入门篇 — 第一次跑通 atkonbase V1

目标：让首次接触 atkonbase 的集成开发者，复制粘贴本页 curl 命令即可跑通一条端到端线索——认证 → 上传文件 → 查回元数据 → 设置 ACL。
不在本篇范围：分片上传（见文件上传链路模式篇）/ TRUSTED_DELEGATED 双通道（见认证与身份双通道模式篇）/ ACL 继承（见ACL 与继承模式篇）/ 多租户切换 / 元数据联合查询 / 版本管理——这些主题由对应模式篇单独承接。

前置假设

本篇所有示例均假设以下前置条件已满足。这些步骤本身不在 V1 集成 API 范围内：

前置条件	谁来准备	说明
租户已开通	atkonbase 服务方	租户开通由 atkonbase 服务方完成，不通过 V1 API 自助开通；开通后您会收到对应的租户标识。
已拿到 `clientId` / `clientSecret`	atkonbase 服务方	API Client 凭据由 atkonbase 服务方为您签发并提供。集成方妥善保管 `clientSecret`，不可入仓
已知一个可用的 `containerId`（容器 ID）	atkonbase 服务方	容器是文档的归属单元，由 atkonbase 服务方为您的租户准备好默认容器并告知其 ID。新建文档时上传 API 需要这个 ID
已部署可访问的 atkonbase 服务地址	部署方	示例中统一写作 `https://api.atkonbase.example.com`，集成时按实际地址替换

一、认证：获取 access token

V1 通道的认证形态是 client credentials——POST clientId + clientSecret 到 /v1/auth/token，拿到 accessToken 后续请求统一带 Authorization: Bearer <token>。

关键事实

V1 通道只通过 Authorization: Bearer <token> 鉴权，不要求任何额外的自定义签名或鉴权 Header
该端点是 V1 通道唯一可在未持有 token 时调用的端点（无需鉴权即可访问）
tenantId 由 clientId 在服务端解码得到，写入返回响应中；后续 V1 请求不需要在 Header 里再传 tenantId

curl 示例

bash

curl -X POST 'https://api.atkonbase.example.com/v1/auth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "clientId": "${clientId}",
    "clientSecret": "${clientSecret}"
  }'

期望响应（关键字段）

json

{
  "code": 0,
  "msg": "操作成功",
  "data": {
    "accessToken": "bcb1c7e5fd9b4d8f8e3c6a1d2f8b5e9c",
    "expiresIn": 7200,
    "refreshToken": "1f8b5e9c2f8b5e9c1f8b5e9c2f8b5e9c",
    "tenantId": "T1000001",
    "mode": "APP_ONLY",
    "scopes": ["client:storage:file:upload", "client:storage:metadata:value:read", "client:storage:acl:write"]
  }
}

accessToken —— 不透明字符串（约 32 字符的随机串，不是 JWT；不要尝试本地 decode/反序列化其内容）；后续所有 V1 请求都要带 Authorization: Bearer <accessToken>
expiresIn —— 单位是秒；过期判断走本字段（不可从 accessToken 本身解析过期时间）；过期前用 refreshToken 刷新或重新获取
tenantId —— 仅供集成方记录归属，不需要回传给服务端
mode —— client credentials 恒为 APP_ONLY（纯应用身份，无委派用户）；强 / 弱通道身份是每请求 header 状态、不反映在此字段，详见认证与身份双通道模式篇
scopes —— 当前 token 携带的能力清单（client:storage:xxx:xxx 形态）；调用具体端点时若 scope 不足会返 102002 SCOPE_DENIED / 106009 CLIENT_SCOPE_INSUFFICIENT

后续请求如何带 token

bash

curl 'https://api.atkonbase.example.com/v1/...' \
  -H 'Authorization: Bearer ${accessToken}'

⚠️ V1 通道只识别 Authorization Header——不要把 token 放进其它自定义 token Header，那样不会被识别。

