跳到主要內容

Blocklet 服務

BlockletService 是一個功能強大的客戶端，作為您的 blocklet 與底層 ABT Node 服務互動的主要介面。它將複雜的 GraphQL 查詢和 HTTP 請求包裝成一個簡潔、基於 promise 的 JavaScript API，從而簡化了使用者管理、工作階段處理、基於角色的存取控制 (RBAC) 和檢索 blocklet 元資料等任務。

此服務對於建構能夠充分利用 Blocklet 平台強大功能的安全且功能豐富的應用程式至關重要。在深入了解此服務之前，建議先理解我們身份驗證指南中涵蓋的概念。

運作原理

您應用程式中的 BlockletService 客戶端與在 ABT 節點上運行的 blocklet-service 進行通訊。所有請求都會使用 blocklet 的憑證自動進行身份驗證，確保對核心功能的安全存取。

Blocklet Service

開始使用

若要使用此服務，只需匯入並實例化它即可。客戶端將根據 Blocklet Server 提供的環境變數自動進行設定。

開始使用

javascript
import BlockletService from '@blocklet/sdk/service/blocklet';

const client = new BlockletService();

async function main() {
  const { user } = await client.getOwner();
  console.log('Blocklet 擁有者:', user.fullName);
}

main();

工作階段管理

login

驗證使用者並啟動一個工作階段。

參數

  • params object (required) — 登入憑證或資料。

傳回值

  • Promise Promise<object> — 一個包含工作階段和使用者資訊的物件。
    • user object — 已驗證使用者的個人資料。
    • token string — 工作階段的存取權杖。
    • refreshToken string — 用於延長工作階段的更新權杖。
    • visitorId string — 訪客/裝置的唯一識別碼。

refreshSession

使用更新權杖來更新過期的工作階段。

參數

  • refreshToken string (required) — 來自先前工作階段的更新權杖。
  • visitorId string — 訪客/裝置的唯一識別碼。

傳回值

  • Promise Promise<object> — 一個包含新工作階段和使用者資訊的物件。
    • user object — 已驗證使用者的個人資料。
    • token string — 新的存取權杖。
    • refreshToken string — 新的更新權杖。
    • provider string — 登入提供者（例如：'wallet'）。

switchProfile

更新使用者的個人資料資訊。

參數

  • did string (required) — 要更新的使用者的 DID。
  • profile object (required) — 一個包含要更新的個人資料欄位的物件。
    • avatar string — 新的頭像 URL。
    • email string — 新的電子郵件地址。
    • fullName string — 新的全名。

傳回值

  • ResponseUser Promise<object> — 一個包含更新後使用者個人資料的物件。

使用者管理

getUser

根據使用者的 DID 檢索單一使用者的個人資料。

參數

  • did string (required) — 要檢索的使用者的唯一 DID。
  • options object — 查詢的可選設定。
    • enableConnectedAccount boolean — 若為 true，則包含使用者已連結帳戶的詳細資訊（例如：OAuth 提供者）。
    • includeTags boolean — 若為 true，則包含與使用者關聯的任何標籤。

傳回值

  • ResponseUser Promise<object> — 一個包含使用者個人資料的物件。
    • user object — 使用者個人資料物件。

getUsers

檢索分頁的使用者列表，支援篩選和排序。

參數

  • args object — 一個包含查詢、排序和分頁選項的物件。
    • paging object — 分頁選項。
      • page number — 要檢索的頁碼。
      • pageSize number — 每頁的使用者數量。
    • query object — 篩選條件。
      • role string — 按使用者角色篩選。
      • approved boolean — 按批准狀態篩選。
      • search string — 用於比對使用者欄位的搜尋字串。
    • sort object — 排序條件。
      • updatedAt number — 按更新時間戳排序。1 為升序，-1 為降序。
      • createdAt number — 按建立時間戳排序。1 為升序，-1 為降序。
      • lastLoginAt number — 按最後登入時間戳排序。1 為升序，-1 為降序。

