Skip to main content

更新管理员角色接口

替换指定角色的名称、说明、权限、成员和管理范围，数组字段应提交需要保留的完整集合。系统预置角色可以调整配置明细，但不能改名。

  • Scope：admin.v1.admin-roles.manage
  • 权限项：管理员角色管理（admin-roles）
  • 权限类型：管理
  • 接口：PATCH/api/openapi/v1/admin-roles/{roleId}

认证与请求头

使用应用 API Key 调用。当前接口只校验上方独立 Scope；读取、管理与执行权限互不隐含。
名称位置类型必填说明示例
Authorizationheaderstring是应用 API Key，使用 Bearer 方式传递。Bearer qwk_***
X-Request-Idheaderstring否可选的调用追踪标识；未传入时由服务端生成。req-20260831-001

权限兼容与保存语义

权限列表以当前目录为准。旧 biz.resource_hub.manage 和 biz.market.manage 分别展开为技能、连接器、专家套件的对应权限；旧 biz.submission.review 展开为技能、专家套件审批权限。转换后去重保存，响应返回当前实际保存的权限码。 subscription.usage-details.view 已退役，旧请求携带时接受但忽略，不再保存或返回；其他未知权限仍拒绝。 biz.catalog.manage 归属 assets.skills，用于官方目录供给配置和资源包导入。接口仍支持单独提交部分权限，不因提交一个权限而自动补齐整个菜单。

请求参数

名称位置类型必填说明示例
roleIdpathstring · uuid必填管理员角色 ID"<uuid>"
descriptionbodystring否说明"<string>"
member_idsbodyarray ｜ null必填用户（QID 列表）["<string>"]
namebodystring必填管理员角色名称"<string>"
permissionsbodyarray ｜ null必填管理权限["<string>"]
scopesbodyarray ｜ null必填管理范围-

scopes[] 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。
字段类型必填说明
include_descendantsboolean否部门对象是否包含下级部门
subject_idstring是适用对象 ID
subject_typestring是适用对象类型

请求示例

curl --request PATCH \
  --url 'https://example.invalid/api/openapi/v1/admin-roles/<roleId>' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "description": "<string>",
  "member_ids": [
    "<string>"
  ],
  "name": "<string>",
  "permissions": [
    "<string>"
  ],
  "scopes": [
    {
      "include_descendants": false,
      "subject_id": "<string>",
      "subject_type": "<string>"
    }
  ]
}'

响应

200 OK

名称类型必填说明示例
created_atstring · date-time是创建时间"2026-08-27T10:00:00Z"
descriptionstring是说明"<string>"
idstring是管理员角色 ID"<string>"
member_idsarray ｜ null是用户（QID 列表）["<string>"]
namestring是管理员角色名称"<string>"
permissionsarray ｜ null是管理权限["<string>"]
scopesarray ｜ null是管理范围-
systemboolean是是否为系统角色false
updated_atstring · date-time是更新时间"2026-08-27T10:00:00Z"

scopes[] 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。
字段类型必填说明
include_descendantsboolean否部门对象是否包含下级部门
subject_idstring是适用对象 ID
subject_typestring是适用对象类型
{
  "created_at": "2026-08-27T10:00:00Z",
  "description": "<string>",
  "id": "<string>",
  "member_ids": [
    "<string>"
  ],
  "name": "<string>",
  "permissions": [
    "<string>"
  ],
  "scopes": [
    {
      "include_descendants": false,
      "subject_id": "<string>",
      "subject_type": "<string>"
    }
  ],
  "system": false,
  "updated_at": "2026-08-27T10:00:00Z"
}

default Flat business error

名称类型必填说明示例
codestring否Stable business error code"<string>"
detailstring是Human-readable error description"<string>"
detailsOpenapiErrorDetails否错误详情-
errorstring是Stable HTTP error type"<string>"

details 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。
字段类型必填说明
fieldstring否校验失败的请求字段
reasonstring否校验失败的原因代码
suggestionstring否建议使用的规范化值
{
  "code": "<string>",
  "detail": "<string>",
  "details": {
    "field": "<string>",
    "reason": "<string>",
    "suggestion": "<string>"
  },
  "error": "<string>"
}