在使用安企CMS管理网站内容时，我们经常需要从后台获取特定文档的详细信息，无论是为了在自定义页面上展示内容，还是将数据集成到其他系统（比如小程序、移动应用等）。安企CMS提供了一套强大且灵活的API接口，其中一个核心功能便是通过文档ID来获取具体的文档详情。

今天，我们就来深入了解如何利用文档ID，轻松获取安企CMS的文档详情，让您的内容运营更加高效和自动化。

核心步骤：如何通过API获取文档详情

要获取安企CMS的文档详情，您需要使用其提供的“获取文档详情接口”。这就像是您给CMS一个门牌号（文档ID），它就会把这栋房子（文档）里所有公开的信息都告诉您。

API调用地址与请求方式：

您可以通过以下地址来访问这个接口： {域名地址}/api/archive/detail

请注意，{域名地址} 需要替换成您自己网站的实际域名，例如 https://www.yourdomain.com/api/archive/detail。

这个接口的调用方法是 GET 请求，意味着您可以通过浏览器直接访问，或者在代码中使用HTTP GET方法来请求数据。

请求参数：ID与别名，灵活选择

要指定您想获取哪个文档的详情，您需要提供一个参数。安企CMS在这个方面提供了两种非常灵活的选择：

  • id (int 类型，必填): 这是文档在系统中的唯一数字标识。如果您知道文档的ID，直接传入即可。
  • filename (string 类型，可选): 如果您传入了 id，就不需要再传 filename。但是，如果您不知道文档ID，但知道文档的URL别名（通常是文档链接中的友好名称），您也可以通过 filename 来获取文档详情。这在很多场景下非常实用，例如您只知道一篇新闻的短链接。

请记住，id 和 filename 只需要二选一，传入其中一个就能成功获取信息。

请求数据示例：

假设您要获取ID为 1 的文档详情，您的请求会是这样： {域名地址}/api/archive/detail?id=1

如果您想通过别名 anqicms-tutorial 获取文档，请求则会是： {域名地址}/api/archive/detail?filename=anqicms-tutorial

理解API返回的数据

当您成功调用接口后，安企CMS会返回一个JSON格式的数据包，里面包含了您请求的文档所有相关信息。这个数据包通常包括以下几个核心部分：

  • code (int 类型): 错误码。通常 0 表示请求成功，其他非零值则表示出现了错误。
  • msg (string 类型): 错误原因说明。如果 code 不是 0，这里会提供具体的错误信息，帮助您排查问题。
  • data (object 类型): 这就是文档详情的核心内容。如果请求成功，这里会是一个包含文档各项属性的对象；如果文档不存在或发生其他错误，这个字段可能为 null。

data 对象：文档信息的宝库

data 对象内部包含了文档的方方面面，您可以从中提取出所需的信息：

  1. 文档的基础信息：

    • id：文档的唯一ID。
    • title：文档标题。
    • description：文档简介。
    • url_token：文档的URL别名。
    • keywords：文档的关键词。

  2. 丰富的内容呈现：

    • data.content：这是文档的实际内容详情，通常以HTML字符串形式返回，方便您直接渲染到页面上。
    • logo：文档的Logo图片地址。
    • thumb：文档的缩略图地址。
    • images：一个字符串数组，包含文档的组图（多张图片）地址。

  3. 重要的运营元数据：

    • seo_title：文档的SEO标题，用于搜索引擎优化。
    • views：文档的浏览量。
    • comment_count：文档的评论数量。
    • created_time：文档的发布时间戳。
    • updated_time：文档的最后更新时间戳。
    • flag：文档的推荐属性，例如头条、推荐、幻灯等。

  4. 关联信息与自定义扩展：

    • category：这是一个嵌套对象，包含了文档所属分类的详细信息，如分类ID、分类名称、分类别名等，让您能轻松获取分类上下文。
    • extra：这是一个非常强大的字段，它会根据您在安企CMS后台模型中设置的自定义字段来显示。例如，如果您为文章模型添加了“作者”字段，那么这里就会包含作者的信息，结构通常是 key => item，其中 name 是字段名称，value 是填写的值。