委派场景的预告

如果集成方希望"以某个最终用户身份"调用 V1 API（例如让 ACL 检查走该用户而非 API Client），可附加以下 Header 之一（互斥）：

强通道：X-Atk-User-Token: <user-token>（系统自签的用户会话 token）
弱通道：X-Atk-Act-As-Source: <来源标识> + X-Atk-Act-As-Source-Id: <来源系统稳定主体键>

具体使用条件与跨租户/同租户判定规则在认证与身份双通道模式篇展开，入门篇不深入；背景概览见集成拓扑。

二、第一次上传：把文件存进 atkonbase

V1 文件上传使用 multipart/form-data，包含两个 part：

Part 名	Content-Type	说明
`file`	`application/octet-stream`	文件二进制
`metadata`	`application/json`	JSON 描述，决定是"新建文档"还是"在已有文档上传新版本"

新建文档只需 containerId + title；上传新版本只需 docId（已有文档 ID）——两条路径二选一。

curl 示例（新建文档）

bash

curl -X POST 'https://api.atkonbase.example.com/v1/versions/upload' \
  -H 'Authorization: Bearer ${accessToken}' \
  -F 'file=@/local/path/to/hello.txt;type=application/octet-stream' \
  -F 'metadata={"containerId":"${containerId}","title":"hello.txt"};type=application/json'

📌 metadata part 必须是合法 JSON 字符串且 Content-Type 显式标 application/json——这是契约要求，不可省略 ;type=application/json，否则会被当成普通字符串。

期望响应（关键字段）

json

{
  "code": 0,
  "msg": "操作成功",
  "data": {
    "docId": "D1000001",
    "versionId": "V1000001",
    "blobId": "B1000001",
    "versionNo": 1,
    "contentHash": "a948904f2f0f479b8f8197694b30184b0d2ed1c1cd2a1ec0fb85d299a192a447",
    "sizeBytes": 12,
    "mimeType": "text/plain",
    "originalFilename": "hello.txt"
  }
}

上例 contentHash 是 "hello world\n"（12 字节）的 SHA-256；集成方自验时可对照本地文件实际内容的 hash。

记下 docId——后面查元数据、设置 ACL 都要用到。

上传新版本（已有 docId 时）

bash

curl -X POST 'https://api.atkonbase.example.com/v1/versions/upload' \
  -H 'Authorization: Bearer ${accessToken}' \
  -F 'file=@/local/path/to/hello-v2.txt;type=application/octet-stream' \
  -F 'metadata={"docId":"${docId}","comment":"修订","label":"v2"};type=application/json'

不在本段范围

大文件分片上传走另一条三段式链路（/initChunkedUpload → /uploadChunk → /completeChunkedUpload），不在入门篇展开——见文件上传链路模式篇。

三、元数据查回：拿回这个文档挂了哪些字段

V1 元数据端点的"查"动作是 GET /v1/metadata/values/get + resourceType + resourceId 两个 query 参数——一次性返回该资源已有的所有 metadata 值（List 形态），不需要按 attributeKey 逐项 GET。

关键事实

resourceType 取值：DOCUMENT / CONTAINER（其它资源类型不支持元数据挂载）
resourceId 是对应 docId / containerId
响应返回的字段是已设置过的字段值——新上传的文档若未挂任何元数据值，返回的 List 可能为空

curl 示例

bash

curl -X GET 'https://api.atkonbase.example.com/v1/metadata/values/get?resourceType=DOCUMENT&resourceId=${docId}' \
  -H 'Authorization: Bearer ${accessToken}'

期望响应（关键字段）

json

{
  "code": 0,
  "msg": "操作成功",
  "data": [
    {
      "valueId": "MV1000001",
      "fieldId": "F1000001",
      "attributeKey": "department",
      "displayName": "归属部门",
      "dataType": "STRING",
      "value": "engineering",
      "updateTime": "2026-05-23T10:00:00.000+08:00"
    }
  ]
}

