认证与请求约定
准备访问身份
集成身份应具有目标模块的 License、功能权限和对象范围权限。应用系统、数据源、标准目录、资产目录和质量问题的访问范围分别核对。管理员浏览到的数据不代表普通集成身份也可访问。
不同部署可能由统一认证网关、单点登录或 Token 机制承载请求。接口定义未声明统一的 securitySchemes，因此本文不假定固定的 Authorization: Bearer、Basic 或自定义请求头。
生产集成应由管理员确认当前部署支持的认证方式、凭据携带位置、有效期和撤销方法。支持单点登录的环境由统一认证网关处理会话。不要将浏览器中的个人登录会话作为长期无人值守集成方案。
当前身份与 Token 管理
除了通过接口管理 Token，还可以在产品界面生成：登录“个人工作台”，进入“Token 管理”，按需生成短期 Token 或永久 Token。短期 Token 适合临时联调，永久 Token 仅适合受控的服务账号；生成后立即保存到企业密钥管理系统，页面通常不会再次展示完整凭据。永久 Token 应建立负责人、用途、轮换周期和撤销记录。
以下路径均为完整服务路径。Token 管理接口属于身份管理，不是无需登录的密码换 Token 接口。
| 方法与路径 | 用途 | 关键输入或返回 |
|---|---|---|
GET /user/usermanagement/users/details/self | 验证当前认证身份 | 返回当前用户信息；对接方仅保留需要的用户标识 |
POST /user/token/getTokens | 查询当前用户的 Token | 返回凭据列表，包含 id、name、expireHours、expiresAt 等；响应可能包含敏感凭据 |
POST /user/token/generateTokens | 创建当前用户的 Token | JSON Body 可用 name（String）、expireHours（Long）；是否允许创建及期限以部署策略为准 |
POST /user/token/updateToken | 更新凭据配置 | 请求结构以目标环境 UserTokenUpdateDto 为准 |
POST /user/token/deleteToken | 撤销凭据 | 请求结构以目标环境 UserTokenUpdateDto 为准；执行前确认受影响的调用方 |
创建 Token 不会增加账号原有权限。凭据存入企业密钥管理设施，禁止写进代码、请求日志、截图和文档。
请求地址与方法
请求地址为“部署入口 + 完整服务路径”。Swagger 的 servers 可能是服务节点内部地址，对外调用应使用管理员确认的统一入口，不直接复制内部 IP。
接口方法以本指南及目标 OpenAPI 为准。现有产品中有不少 POST 查询，不能因为使用 POST 就判定为写操作；也有历史接口同时声明多种方法，不能据此把 DELETE、PUT 当作查询别名使用。
JSON 请求使用 Content-Type: application/json。Query 参数、Path 参数与 Body 不可互换；文件导入使用接口规定的 multipart/form-data，导出可能返回二进制或异步任务标识，不按 JSON 强制解析。
下面以一次已验证的元数据检索演示请求结构。DAM_BASE_URL 是企业实际入口，DAM_COOKIE_FILE 是经企业认可方式配置的有效会话 Cookie 文件路径，仅用于会话方式联调；采用其他认证方式时替换为管理员确认的携带方式。
curl --fail-with-body --request POST \
--cookie "$DAM_COOKIE_FILE" \
--header 'Content-Type: application/json' \
--data '{"currentPage":1,"pageSize":20,"keyword":"customer","types":["TABLE"]}' \
"$DAM_BASE_URL/metadata/entities/searchMetadata"示例未关闭 HTTPS 证书验证。企业证书由可信 CA 或企业信任链验证，不在生产调用中忽略证书错误。
分页与响应不能统一套用
| 接口 | 请求分页字段 | 数据列表与总数 |
|---|---|---|
| 元数据搜索、数据源分页、已发布标准分页 | Body：currentPage、pageSize | content、totalItems |
| 标准代码分页 | Body：currentPage、pageSize | data、total |
| 质量技术规则分页 | Body：currentPage、pageSize | ruleList、total |
| 资产列表 | Body：pageNum、pageSize | 外层 status、msg、data；data 为开放结构，按实测适配 |
| 已发布安全资产 | Body：pageNo、pageSize，Schema 默认 1、10 | 外层 status、msg、data |
| 质量问题明细 | Query：currentPage、pageSize，从 1 开始 | rowNames、rowData、totalRow |
| 通用任务列表 | Body：查询条件及嵌套 page | content、totalElements、number 等 |
| 统一资产搜索（可选） | Body：cursor、limit | items、nextCursor、hasMore |
不能仅按分页字段名称推断起始页。对返回开放 Map 的接口先做少量联调，不自行编造 data.list 等字段。
对象标识与一致性
- 保留应用系统
categoryId、数据源modelId、表字段objectId，并记录来源系统和 Schema。 - 搜索结果中的元数据标识是
id，详情及字段接口使用 Path 参数objectId。以接口返回对象核对映射。 - 资产目录
catalogId、目录结构structureId、资产assetId与底层元数据objectId不同。 - 标准
domainId与domainCode不同；指标、标准代码也有各自的编号。 - SQLink 节点
id为 String，不能直接当作 DAM 的数字objectId；跨服务应建立经确认的映射。 - 长整型标识在 JavaScript 中可能超过安全整数范围，接入系统应采用不会丢失精度的解析和存储方式。
异常、重试与日志
| 现象 | 调用方处理 |
|---|---|
| 401 或重定向到登录页 | 重新认证，检查是否实际返回 HTML；不把登录页当作成功 JSON |
| 403 或对象不可见 | 核对身份、模块及对象范围；不改用跳过权限校验的接口 |
| 400、404 | 核对服务前缀、方法、参数类型和对象是否存在 |
| 429、网关繁忙或临时 5xx | 只读请求采用有上限的退避重试；是否支持 429 以部署为准 |
| 200 但外层业务状态失败 | 检查 status、msg 或服务实际错误结构，不能只判断 HTTP |
| 599 等部署自定义错误码 | 保存脱敏错误摘要并联系服务管理员，不将其等同于标准 HTTP 状态语义 |
写入与启动任务没有经核实的统一幂等键。超时后先查询对象或任务状态，再决定是否补交，避免重复创建或重复执行。日志保留时间、方法、路径、脱敏条件、对象及实例标识、HTTP 和业务状态；删除凭据、连接密码和原始问题数据。
联调完成检查
- 用集成身份查询一条可见对象和一条无权限对象，确认边界。
- 比较页面与 API 的名称、来源、状态和数量，并验证分页终止条件。
- 验证凭据过期、缺参、对象不存在和服务异常的处理分支。
- 记录环境构建版本及接口契约；升级后重复业务场景回归。