获取 AceDataCloud 平台文档详情

获取 AceDataCloud 平台文档详情

💡 原文中文,约1100字,阅读约需3分钟。
📝

内容提要

AceDataCloud 文档详情接口为 GET /api/v1/documents/{id_or_alias},采用公开鉴权,可通过 UUID、当前或旧 alias 直接读取单篇文档。可选 lang 参数或 Accept-Language,语言以 content_locale 为准。响应包含元数据、正文、父级与同级、子级摘要及关联资源,不含 breadcrumbs。文档不存在或不可见时返回 404;private 仅隐藏列表,不阻止直链访问。路由不带尾斜杠。

🔎

延伸解读

private 不是保密边界

文章明确指出,private 只控制文档在列表中的可见性,并不阻止知道链接的人直接读取。这意味着若把敏感内容仅靠 private 标记来保护,实际上任何获得 UUID 或 alias 的人都能访问。需要真正保密时,应依赖其他访问控制手段,而不是把 private 当作权限隔离。

语言参数只是提示

请求可通过 lang 参数或 Accept-Language 头提示语言,但最终内容语言以响应中的 content_locale 为准。调用方不应假设传入 lang 就一定返回对应语言版本,而应读取 content_locale 判断实际语言,再决定是否展示或回退,避免多语言场景下出现内容与界面语言不一致。

面包屑需自行构建

详情响应不包含 breadcrumbs 字段,但提供了 parent 以及按 rank 排序的公开 children 摘要。若页面需要面包屑,可从 parent 逐级继续请求详情,或使用已缓存的文档目录关系拼装。这要求调用方额外处理层级请求或维护缓存,不能指望单次详情响应直接给出完整路径。

路由与旧 alias 的注意点

当前路由使用无尾斜杠形式,文章提醒不要依赖代理层自动补斜杠,调用时应直接使用规范 URL。此外,id_or_alias 除 UUID 和当前 alias 外,还接受保留在 redirect_from 中的旧 alias,便于旧链接继续可用;但文档不存在或不符合站点可见性时统一返回 404。

❓

Q&A

AceDataCloud 文档详情接口的请求方法和 URL 是什么?

使用 GET 方法,URL 为 https://platform.acedata.cloud/api/v1/documents/{id_or_alias}。

如何通过 alias 获取文档详情?需要先查列表吗?

可以直接用 alias 请求,无需先从列表筛选。id_or_alias 参数支持文档 UUID、当前 alias 或保留在 redirect_from 中的旧 alias。

文档详情接口支持哪些语言参数?最终语言以什么为准?

可选 lang 参数或使用 Accept-Language 请求头。最终内容语言以响应中的 content_locale 字段为准。

文档详情响应包含哪些字段?有 breadcrumbs 吗?

响应包含 id、alias、redirect_from、name、title、type、rank、tags;content、content_mode、content_locale、content_hash;parent、sibling 和按 rank 排序的公开 children 摘要;api/dataset/integration 关联及 agent(存在时)。没有 breadcrumbs 字段。

文档不存在或不可见时返回什么错误?private 文档能直接访问吗?

ID/alias 不存在或不符合当前站点可见性时返回 404。private 仅控制列表可见性,不阻止知道链接的人直接读取,不能作为保密边界。

调用文档详情接口时 URL 末尾可以加斜杠吗?

当前路由使用无尾斜杠形式,不要依赖代理层自动补斜杠。

🏷️

标签

➡️

继续阅读