傳回值

  • ResponseUsers Promise<object> — 一個分頁的使用者物件列表。
    • users TUserInfo[] — 一個使用者個人資料物件的陣列。
    • paging object — 分頁資訊。
      • total number — 使用者總數。
      • pageSize number — 每頁的使用者數量。
      • page number — 目前頁碼。

getUsersCount

取得使用者總數。

傳回值

  • ResponseGetUsersCount Promise<object> — 一個包含使用者總數的物件。
    • count number — 使用者總數。

getUsersCountPerRole

取得每個角色的使用者數量。

傳回值

  • ResponseGetUsersCountPerRole Promise<object> — 一個包含每個角色使用者數量的物件。
    • counts TKeyValue[] — 一個物件陣列，其中每個物件都有一個 key（角色名稱）和 value（使用者數量）。

getOwner

檢索 blocklet 擁有者的個人資料。

傳回值

  • ResponseUser Promise<object> — 一個包含擁有者使用者個人資料的物件。

updateUserApproval

批准或撤銷使用者對 blocklet 的存取權限。

參數

  • did string (required) — 要更新的使用者的 DID。
  • approved boolean (required) — 設定為 true 表示批准，false 表示撤銷。

傳回值

  • ResponseUser Promise<object> — 一個包含更新後使用者個人資料的物件。

updateUserTags

更新與使用者關聯的標籤。

參數

  • args object (required)
    • did string (required) — 使用者的 DID。
    • tags number[] (required) — 一個要與使用者關聯的標籤 ID 陣列。

傳回值

  • ResponseUser Promise<object> — 一個包含更新後使用者個人資料的物件。

updateUserExtra

更新使用者的額外元資料。

參數

  • args object (required)
    • did string (required) — 使用者的 DID。
    • remark string — 關於使用者的備註或說明。
    • extra string — 一個用於儲存自訂資料的 JSON 字串。

傳回值

  • ResponseUser Promise<object> — 一個包含更新後使用者個人資料的物件。

updateUserInfo

更新使用者的一般資訊。需要有效的使用者工作階段 cookie。

參數

  • userInfo object (required) — 一個包含要更新的使用者欄位的物件。必須包含使用者的 did。
  • options object (required) — 請求選項，包含標頭。
    • headers object (required)
      • cookie string (required) — 使用者的工作階段 cookie。

傳回值

  • ResponseUser Promise<object> — 一個包含更新後使用者個人資料的物件。

updateUserAddress

更新使用者的實際地址。需要有效的使用者工作階段 cookie。

參數

  • args object (required) — 一個包含使用者 DID 和地址詳細資訊的物件。
    • did string (required) — 使用者的 DID。
    • address object — 使用者的地址。
      • country string — 國家
      • province string — 州/省
      • city string — 城市
      • postalCode string — 郵遞區號
      • line1 string — 地址第一行
      • line2 string — 地址第二行
  • options object (required) — 請求選項，包含標頭。
    • headers object (required)
      • cookie string (required) — 使用者的工作階段 cookie。

傳回值

  • ResponseUser Promise<object> — 一個包含更新後使用者個人資料的物件。

使用者工作階段

getUserSessions

檢索使用者的有效工作階段列表。

參數

  • args object — 一個包含查詢和分頁選項的物件。
    • paging object — 分頁選項。
    • query object — 篩選條件。
      • userDid string — 按使用者 DID 篩選。
      • status string — 按工作階段狀態篩選。

傳回值

  • ResponseUserSessions Promise<object> — 一個分頁的使用者工作階段列表。
    • list TUserSession[] — 一個工作階段物件的陣列。
    • paging object — 分頁資訊。

getUserSessionsCount

取得使用者工作階段的總數，可選篩選條件。

參數

  • args object — 一個包含查詢選項的物件。
    • query object — 篩選條件。
      • userDid string — 按使用者 DID 篩選。

傳回值

  • ResponseUserSessionsCount Promise<object> — 一個包含工作階段數量的物件。
    • count number — 工作階段總數。