返回数据示例（简化）：

{
  "code": 0,
  "data": {
    "id": 1,
    "title": "欢迎使用AnqiCMS",
    "seo_title": "",
    "url_token": "anqicms",
    "keywords": "",
    "description": "欢迎使用AnqiCMS",
    "views": 1338,
    "logo": "https://www.anqicms.com/uploads/202012/7/bd36c37ef742c7be.webp",
    "thumb": "https://www.anqicms.com/uploads/202012/7/thumb_bd36c37ef742c7be.webp",
    "created_time": 1607308159,
    "category": {
      "id": 1,
      "title": "AnqiCMS帮助",
      "url_token": "goruning",
      "content": "<p>欢迎使用AnqiCMS</p>"
    },
    "data": {
      "content": "<p>欢迎使用AnqiCMS</p>"
    },
    "extra": {
      "author": {
        "name": "作者",
        "value": "AnqiCMS",
        "default": ""
      }
    }
  },
  "msg": ""
}

实际应用场景

通过文档ID获取文档详情是安企CMS API的基石之一，它的应用场景非常广泛：

  • 构建高度定制化的详情页： 您可以完全掌控文档在前端的展示方式，不再受限于预设模板。
  • 开发跨平台应用： 无论是PC端、H5、小程序还是原生APP，都可以通过这个接口获取统一的文档数据源。
  • SEO优化： 获取 seo_title、keywords 和 description 等信息，可以在前端动态设置页面的SEO元数据。
  • 数据分析与内容推荐： 结合 views、comment_count 等数据，您可以构建更智能的内容推荐系统或进行数据分析。
  • 内容聚合与分发： 快速获取大量文档详情，用于构建内容聚合平台或向第三方平台分发内容。

错误处理小贴士

在使用API时，了解常见的错误码能帮助您更快地定位问题：

  • code: 0: 一切正常，数据在 data 字段中。
  • code: -1: 通用错误，具体原因会显示在 msg 字段中，例如“文档不存在”。
  • code: 1001: 未登录。如果您的CMS设置了文档需要登录才能访问，但您没有提供有效的用户凭证，就会出现这个错误。
  • code: 1002: 未授权。即使登录了，也可能因为权限不足而无法访问某些文档。

通过理解并善用这个文档详情接口，您可以充分发挥安企CMS的内容管理能力，为您的网站或应用带来更灵活、更强大的内容展示和互动体验。

常见问题 (FAQ)

Q1：如果我同时传入了 id 和 filename，系统会优先使用哪个参数？

A1： 根据安企CMS的文档说明，如果您同时传入 id 和 filename，系统通常会优先处理 id 参数。为了避免混淆并确保请求的明确性，建议您只传入其中一个参数，选择您手头最方便或最明确的那个。

Q2：如果我请求的文档不存在，API会返回什么？

A2： 如果您请求的文档ID或filename不存在，API会返回一个 code 为 -1 的状态码，并在 msg 字段中给出类似“文档不存在”的提示信息。此时，data 字段通常会是 null 或一个空对象。在您的程序中，应该对 code 和 data 字段进行判断，以妥善处理文档不存在的情况。

Q3：我可以通过这个接口只获取文档的标题和简介，而不是所有字段吗？

A3： “获取文档详情接口”被设计为一次性返回文档的所有可用详细信息。这意味着您无法直接通过参数控制只返回部分字段。如果您只需要文档的标题、简介等少量信息，而不需要完整的文档内容，您可以在前端或后端获取到完整数据后，再根据需求提取或过滤所需字段进行展示。如果性能成为瓶颈，并且您需要大量文档的少量信息，那么“获取文档列表接口”（/api/archive/list）可能更适合，