权限管理

版本提示

自 v5.0.0 起新增此模块。

@cloudbase/manager-node 提供 PermissionService，通过 app.permission 访问，支持两大功能：

资源权限管理：设置和查询云函数、数据库、存储等资源的访问权限
角色管理：创建/查询/修改/删除用户角色（RBAC），并为角色绑定网关访问策略

modifyResourcePermission

1. 接口描述

接口功能：设置指定资源的访问权限

接口声明：app.permission.modifyResourcePermission(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
resourceType	是	`PermissionResourceType`	资源类型，取值：`function` / `storage` / `table` / `collection`
resource	否	String	资源名称（如函数名、集合名）。当 `resourceType` 为 `function` 时可不传
permission	是	`BasePermission`	权限类型（见下表）
securityRule	否	String	自定义安全规则 JSON 字符串，仅 `permission = 'CUSTOM'` 时传入

权限类型（BasePermission）

table / collection

值	说明
`READONLY`	读取全部数据，修改本人数据
`PRIVATE`	读取和修改本人数据
`ADMINWRITE`	读取全部数据，不可修改数据
`ADMINONLY`	无权限
`CUSTOM`	自定义安全规则（仅 `collection` 支持）

storage

值	说明
`READONLY`	所有用户可读，仅创建者和管理员可写
`PRIVATE`	仅创建者及管理员可读写
`ADMINWRITE`	所有用户可读，仅管理员可写
`ADMINONLY`	仅管理员可读写
`CUSTOM`	自定义安全规则

function

值	说明
`CUSTOM`	自定义安全规则

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识
Data.Success	Boolean	是否设置成功

4. 示例代码

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

async function test() {
  // 设置数据库集合为仅管理员可读写
  await app.permission.modifyResourcePermission({
    resourceType: 'collection',
    resource: 'my-collection',
    permission: 'ADMINONLY'
  })

  // 设置自定义安全规则
  await app.permission.modifyResourcePermission({
    resourceType: 'collection',
    resource: 'user-data',
    permission: 'CUSTOM',
    securityRule: JSON.stringify({
      read: 'auth.uid == doc.uid',
      write: 'auth.uid == doc.uid'
    })
  })
}

test()

describeResourcePermission

1. 接口描述

接口功能：查询指定资源的当前访问权限

接口声明：app.permission.describeResourcePermission(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
resourceType	是	`PermissionResourceType`	资源类型：`function` / `storage` / `table` / `collection`
resources	否	`string[]`	资源名称列表，云函数不传或传空数组、云存储传存储桶名、数据库表传表名，不能超过100条。

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识
Data.TotalCount	Number	总条数
Data.PermissionList	`ResourcePermission[]`	权限列表

ResourcePermission

字段	类型	说明
ResourceType	String	资源类型
Resource	String	资源名称
Permission	String	当前权限值
SecurityRule	String	自定义安全规则（CUSTOM 时有值）

角色管理适用于企业内部多人协作、网关 API 访问控制等场景，支持为角色绑定腾讯云网关策略。

createRole

1. 接口描述

接口功能：创建用户角色

接口声明：app.permission.createRole(options): Promise<CreateRoleResp>

2. 输入参数

字段	必填	类型	说明
roleName	是	String	角色名称
roleIdentity	是	String	角色唯一标识符（英文，创建后不可修改）
description	否	String	角色描述
memberUids	否	`string[]`	初始成员 UID 列表
policies	否	`PermissionPolicyItem[]`	绑定的权限策略列表

PermissionPolicyItem

当前 ResourceType 仅支持 gateway。

字段	必填	类型	说明
ResourceType	是	String	资源类型，当前仅支持 `gateway`
Resource	是	String	资源标识符。传预设策略时填预设策略字符串；传自定义策略时与 `GatewayPolicyCode` 保持一致
Effect	是	String	效果：`allow`（允许）或 `deny`（拒绝）
GatewayPolicyCode	是	String	网关策略编码。传预设策略时填预设策略字符串；传自定义策略时与 `Resource` 保持一致
GatewayPolicyName	否	String	网关策略名称
GatewayPolicyDescription	否	String	网关策略描述
GatewayPolicyExpression	否	String	网关策略表达式 JSON 字符串

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识
Data.RoleId	String	创建的角色 ID
Data.MemberUids	`string[]`	添加的成员 UID 列表
Data.Policies	`PermissionPolicyItem[]`	绑定的策略列表

4. 示例代码

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

async function test() {
  const result = await app.permission.createRole({
    roleName: '只读运营',
    roleIdentity: 'read-only-operator',
    description: '运营人员只读角色',
    policies: [
      { ResourceType: 'gateway', Resource: 'FunctionsAccess', Effect: 'allow', GatewayPolicyCode: 'FunctionsAccess' }
    ]
  })
  console.log('创建角色 ID:', result.RoleId)
}

test()

describeRoleList

1. 接口描述

接口功能：查询角色列表，支持按角色 ID、标识、名称筛选

接口声明：app.permission.describeRoleList(options?): Promise<DescribeRoleListResp>

2. 输入参数

字段	必填	类型	说明
pageNumber	否	Number	页码，默认 1
pageSize	否	Number	每页条数，默认 20
roleId	否	String	按角色 ID 精确查询
roleIdentity	否	String	按角色唯一标识查询
roleName	否	String	按角色名称模糊查询
loadDetails	否	Boolean	是否返回成员和策略详情，默认 false

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识
Data.TotalCount	Number	系统角色总数
Data.CustomTotalCount	Number	自定义角色总数
Data.SystemRoles	`RoleItem[]`	系统预置角色列表
Data.CustomRoles	`RoleItem[]`	自定义角色列表

RoleItem

字段	类型	说明
RoleId	String	角色 ID
RoleIdentity	String	角色唯一标识
RoleName	String	角色名称
RoleType	String	类型：`system` / `custom`
Description	String	角色描述
Members	`MemberInfo[]`	成员列表（loadDetails=true 时返回）
Policies	`PermissionPolicyItem[]`	策略列表（loadDetails=true 时返回）

modifyRole

1. 接口描述

接口功能：修改角色信息，支持更新名称、描述、成员、策略

接口声明：app.permission.modifyRole(options): Promise<ModifyRoleResp>

2. 输入参数

字段	必填	类型	说明
roleId	是	String	要修改的角色 ID
roleName	否	String	新的角色名称
description	否	String	新的角色描述
addMemberUids	否	`string[]`	新增成员 UID 列表
removeMemberUids	否	`string[]`	移除成员 UID 列表
addPolicies	否	`PermissionPolicyItem[]`	新增策略列表
removePolicies	否	`PermissionPolicyItem[]`	移除策略列表

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识
Data.Success	Boolean	是否修改成功
Data.AddedMemberUids	`string[]`	实际添加的成员
Data.RemovedMemberUids	`string[]`	实际移除的成员
Data.AddedPolicies	`PermissionPolicyItem[]`	实际添加的策略
Data.RemovedPolicies	`PermissionPolicyItem[]`	实际移除的策略

deleteRoles

1. 接口描述

接口功能：批量删除角色

接口声明：app.permission.deleteRoles(options): Promise<DeleteRolesResp>

2. 输入参数

字段	必填	类型	说明
roleIds	是	`string[]`	要删除的角色 ID 列表

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识
Data.SuccessCount	Number	删除成功数量
Data.FailedCount	Number	删除失败数量

4. 示例代码

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

async function test() {
  // 查询所有自定义角色
  const { CustomRoles } = await app.permission.describeRoleList({
    loadDetails: true
  })
  console.log('自定义角色数量：', CustomRoles?.length)
  
  // 修改角色：添加新成员
  await app.permission.modifyRole({
    roleId: 'role-123',
    addMemberUids: ['uid-456'],
    roleName: '运营管理员（更新）'
  })

  // 删除角色
  const res = await app.permission.deleteRoles({
    roleIds: ['role-123', 'role-456']
  })
  console.log(`删除成功 ${res.SuccessCount} 个角色`)
}

test()

权限管理

modifyResourcePermission​

1. 接口描述​

2. 输入参数​

权限类型（BasePermission）​

3. 返回结果​

4. 示例代码​

describeResourcePermission​

1. 接口描述​

2. 输入参数​

3. 返回结果​

ResourcePermission​

createRole​

1. 接口描述​

2. 输入参数​

PermissionPolicyItem​

3. 返回结果​

4. 示例代码​

describeRoleList​

1. 接口描述​

2. 输入参数​

3. 返回结果​

RoleItem​

modifyRole​

1. 接口描述​

2. 输入参数​

3. 返回结果​

deleteRoles​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

modifyResourcePermission

1. 接口描述

2. 输入参数

权限类型（BasePermission）

3. 返回结果

4. 示例代码

describeResourcePermission

1. 接口描述

2. 输入参数

3. 返回结果

ResourcePermission

createRole

1. 接口描述

2. 输入参数

PermissionPolicyItem

3. 返回结果

4. 示例代码

describeRoleList

1. 接口描述

2. 输入参数

3. 返回结果

RoleItem

modifyRole

1. 接口描述

2. 输入参数

3. 返回结果

deleteRoles

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码