社交與社群

getUserFollowers

檢索正在追蹤特定使用者的使用者列表。需要有效的使用者工作階段 cookie。

參數

  • args object (required) — 查詢選項。
    • userDid string (required) — 要檢索其追蹤者的使用者的 DID。
    • paging object — 分頁選項。
  • options object (required) — 請求選項，包含標頭。
    • headers object (required)
      • cookie string (required) — 使用者的工作階段 cookie。

傳回值

  • ResponseUserFollows Promise<object> — 一個分頁的追蹤者使用者列表。

getUserFollowing

檢索特定使用者正在追蹤的使用者列表。需要有效的使用者工作階段 cookie。

參數

  • args object (required) — 查詢選項。
    • userDid string (required) — 要檢索其追蹤列表的使用者的 DID。
    • paging object — 分頁選項。
  • options object (required) — 請求選項，包含標頭。
    • headers object (required)
      • cookie string (required) — 使用者的工作階段 cookie。

傳回值

  • ResponseUserFollows Promise<object> — 一個分頁的被追蹤使用者列表。

getUserFollowStats

取得使用者的追蹤者和正在追蹤的數量。需要有效的使用者工作階段 cookie。

參數

  • args object (required) — 查詢選項。
    • userDids string[] (required) — 一個使用者 DID 的陣列。
  • options object (required) — 請求選項，包含標頭。
    • headers object (required)
      • cookie string (required) — 使用者的工作階段 cookie。

傳回值

  • ResponseUserRelationCount Promise<object> — 一個包含追蹤者和正在追蹤數量的物件。

checkFollowing

檢查一個使用者是否正在追蹤一個或多個其他使用者。

參數

  • args object (required)
    • followerDid string (required) — 潛在追蹤者的 DID。
    • userDids string[] (required) — 一個要檢查的使用者 DID 陣列。

傳回值

  • ResponseCheckFollowing Promise<object> — 一個物件，其鍵為使用者 DID，值為表示追蹤狀態的布林值。

followUser

讓一個使用者追蹤另一個使用者。

參數

  • args object (required)
    • followerDid string (required) — 正在追蹤的使用者的 DID。
    • userDid string (required) — 要被追蹤的使用者的 DID。

傳回值

  • GeneralResponse Promise<object> — 一個表示成功或失敗的一般回應物件。

unfollowUser

讓一個使用者取消追蹤另一個使用者。

參數

  • args object (required)
    • followerDid string (required) — 正在取消追蹤的使用者的 DID。
    • userDid string (required) — 要被取消追蹤的使用者的 DID。

傳回值

  • GeneralResponse Promise<object> — 一個表示成功或失敗的一般回應物件。

getUserInvites

檢索由特定使用者邀請的使用者列表。需要有效的使用者工作階段 cookie。

參數

  • args object (required) — 查詢選項。
    • userDid string (required) — 邀請者的 DID。
    • paging object — 分頁選項。
  • options object (required) — 請求選項，包含標頭。
    • headers object (required)
      • cookie string (required) — 使用者的工作階段 cookie。

傳回值

  • ResponseUsers Promise<object> — 一個分頁的受邀使用者列表。

標籤管理

getTags

檢索所有可用的使用者標籤列表。

參數

  • args object
    • paging object — 分頁選項。

傳回值

  • ResponseTags Promise<object> — 一個分頁的標籤物件列表。
    • tags TTag[] — 一個標籤物件的陣列。
    • paging object — 分頁資訊。

createTag

建立一個新的使用者標籤。

參數

  • args object (required)
    • tag object (required)
      • title string (required) — 標籤的標題。
      • description string — 標籤的描述。
      • color string — 標籤的十六進位顏色代碼。

傳回值

  • ResponseTag Promise<object> — 一個包含新建立標籤的物件。

updateTag

更新現有的使用者標籤。

參數

  • args object (required)
    • tag object (required)
      • id number (required) — 要更新的標籤 ID。
      • title string — 新的標題。
      • description string — 新的描述。
      • color string — 新的顏色。

