使用者與存取管理

本節提供在 Blocklet Server 中管理使用者、角色、權限、工作階段和存取金鑰的相關查詢的詳細參考。這些查詢可讓您檢索有關應用程式使用者及其存取級別的資訊。

對於修改使用者和存取資料的操作，例如建立使用者或更新權限，請參考使用者與存取管理 Mutations 文件。

使用者查詢

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('Fetched users:', users);
    console.log('Pagination info:', paging);
  } catch (error) {
    console.error('Error fetching users:', 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 — 是否包含使用者的 passports。
  - 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 details:', user);
  } catch (error) {
    console.error('Error fetching user:', 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('Total users:', count);
  } catch (error) {
    console.error('Error counting users:', 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('User counts per role:', counts);
  } catch (error) {
    console.error('Error counting users by role:', 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('Owner info:', user);
  } catch (error) {
    console.error('Error fetching owner:', 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 account deleted:', user.did);
  } catch (error) {
    console.error('Error deleting account:', 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('Available roles:', roles);
  } catch (error) {
    console.error('Error fetching roles:', 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 details:', role);
  } catch (error) {
    console.error('Error fetching role details:', 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('Available permissions:', permissions);
  } catch (error) {
    console.error('Error fetching permissions:', 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(`Permissions for role '${roleName}':`, permissions);
  } catch (error) {
    console.error('Error fetching role permissions:', 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('Pending invitations:', invitations);
  } catch (error) {
    console.error('Error fetching invitations:', 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('Access keys:', list);
  } catch (error) {
    console.error('Error fetching access keys:', 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('Access key details:', data);
  } catch (error) {
    console.error('Error fetching access key:', 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 details:', session);
  } catch (error) {
    console.error('Error fetching session:', 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('User sessions:', list);
  } catch (error) {
    console.error('Error fetching user sessions:', 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('Total sessions for user:', count);
  } catch (error) {
    console.error('Error counting user sessions:', 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('Available tags:', tags);
  } catch (error) {
    console.error('Error fetching tags:', error);
  }
}

fetchTags();

範例回應

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

使用者查詢

getUsers

getUser

getUsersCount

getUsersCountPerRole

getOwner

destroySelf

使用者社交查詢

getUserFollowers

getUserFollowing

getUserFollowStats

checkFollowing

getUserInvites

角色與權限

getRoles

getRole

getPermissions

getPermissionsByRole

邀請與存取金鑰

getInvitations

getAccessKeys

getAccessKey

工作階段

getSession

getUserSessions

getUserSessionsCount

標籤

getTags