用户与访问管理

本节提供了在 Blocklet Server 中管理用户、角色、权限、会话和访问密钥相关查询的详细参考。这些查询允许您检索有关应用程序用户及其访问级别的信息。

对于修改用户和访问数据的操作，例如创建用户或更新权限，请参阅用户与访问管理变更文档。

用户查询

getUsers

检索分页的用户列表，可进行筛选和排序。

参数

input RequestUsersInput (required) — 包含查询参数的对象。
- teamDid string (required) — Blocklet 或团队的 DID。
- query UserQueryInput — 用户列表的筛选条件。
- sort UserSortInput — 用户列表的排序条件。
- paging PagingInput — 分页选项。
- dids string[] — 要专门检索的用户 DID 数组。

**** ResponseUsers — 包含用户列表和分页信息的对象。
- users UserInfo[] — 用户对象数组。
- paging Paging — 结果集的分页信息。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchUsers() {
  try {
    const { users, paging } = await client.getUsers({
      input: {
        teamDid: 'z1...',
        paging: { page: 1, pageSize: 10 },
        query: {
          role: 'guest',
          approved: true,
          search: 'john.doe',
        },
        sort: {
          lastLoginAt: -1, // 按最后登录时间降序排序
        },
      },
    });
    console.log('获取到的用户:', users);
    console.log('分页信息:', paging);
  } catch (error) {
    console.error('获取用户时出错:', error);
  }
}

fetchUsers();

示例响应