傳回值

  • ResponseTag Promise<object> — 一個包含更新後標籤的物件。

deleteTag

刪除一個使用者標籤。

參數

  • args object (required)
    • tag object (required)
      • id number (required) — 要刪除的標籤 ID。

傳回值

  • ResponseTag Promise<object> — 一個包含已刪除標籤的物件。

基於角色的存取控制 (RBAC)

getRoles

檢索所有可用角色的列表。

傳回值

  • ResponseRoles Promise<object> — 一個包含角色列表的物件。
    • roles TRole[] — 一個角色物件的陣列。

getRole

根據名稱檢索單一角色。

參數

  • name string (required) — 角色的唯一名稱。

傳回值

  • ResponseRole Promise<object> — 一個包含角色詳細資訊的物件。

createRole

建立一個新角色。

參數

  • args object (required)
    • name string (required) — 角色的唯一識別碼（例如：editor）。
    • title string (required) — 人類可讀的標題（例如：內容編輯器）。
    • description string — 對角色用途的簡要描述。

傳回值

  • ResponseRole Promise<object> — 一個包含新建立角色的物件。

updateRole

更新現有角色。

參數

  • name string (required) — 要更新的角色名稱。
  • updates object (required) — 一個包含要更新欄位的物件。
    • title string — 新的標題。
    • description string — 新的描述。

傳回值

  • ResponseRole Promise<object> — 一個包含更新後角色的物件。

deleteRole

刪除一個角色。

參數

  • name string (required) — 要刪除的角色名稱。

傳回值

  • GeneralResponse Promise<object> — 一個表示成功或失敗的一般回應物件。

getPermissions

檢索所有可用權限的列表。

傳回值

  • ResponsePermissions Promise<object> — 一個包含權限列表的物件。
    • permissions TPermission[] — 一個權限物件的陣列。

getPermissionsByRole

檢索授予特定角色的所有權限。

參數

  • role string (required) — 角色的名稱。

傳回值

  • ResponsePermissions Promise<object> — 一個包含該角色權限列表的物件。

createPermission

建立一個新權限。

參數

  • args object (required)
    • name string (required) — 權限的唯一名稱（例如：post:create）。
    • description string — 描述該權限允許的操作。

傳回值

  • ResponsePermission Promise<object> — 一個包含新建立權限的物件。

updatePermission

更新現有權限。

參數

  • name string (required) — 要更新的權限名稱。
  • updates object (required)
    • description string — 權限的新描述。

傳回值

  • ResponsePermission Promise<object> — 一個包含更新後權限的物件。

deletePermission

刪除一個權限。

參數

  • name string (required) — 要刪除的權限名稱。

傳回值

  • GeneralResponse Promise<object> — 一個表示成功或失敗的一般回應物件。

grantPermissionForRole

將一個權限指派給一個角色。

參數

  • role string (required) — 角色的名稱。
  • permission string (required) — 要授予的權限名稱。

傳回值

  • GeneralResponse Promise<object> — 一個表示成功或失敗的一般回應物件。

revokePermissionFromRole

從一個角色中撤銷一個權限。

參數

  • role string (required) — 角色的名稱。
  • permission string (required) — 要撤銷的權限名稱。

傳回值

  • GeneralResponse Promise<object> — 一個表示成功或失敗的一般回應物件。

updatePermissionsForRole

用一組新的權限取代角色的所有現有權限。

參數

  • role string (required) — 角色的名稱。
  • permissions string[] (required) — 一個要為該角色設定的權限名稱陣列。

傳回值

  • ResponseRole Promise<object> — 一個包含更新後角色的物件。

hasPermission

檢查一個角色是否具有特定權限。

參數

  • role string (required) — 要檢查的角色名稱。
  • permission string (required) — 要驗證的權限名稱。

傳回值

  • BooleanResponse Promise<object> — 一個帶有布林值 result 屬性的物件。
    • result boolean — 若角色具有該權限，則為 true，否則為 false。