设置元数据值（写动作）

需要给文档挂值时用 POST /v1/metadata/values/set：

bash

curl -X POST 'https://api.atkonbase.example.com/v1/metadata/values/set' \
  -H 'Authorization: Bearer ${accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "resourceType": "DOCUMENT",
    "resourceId": "${docId}",
    "values": {
      "department": "engineering"
    },
    "partialUpdate": true
  }'

partialUpdate=true（默认）只更新 values 中出现的键，其它字段保持不变；false 则按整体替换语义
values 的 key 是字段的 attributeKey（业务定义的稳定标识），value 按字段 dataType 编码——具体编码规则见字段值编码契约

不在本段范围

按字段筛选 / 跨资源类型查询 / 字段定义变更（增删字段、约束修订）属于元数据联合查询模式篇和字段建模模式篇主题，入门篇不展开。

四、ACL 设置：给文档授权

V1 ACL 端点的"最小设置一条"动作是 POST /v1/acl/set：把资源（resource）+ 被授权方（grantee）+ 角色（role）三段拼齐即可。

关键事实

resource.resourceType 取值：DOCUMENT / CONTAINER
grantee.granteeType 取值：USER / ROLE / DEPARTMENT
role 取值（按权限范围从小到大）：
- VIEWER —— 读 + 下载
- EDITOR —— 读 + 下载 + 写
- MANAGER —— 全部权限（含 SHARE / MANAGE）
granteeId 是 atkonbase 内的稳定 ID——按 granteeType 分别对应业务用户 ID（USER）/ 角色 ID（ROLE）/ 部门 ID（DEPARTMENT）；不是 IdP 侧的 unionId / sub / employeeNo，也不是集成方业务系统的原始用户主键。典型获取路径是先调用业务身份查询端点，拿到 atkonbase 内的稳定 ID

curl 示例

bash

curl -X POST 'https://api.atkonbase.example.com/v1/acl/set' \
  -H 'Authorization: Bearer ${accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "resource": {
      "resourceType": "DOCUMENT",
      "resourceId": "${docId}"
    },
    "grantee": {
      "granteeType": "USER",
      "granteeId": "${userId}"
    },
    "role": "VIEWER"
  }'

期望响应（关键字段）

json

{
  "code": 0,
  "msg": "操作成功",
  "data": {
    "aclId": "A1000001",
    "resource": { "resourceType": "DOCUMENT", "resourceId": "${docId}" },
    "grantee": { "granteeType": "USER", "granteeId": "${userId}" },
    "permissionMask": 3,
    "resolvedRole": "VIEWER",
    "createTime": "2026-05-23T10:00:00.000+08:00",
    "updateTime": "2026-05-23T10:00:00.000+08:00"
  }
}

permissionMask 是位掩码（READ=1, DOWNLOAD=2, WRITE=4, DELETE=8, SHARE=16, MANAGE=32）；VIEWER=3=1+2，EDITOR=7=1+2+4，MANAGER=63
二选一：传 role 走预设角色（推荐），或传 permissionMask 走自定义位组合（高级用法）

不在本段范围

容器→文档的 ACL 继承解析、有效权限合并、批量授权（/batch-set）、权限快照查询 (/batchCheck) 等属于 ACL 与继承模式篇，入门篇不展开；继承关系的概念说明见领域模型 §ACL。

五、错误处理：读懂 V1 错误响应

V1 错误响应结构

V1 所有业务接口统一返回 ResponseDTO<T> 结构，包括失败响应：

json

{
  "code": 101001,
  "msg": "认证失败：clientId 或 clientSecret 不正确",
  "data": null
}

code: 0 —— 业务成功
code != 0 —— 业务失败，msg 是失败原因，data 通常为 null
code 是 int 类型；具体取值清单见错误码参考

