通过 API 配置 QwenWork 管理后台

更新时间:
复制 MD 格式
  • 权限类型:read / manage / execute

开始调用

  1. 创建应用:在开放平台创建或选择应用。

  2. 授权权限项:按用途独立勾选需要的读取、管理或执行权限项。

  3. 创建 API Key:凭据只在创建成功时完整展示,请立即安全保存。

  4. 构造请求:按接口文档构造请求,并使用请求 ID 排查问题。

  • 认证方式:API Key、Scope 与组织边界。

  • 通用约定:Host、格式与请求追踪。

  • 错误处理:通用状态码与排查顺序。

认证方式

服务端应用使用开放平台创建的 API Key 调用接口。API Key 代表应用身份,服务端据此确定可信组织和应用已获授权的 Scope。

认证与请求头

所有接口适用公共认证与追踪请求头。Authorization 必填,X-Request-Id 可选;Idempotency-Key 仅在单接口参数表明确声明时适用,是否必填以该接口为准。

读取(read)、管理(manage)和执行(execute)权限互不隐含,必须按所调用接口分别授权。

名称

位置

类型

必填

说明

示例

Authorization

header

string

是

应用 API Key,使用 Bearer 方式传递。

Bearer <API_KEY>

X-Request-Id

header

string

否

可选的调用追踪标识;未传入时由服务端生成。

req-20260831-001

Content-Type

header

string

按单接口请求体

按单接口声明设置媒体类型;JSON 使用 application/json,文件上传按该接口使用 multipart/form-data,勿将 JSON 头套用于上传。

application/json

Idempotency-Key

header

string

按单接口文档

仅用于单接口明确支持的幂等请求;是否必填、长度及字符限制以该接口为准,相同输入重试时复用原值。

idem-20260831-001

API Key 和其他密钥只能保存在服务端密钥系统中,不得写入浏览器代码、日志、文档或截图。

错误处理

先按 HTTP 状态和稳定业务错误码判断认证、授权、参数、资源或依赖服务问题。

错误码

业务服务错误响应使用 error、detail、code 和可选 details 字段。

请求追踪标识通过响应头 X-Request-Id 返回;经公共错误中间件处理且请求上下文中已有追踪标识时,错误正文还可能包含可选的 request_id(string)。

它不是成功响应的通用必填字段,也不能与审批等接口中同名的业务申请 ID 混淆。

HTTP

错误类型

错误码

说明

可重试

400

BadRequest

request_validation_failed

Content-Type、JSON、revision 等请求格式无效。

否

401

Unauthorized

openapi_invalid_api_key

API Key 缺失或无效。

否

403

Forbidden

openapi_scope_denied

API Key 未获得当前接口要求的独立 Scope。

否

404

NotFound

authn_openapi_not_enabled

OpenAPI 接口未启用或未在网关目录注册。

否

404

NotFound

department_not_found

指定部门不存在;这是当前部门接口已实现的资源错误码示例。

否

422

UnprocessableEntity

request_validation_failed

UUID、分页、字段或 Idempotency-Key 等语义校验失败。

否

503

ServiceUnavailable

iam_openapi_execution_unavailable

IAM 内部执行链路或相关 OpenAPI 能力暂时不可用。

是

错误响应示例

{
  "error": "UnprocessableEntity",
  "detail": "Idempotency-Key is required.",
  "code": "request_validation_failed"
}

排查与重试顺序

先校验请求格式和 API Key,再核对接口 Scope,随后确认资源状态。

仅在 503 或明确可重试的网关错误下退避重试;仅对明确支持幂等重放的接口复用原 Idempotency-Key 和完全相同的请求内容;其他写操作应先查询实际结果,再按该接口说明决定是否重试。

使用响应头 X-Request-Id 关联日志和排查调用链。

字段表阅读约定

  • 请求字段的“必填”表示调用方必须提交;响应字段的“必填”表示对应响应分支保证包含该键,不是需要填写的参数。

  • 必填性与可空性分别判断:可省略不等于允许 null,允许 null 也不等于可以省略。以字段表的“必填”和“类型”为准。

  • 嵌套字段要求仅在父对象存在且非 null 时适用;对象数组的字段要求逐个应用于非 null 元素,仅凭子字段必填不能推断数组非空;minItems 等数组数量约束仍独立适用。数组本身和数组元素是否允许 null 分别以其类型为准。

  • 可选对象的出现条件、条件必填及特殊业务约束在对应接口字段说明中列明;同名字段在不同响应分支的含义以该分支为准。

{key}、{locale} 等路径表示动态字典键,[] 表示数组元素;具体允许的键和扩展属性以接口说明为准。 示例域名及 <...> 均为占位符,调用前替换为实际地址和业务值。版本号使用查询返回的当前值;配置发布前先读取现有配置,按接口的合并或替换语义保留不需修改的字段。示例不包含真实凭据。

公共错误响应

仅在状态表明确引用本结构时适用。特殊业务详情见对应接口;不得将冲突或同步恢复字段视为所有错误共有字段。request_id 是错误中间件可能附加的可选追踪字段,现有生成协议未声明,参见本页错误处理说明。

公共错误字段

名称

类型

必填

说明

示例

detail

string

是

错误说明;客户端分支应使用 code。

"Request rejected"

error

string

是

稳定的 HTTP 错误类型。

"Conflict"

通用错误

复用结构:见本文“公共错误字段”

名称

类型

必填

说明

示例

code

string

否

稳定业务错误码;没有业务码时可省略。

"request_rejected"

details

object

否

仅在该错误分支有结构化详情时出现。

-

details

字段

类型

必填

说明

field

string

否

相关的公开请求字段名。

reason

string

否

校验失败原因。

suggestion

string

否

建议修正值或处理方式。

公共错误示例

以下仅示意公共必填字段;可选业务码、详情及追踪标识按实际错误场景返回。

{
  "error": "Bad Request",
  "detail": "Request validation failed"
}

用户写入的同步等待与重试

适用于创建、更新、删除用户、调整用户席位/状态及入组织/席位申请审批:本地业务提交后最多等待 10 秒,同步确认成功立即返回该接口的成功响应,不固定等待满 10 秒。

同步仍在处理时可能返回 HTTP 503 / iam_openapi_execution_unavailable,具体详情以接口的特殊响应结构为准。

committed=true 表示本地写入已执行,不表示同步完成;不要因此另起一笔写操作。先通过查询接口核对业务状态;声明了幂等键的操作应复用原键和原请求。

提交前校验失败仍按原错误处理;普通 503 不代表已经提交,也不代表已经回滚。