跳到主要内容

Blocklet 服务

BlockletService 是一个功能强大的客户端，作为您的 blocklet 与底层 ABT Node 服务交互的主要接口。它将复杂的 GraphQL 查询和 HTTP 请求封装成一个简洁的、基于 promise 的 JavaScript API，从而简化了用户管理、会话处理、基于角色的访问控制 (RBAC) 和检索 blocklet 元数据等任务。

该服务对于构建利用 Blocklet 平台全部功能的、安全且功能丰富的应用程序至关重要。在深入了解此服务之前，建议先理解我们的身份验证指南中涵盖的概念。

工作原理

您应用程序中的 BlockletService 客户端与在 ABT Node 上运行的 blocklet-service 进行通信。所有请求都使用 blocklet 的凭据自动进行身份验证，以确保对核心功能的安全访问。

Blocklet Service

开始使用

要使用该服务，只需导入并实例化它即可。客户端将根据 Blocklet Server 提供的环境变量自动配置。

Getting Started

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 — 地址行 1
      • line2 string — 地址行 2
  • 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) — 一个人类可读的标题（例如，Content Editor）。
    • 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。

通行证管理

issuePassportToUser

向用户颁发一个新的通行证，并为其分配一个角色。

参数

  • args object (required)
    • userDid string (required) — 接收通行证的用户的 DID。
    • role string (required) — 通过此通行证分配的角色。

返回

  • ResponseUser Promise<object> — 一个包含更新后用户个人资料的对象，包括新的通行证。

enableUserPassport

为用户启用先前已撤销的通行证。

参数

  • args object (required)
    • userDid string (required) — 用户的 DID。
    • passportId string (required) — 要启用的通行证的 ID。

返回

  • ResponseUser Promise<object> — 一个包含更新后用户个人资料的对象。

revokeUserPassport

撤销用户的通行证。

参数

  • args object (required)
    • userDid string (required) — 用户的 DID。
    • passportId string (required) — 要撤销的通行证的 ID。

返回

  • ResponseUser Promise<object> — 一个包含更新后用户个人资料的对象。

removeUserPassport

永久移除用户的通行证。

参数

  • args object (required)
    • userDid string (required) — 用户的 DID。
    • passportId string (required) — 要移除的通行证的 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 Promise<string> — 验证成功后的保险库字符串。

clearCache

根据模式清除节点上的缓存数据。

参数

  • args object
    • pattern string — 用于匹配要删除的缓存键的模式。

返回

  • ResponseClearCache Promise<object> — 一个包含已删除缓存键列表的对象。
    • removed string[] — 从缓存中删除的键的数组。

访问密钥管理

createAccessKey

为程序化访问创建一个新的访问密钥。

参数

  • params object (required)
    • remark string — 访问密钥的描述。
    • passport string — 与密钥关联的角色/通行证。默认为 '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 后，您可能想探索如何向用户发送消息。请前往通知服务指南了解更多信息。