Passport 管理

issuePassportToUser

向使用者發行一個新的 passport，並為他們指派一個角色。

參數

  • args object (required)
    • userDid string (required) — 接收 passport 的使用者的 DID。
    • role string (required) — 要透過此 passport 指派的角色。

傳回值

  • ResponseUser Promise<object> — 一個包含更新後使用者個人資料的物件，包括新的 passport。

enableUserPassport

為使用者啟用一個先前被撤銷的 passport。

參數

  • args object (required)
    • userDid string (required) — 使用者的 DID。
    • passportId string (required) — 要啟用的 passport 的 ID。

傳回值

  • ResponseUser Promise<object> — 一個包含更新後使用者個人資料的物件。

revokeUserPassport

撤銷使用者的 passport。

參數

  • args object (required)
    • userDid string (required) — 使用者的 DID。
    • passportId string (required) — 要撤銷的 passport 的 ID。

傳回值

  • ResponseUser Promise<object> — 一個包含更新後使用者個人資料的物件。

removeUserPassport

永久移除使用者的 passport。

參數

  • args object (required)
    • userDid string (required) — 使用者的 DID。
    • passportId string (required) — 要移除的 passport 的 ID。

傳回值

  • GeneralResponse Promise<object> — 一個表示成功或失敗的一般回應物件。

Blocklet 與元件資訊

getBlocklet

檢索目前 blocklet 的元資料和狀態。

參數

  • attachRuntimeInfo boolean (default: false) — 若為 true，則包含執行階段資訊，如 CPU 和記憶體使用情況。
  • useCache boolean (default: true) — 若為 false，則繞過快取以擷取最新資料。

傳回值

  • ResponseBlocklet Promise<object> — 一個包含 blocklet 狀態和元資料的物件。

getComponent

透過其 DID 檢索目前 blocklet 中特定元件的狀態。

參數

  • did string (required) — 要檢索的元件的 DID。

傳回值

  • ComponentState Promise<object> — 一個包含元件狀態和元資料的物件。

getTrustedDomains

檢索用於聯合登入的受信任網域列表。

傳回值

  • string[] Promise<string[]> — 一個受信任網域 URL 的陣列。

getVault

檢索並驗證 blocklet 的 vault 資訊。

傳回值

  • vault Promise<string> — 如果驗證成功，則為 vault 字串。

clearCache

根據模式清除節點上的快取資料。

參數

  • args object
    • pattern string — 一個用於比對快取鍵以進行移除的模式。

傳回值

  • ResponseClearCache Promise<object> — 一個包含已移除快取鍵列表的物件。
    • removed string[] — 一個從快取中移除的鍵的陣列。

存取金鑰管理

createAccessKey

為程式化存取建立一個新的存取金鑰。

參數

  • params object (required)
    • remark string — 存取金鑰的描述。
    • passport string — 要與金鑰關聯的角色/passport。預設為 'guest'。

傳回值

  • ResponseCreateAccessKey Promise<object> — 一個包含新建立的存取金鑰和密鑰的物件。

getAccessKey

檢索單一存取金鑰的詳細資訊。

參數

  • params object (required)
    • accessKeyId string (required) — 要檢索的存取金鑰 ID。

傳回值

  • ResponseAccessKey Promise<object> — 一個包含存取金鑰詳細資訊的物件。

getAccessKeys

檢索存取金鑰列表。

參數

  • params object
    • paging object — 分頁選項。

傳回值

  • ResponseAccessKeys Promise<object> — 一個分頁的存取金鑰物件列表。

verifyAccessKey

驗證存取金鑰是否有效。

參數

  • params object (required)
    • accessKeyId string (required) — 要驗證的存取金鑰 ID。

傳回值

  • ResponseAccessKey Promise<object> — 如果有效，則為一個包含存取金鑰詳細資訊的物件。

在掌握 BlockletService 後，您可能會想探索如何向您的使用者傳送訊息。請前往通知服務指南以了解更多資訊。