Skip to content

工作区配置管理

配置管理接口按对象读取、预检和修改工作区配置，适合自动化配置与逐项验收。统一路径前缀为：

/openapi/v1/workspaces/{workspaceId}/management/

本文后续路径均相对此前缀，且必须以 / 结尾。原有工作区配置和模型配置接口继续可用。

鉴权与调用顺序

请求头使用 Authorization: Bearer <access_token>。密钥须有当前工作区权限及 workspace 功能权限；读取数据或执行真实问法的接口还需 data 权限。写入时可传当前客户账号的 operatorUid，用于记录操作人；它不替代密钥鉴权。可先通过当前密钥范围核对授权。

  1. 从列表取得对象 ID，再读取详情中的 revision。变更前可查询 impacts/{type}/{id}/ 了解引用与依赖。
  2. 向该对象的 preview/ 提交动作、修订值和变更。预检返回 planToken，不保存配置。
  3. 在 10 分钟内用同一密钥提交与预检一致的内容，并设置 Idempotency-Key 请求头。令牌绑定工作区、密钥、对象、变更和操作人。
  4. 保存后回读对象；若返回 operationId，再查询 operations/{operationId}/。异步配置还需按具体页面说明验收实际效果。

普通资源（时间序列、维度、指标、维度表、模型及多数知识对象）的预检请求如下。创建时使用 action: "create"；修改和删除需提供 targetId 及详情的 revision，删除的 changes 为 {}。

POST /openapi/v1/workspaces/1/management/dimensions/preview/
Authorization: Bearer <access_token>
Content-Type: application/json

{"action":"update","targetId":12,"revision":"<当前修订值>","changes":{"description":"新的说明"}}

{
  "errcode": 200,
  "errmsg": "success",
  "data": {
    "beforeRevision": "<当前修订值>",
    "afterRevision": "<预期修订值>",
    "changes": { "description": "新的说明" },
    "impact": { "usedByModels": [], "usedByDrafts": [], "dependentMeasures": [] },
    "candidate": { "id": 12, "description": "新的说明" },
    "planToken": "<预检令牌>"
  }
}

PATCH /openapi/v1/workspaces/1/management/dimensions/12/
Authorization: Bearer <access_token>
Idempotency-Key: dimension-12-description-v1
Content-Type: application/json

{"changes":{"description":"新的说明"},"planToken":"<预检令牌>"}

普通资源使用集合 POST / 创建、详情 PATCH {id}/ 修改、详情 DELETE {id}/ 删除。提交中可选的 operatorUid 必须与预检一致。省略字段表示保留，清空字段须明确传空值。时间序列、维度、指标、维度表和模型的详情含 definition、revision、usedByModels；语料、SOP、数据集等知识对象的详情含 id、definition、revision。列表返回摘要。专用接口的请求形状见后续页面。

幂等、响应与操作状态

提交必须使用不超过 128 字符的 Idempotency-Key。同一密钥、工作区和请求体重试会返回相同结果及 operationId；同一键用于另一请求会被拒绝。修订值变化或预检过期时，应重新读取详情并预检。接口统一使用 errcode、errmsg、data 响应；预检失败时依据 errmsg 修正后重试。

GET operations/{operationId}/ 返回 operationId、target、state、beforeRevision、afterRevision、result，以及可能存在的 taskUid、taskResult、probe。操作 ID 只可由原密钥在对应工作区查询。

状态 含义 建议动作
saved 配置已保存 回读对象，必要时运行探针
pending 后续任务尚未完成 稍后再查操作状态
verified 对应任务或探针已通过 回读实际配置和业务结果
failed 任务或验收失败 查看 taskResult、probe 和错误信息，修正后重新预检
unknown 证据不足或无法关联到本次任务 回读来源、配置或运行实际问法，勿视作通过

幂等结果和操作状态沿用开放接口访问日志的一年保留期；过期后无法重放旧键或查询旧操作 ID。来源元数据刷新采用防抖任务，多次请求可能合并；无法关联到本次实际执行任务时状态为 unknown。

按任务查找