HTTP status：统一 200

⚠️ atkonbase V1 不通过 HTTP status 区分业务错——所有业务异常均返 HTTP 200，业务结果由 body.code 区分。
集成方代码不可按 HTTP status 判断业务成败，必须读 body.code。

少数非业务码的 HTTP 错误（认证未通过 / 路径未匹配 / 上传超限等）保留原始 HTTP 状态码（401 / 404 / 413 等）——这些不在 V1 业务错误码清单内，作为附录在错误码参考单列。

code=1 兜底分支必须保留

⚠️ V1 还可能返回 code=1 通用错（涵盖：参数缺失 / 类型不匹配 / 数据约束失败 / 未编码业务错），msg 字段携带具体原因文本。
集成方代码不可做枚举式 exhaustive switch——必须保留对 code=1 通用错误的处理分支，覆盖未被专属错误码标识的业务错误，否则会有遗漏。

示例：处理认证失败

例如 clientSecret 输错时，POST /v1/auth/token 会返回：

json

{
  "code": 101001,
  "msg": "认证失败",
  "data": null
}

101001 是 AUTHENTICATION_FAILED——含义、典型触发条件、处理建议详见认证错误码 101001。

全流程串联回顾

text

1. POST /v1/auth/token            → accessToken
2. POST /v1/versions/upload       → docId, versionId
3. GET  /v1/metadata/values/get   → 当前 metadata 值清单
   POST /v1/metadata/values/set   → 写入新值
4. POST /v1/acl/set               → 给 docId 授权

跑通这四段，集成方已经完成了"对接 atkonbase 的最小闭环"。后续按业务需求查阅对应模式篇。

下一步

遇到错误响应 → 查错误码参考
需要展开委派 → 认证与身份双通道模式篇；分片上传 → 文件上传链路模式篇；ACL 继承 → ACL 与继承模式篇；Webhook 现状 → Webhook 预览篇
校验响应字段编码规则（如 metadata 字段按 dataType 编码、null 三态含义）→ 见字段值编码契约

入门篇 — 第一次跑通 atkonbase V1 ​

前置假设 ​

一、认证：获取 access token ​

关键事实 ​

curl 示例 ​

期望响应（关键字段） ​

后续请求如何带 token ​

委派场景的预告 ​

二、第一次上传：把文件存进 atkonbase ​

curl 示例（新建文档） ​

期望响应（关键字段） ​

上传新版本（已有 docId 时） ​

不在本段范围 ​

三、元数据查回：拿回这个文档挂了哪些字段 ​

关键事实 ​

curl 示例 ​

期望响应（关键字段） ​

设置元数据值（写动作） ​

不在本段范围 ​

四、ACL 设置：给文档授权 ​

关键事实 ​

curl 示例 ​

期望响应（关键字段） ​

不在本段范围 ​

五、错误处理：读懂 V1 错误响应 ​

V1 错误响应结构 ​

HTTP status：统一 200 ​

code=1 兜底分支必须保留 ​

示例：处理认证失败 ​

全流程串联回顾 ​

下一步 ​

入门篇 — 第一次跑通 atkonbase V1

前置假设

一、认证：获取 access token

关键事实

curl 示例

期望响应（关键字段）

后续请求如何带 token

委派场景的预告

二、第一次上传：把文件存进 atkonbase

curl 示例（新建文档）

期望响应（关键字段）

上传新版本（已有 docId 时）

不在本段范围

三、元数据查回：拿回这个文档挂了哪些字段

关键事实

curl 示例

期望响应（关键字段）

设置元数据值（写动作）

不在本段范围

四、ACL 设置：给文档授权

关键事实

curl 示例

期望响应（关键字段）

不在本段范围

五、错误处理：读懂 V1 错误响应

V1 错误响应结构

HTTP status：统一 200

code=1 兜底分支必须保留

示例：处理认证失败

全流程串联回顾

下一步