{
  "code": "ok",
  "users": [
    {
      "did": "z8ia...",
      "pk": "...",
      "role": "guest",
      "avatar": "/path/to/avatar.png",
      "fullName": "John Doe",
      "email": "john.doe@example.com",
      "approved": true,
      "createdAt": 1672531200,
      "lastLoginAt": 1675209600
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 10,
    "total": 1,
    "pageCount": 1
  }
}

getUser

通过用户的 DID 检索单个用户的详细信息。

参数

input RequestTeamUserInput (required) — 包含查询参数的对象。
- teamDid string (required) — Blocklet 或团队的 DID。
- user UserInfoInput (required) — 包含用户 DID 的对象。只需 did 字段。
  - did string (required)
- options RequestTeamUserOptionsInput — 用于包含额外相关数据的可选标志。
  - includeTags boolean — 是否包含用户的标签。
  - includePassports boolean — 是否包含用户的通行证。
  - includeConnectedAccounts boolean — 是否包含用户的关联账户。

user UserInfo — 请求的用户对象。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchUser(userDid) {
  try {
    const { user } = await client.getUser({
      input: {
        teamDid: 'z1...',
        user: { did: userDid },
        options: {
          includePassports: true,
          includeTags: true,
        },
      },
    });
    console.log('用户详情:', user);
  } catch (error) {
    console.error('获取用户时出错:', error);
  }
}

fetchUser('z8ia...'); // 替换为有效的用户 DID

示例响应

{
  "code": "ok",
  "user": {
    "did": "z8ia...",
    "fullName": "Jane Doe",
    "email": "jane.doe@example.com",
    "role": "admin",
    "approved": true,
    "passports": [],
    "tags": []
  }
}

getUsersCount

检索特定团队或 Blocklet 的用户总数。

参数

input TeamInput (required) — 包含团队 DID 的对象。
- teamDid string (required)

count number — 用户总数。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function countUsers() {
  try {
    const { count } = await client.getUsersCount({
      input: { teamDid: 'z1...' },
    });
    console.log('用户总数:', count);
  } catch (error) {
    console.error('统计用户时出错:', error);
  }
}

countUsers();

示例响应

{
  "code": "ok",
  "count": 125
}

getUsersCountPerRole

检索团队或 Blocklet 中每个角色的用户数。

参数

input TeamInput (required) — 包含团队 DID 的对象。
- teamDid string (required)

counts KeyValue[] — 一个对象数组，其中每个对象的 key 是角色名称，value 是数量。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function countUsersByRole() {
  try {
    const { counts } = await client.getUsersCountPerRole({
      input: { teamDid: 'z1...' },
    });
    console.log('各角色用户数:', counts);
  } catch (error) {
    console.error('按角色统计用户时出错:', error);
  }
}

countUsersByRole();

示例响应

{
  "code": "ok",
  "counts": [
    { "key": "owner", "value": 1 },
    { "key": "admin", "value": 5 },
    { "key": "member", "value": 119 }
  ]
}

getOwner

检索 Blocklet 或团队所有者的用户信息。

参数

input TeamInput (required) — 包含团队 DID 的对象。
- teamDid string (required)

user UserInfo — 所有者的用户对象。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchOwner() {
  try {
    const { user } = await client.getOwner({
      input: { teamDid: 'z1...' },
    });
    console.log('所有者信息:', user);
  } catch (error) {
    console.error('获取所有者时出错:', error);
  }
}

fetchOwner();

示例响应

{
  "code": "ok",
  "user": {
    "did": "zNK...",
    "fullName": "Node Owner",
    "email": "owner@example.com",
    "role": "owner"
  }
}

destroySelf

允许用户在特定 Blocklet 内删除自己的账户。此操作不可逆。

参数

input RequestTeamUserInput (required) — 包含用户自我销毁详细信息的对象。
- teamDid string (required) — Blocklet 或团队的 DID。
- user UserInfoInput (required) — 包含用户 DID 的对象。只需 did 字段。
  - did string (required)

user UserInfo — 被删除账户的用户对象。

示例

import BlockletServerClient from '@blocklet/server-js';

// 假设客户端已作为要删除的用户进行身份验证
const client = new BlockletServerClient();

async function deleteMyAccount(userDid) {
  try {
    const { user } = await client.destroySelf({
      input: {
        teamDid: 'z1...',
        user: { did: userDid },
      },
    });
    console.log('用户账户已删除:', user.did);
  } catch (error) {
    console.error('删除账户时出错:', error);
  }
}

deleteMyAccount('z8ia...'); // 当前已验证用户的 DID

示例响应

{
  "code": "ok",
  "user": {
    "did": "z8ia...",
    "fullName": "Former User"
  }
}

用户社交查询

getUserFollowers

检索正在关注指定用户的用户列表。

参数

input RequestUserRelationQueryInput (required)
- teamDid string (required)
- userDid string (required)
- paging PagingInput
- options QueryUserFollowOptionsInput

**** ResponseUserFollows
- data UserFollows[]
- paging Paging

getUserFollowing

检索指定用户正在关注的用户列表。

参数

input RequestUserRelationQueryInput (required)
- teamDid string (required)
- userDid string (required)
- paging PagingInput
- options QueryUserFollowOptionsInput

**** ResponseUserFollows
- data UserFollows[]
- paging Paging

getUserFollowStats

检索一个或多个用户的关注相关统计信息，例如关注者和正在关注的数量。

参数

input RequestUserRelationCountInput (required)
- teamDid string (required)
- userDids string[] (required)
- options QueryUserFollowStateOptionsInput

data any — 包含关注统计信息的对象。

checkFollowing

检查特定用户是否正在关注一个或多个其他用户。

参数

input RequestCheckFollowingInput (required)
- teamDid string (required)
- followerDid string (required) — 可能正在关注其他用户的用户的 DID。
- userDids string[] (required) — 用于检查是否被关注的 DID 数组。

data any — 一个对象，其中键是 userDids，值是表示关注状态的布尔值。

getUserInvites

检索由特定用户邀请的用户列表。

参数

input RequestUserRelationQueryInput (required)
- teamDid string (required)
- userDid string (required) — 邀请者的 DID。
- paging PagingInput

**** ResponseUsers — 包含受邀用户列表和分页信息的对象。
- users UserInfo[]
- paging Paging

角色与权限

getRoles

检索团队或 Blocklet 中所有可用角色的列表。

参数

input TeamInput (required) — 包含团队 DID 的对象。
- teamDid string (required)

roles Role[] — 角色对象数组。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchRoles() {
  try {
    const { roles } = await client.getRoles({
      input: { teamDid: 'z1...' },
    });
    console.log('可用角色:', roles);
  } catch (error) {
    console.error('获取角色时出错:', error);
  }
}

fetchRoles();

示例响应

{
  "code": "ok",
  "roles": [
    { "name": "owner", "title": "Owner", "description": "Full access to all resources." },
    { "name": "admin", "title": "Administrator", "description": "Can manage users and settings." },
    { "name": "member", "title": "Member", "description": "Standard user access." },
    { "name": "guest", "title": "Guest", "description": "Limited access." }
  ]
}

getRole

通过名称检索特定角色的详细信息。

参数

input RequestTeamRoleInput (required) — 包含团队 DID 和角色名称的对象。
- teamDid string (required)
- role RoleUpdateInput (required)
  - name string (required)

role Role — 请求的角色对象。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchRoleDetails(roleName) {
  try {
    const { role } = await client.getRole({
      input: {
        teamDid: 'z1...',
        role: { name: roleName },
      },
    });
    console.log('角色详情:', role);
  } catch (error) {
    console.error('获取角色详情时出错:', error);
  }
}

fetchRoleDetails('admin');

示例响应

{
  "code": "ok",
  "role": {
    "name": "admin",
    "title": "Administrator",
    "description": "Can manage users and settings.",
    "grants": ["user:create", "user:update", "setting:update"]
  }
}

getPermissions

检索团队或 Blocklet 中所有可用权限的列表。

参数

input TeamInput (required) — 包含团队 DID 的对象。
- teamDid string (required)

permissions Permission[] — 权限对象数组。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchPermissions() {
  try {
    const { permissions } = await client.getPermissions({
      input: { teamDid: 'z1...' },
    });
    console.log('可用权限:', permissions);
  } catch (error) {
    console.error('获取权限时出错:', error);
  }
}

fetchPermissions();

示例响应

{
  "code": "ok",
  "permissions": [
    { "name": "user:create", "description": "Allows creating new users." },
    { "name": "user:read", "description": "Allows viewing user profiles." },
    { "name": "post:publish", "description": "Allows publishing new posts." }
  ]
}

getPermissionsByRole

检索与特定角色关联的权限列表。

参数

input RequestTeamRoleInput (required) — 包含团队 DID 和角色名称的对象。
- teamDid string (required)
- role RoleUpdateInput (required)
  - name string (required)

permissions Permission[] — 与该角色关联的权限对象数组。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchRolePermissions(roleName) {
  try {
    const { permissions } = await client.getPermissionsByRole({
      input: {
        teamDid: 'z1...',
        role: { name: roleName },
      },
    });
    console.log(`角色 '${roleName}' 的权限:`, permissions);
  } catch (error) {
    console.error('获取角色权限时出错:', error);
  }
}

fetchRolePermissions('member');

示例响应

{
  "code": "ok",
  "permissions": [
    { "name": "post:create", "description": "Allows creating new posts." },
    { "name": "post:read", "description": "Allows reading posts." }
  ]
}

邀请与访问密钥

getInvitations

检索团队或 Blocklet 的所有待处理邀请列表。

参数

input TeamInput (required) — 包含团队 DID 的对象。
- teamDid string (required)

invitations InviteInfo[] — 邀请对象数组。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchInvitations() {
  try {
    const { invitations } = await client.getInvitations({
      input: { teamDid: 'z1...' },
    });
    console.log('待处理邀请:', invitations);
  } catch (error) {
    console.error('获取邀请时出错:', error);
  }
}

fetchInvitations();

示例响应

{
  "code": "ok",
  "invitations": [
    {
      "inviteId": "...",
      "role": "member",
      "remark": "Invitation for new developer",
      "expireDate": "2024-12-31T23:59:59Z",
      "inviter": {
        "did": "z8ia...",
        "fullName": "Admin User"
      }
    }
  ]
}

getAccessKeys

检索与团队或 Blocklet 关联的访问密钥列表。

参数

input RequestAccessKeysInput (required) — 包含用于筛选访问密钥的查询参数的对象。
- teamDid string (required)
- paging PagingInput
- remark string
- componentDid string
- resourceType string
- resourceId string

**** ResponseAccessKeys
- list AccessKey[] — 访问密钥对象数组。
- paging Paging — 分页信息。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchAccessKeys() {
  try {
    const { list } = await client.getAccessKeys({
      input: {
        teamDid: 'z1...',
        paging: { pageSize: 20 },
      },
    });
    console.log('访问密钥:', list);
  } catch (error) {
    console.error('获取访问密钥时出错:', error);
  }
}

fetchAccessKeys();

示例响应

{
  "code": "ok",
  "list": [
    {
      "accessKeyId": "...",
      "remark": "CI/CD Key",
      "createdAt": 1672531200,
      "lastUsedAt": 1675209600
    }
  ],
  "paging": {
    "total": 1,
    "pageSize": 20,
    "page": 1
  }
}

getAccessKey

通过 ID 检索单个访问密钥的详细信息。

参数

input RequestAccessKeyInput (required) — 包含团队 DID 和访问密钥 ID 的对象。
- teamDid string (required)
- accessKeyId string (required)

data AccessKey — 请求的访问密钥对象。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchAccessKey(keyId) {
  try {
    const { data } = await client.getAccessKey({
      input: {
        teamDid: 'z1...',
        accessKeyId: keyId,
      },
    });
    console.log('访问密钥详情:', data);
  } catch (error) {
    console.error('获取访问密钥时出错:', error);
  }
}

fetchAccessKey('...'); // 替换为有效的访问密钥 ID

示例响应

{
  "code": "ok",
  "data": {
    "accessKeyId": "...",
    "accessKeyPublic": "...",
    "remark": "API access for integration tests",
    "createdAt": 1672531200
  }
}

会话

getSession

通过 ID 检索特定会话的详细信息。

参数

input RequestGetSessionInput (required) — 包含会话 ID 的对象。
- id string (required)

session any — 请求的会话对象。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchSession(sessionId) {
  try {
    const { session } = await client.getSession({
      input: { id: sessionId },
    });
    console.log('会话详情:', session);
  } catch (error) {
    console.error('获取会话时出错:', error);
  }
}

fetchSession('...'); // 替换为有效的会话 ID

示例响应

{
  "code": "ok",
  "session": {
    "sessionId": "...",
    "userDid": "z8ia...",
    "status": "active",
    "createdAt": 1675209600
  }
}

getUserSessions

检索特定用户的会话分页列表。

参数

input RequestUserSessionsInput (required) — 包含用户会话查询参数的对象。
- teamDid string (required)
- query UserSessionQueryInput
  - userDid string (required)
- paging PagingInput

**** ResponseUserSessions
- list UserSession[] — 会话对象数组。
- paging Paging — 分页信息。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchUserSessions(userDid) {
  try {
    const { list, paging } = await client.getUserSessions({
      input: {
        teamDid: 'z1...',
        query: { userDid: userDid },
        paging: { pageSize: 5 },
      },
    });
    console.log('用户会话:', list);
  } catch (error) {
    console.error('获取用户会话时出错:', error);
  }
}

fetchUserSessions('z8ia...');

示例响应

{
  "code": "ok",
  "list": [
    {
      "id": "...",
      "userDid": "z8ia...",
      "status": "active",
      "lastLoginIp": "192.168.1.1",
      "createdAt": 1675209600
    }
  ],
  "paging": {
    "total": 1,
    "pageSize": 5,
    "page": 1
  }
}

getUserSessionsCount

检索特定用户的会话总数。

参数

input RequestUserSessionsCountInput (required) — 包含用于统计用户会话的查询参数的对象。
- teamDid string (required)
- query UserSessionQueryInput
  - userDid string (required)

count number — 该用户的会话总数。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function countUserSessions(userDid) {
  try {
    const { count } = await client.getUserSessionsCount({
      input: {
        teamDid: 'z1...',
        query: { userDid: userDid },
      },
    });
    console.log('用户的会话总数:', count);
  } catch (error) {
    console.error('统计用户会话时出错:', error);
  }
}

countUserSessions('z8ia...');

示例响应

{
  "code": "ok",
  "count": 5
}

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchTags() {
  try {
    const { tags } = await client.getTags({
      input: {
        teamDid: 'z1...',
        paging: { pageSize: 100 },
      },
    });
    console.log('可用标签:', tags);
  } catch (error) {
    console.error('获取标签时出错:', error);
  }
}

fetchTags();

示例响应

{
  "code": "ok",
  "tags": [
    {
      "id": 1,
      "title": "Developer",
      "description": "Users with development access",
      "color": "#3498db"
    }
  ],
  "paging": {
    "total": 1,
    "pageSize": 100,
    "page": 1
  }
}