Skip to main content

在 Content API 调用中应使用 documentId 代替 id

¥documentId should be used instead of id in Content API calls

在 Strapi 5 中，处理内容的底层 API 是 文档服务 API，文档应在内容 API 调用（REST API 和 GraphQL）中由其 documentId 调用。

¥In Strapi 5, the underlying API handling content is the Document Service API and documents should be called by their documentId in Content API calls (REST API & GraphQL).

此页面是 重大变更数据库 的一部分，提供有关重大更改的信息以及从 Strapi v4 迁移到 Strapi 5 的其他说明。

¥This page is part of the breaking changes database and provides information about the breaking change and additional instructions to migrate from Strapi v4 to Strapi 5.

\🔌 此重大更改是否会影响插件？\是
\🤖 此重大更改是否由 codemod 自动处理？\部分

重大更改描述​

¥Breaking change description

在 Strapi v4 中

¥In Strapi v4

条目由其 id 标识：

¥Entries were identified by their id:

{
  "data": {
    // system fields
    "id": 14,
    "attributes": {
      // user fields
      "title": "Article A"
      "relation": {
        "data": {
          "id": "clkgylw7d000108lc4rw1bb6s"
          "name": "Category A"
        }
      }
    }
  }
  "meta": {
    // …
  }
}

在 Strapi 5 中

¥In Strapi 5

文档由其 documentId 标识：

¥Documents are identified by their documentId:

{
  "data": {
    // system fields
    "documentId": "clkgylmcc000008lcdd868feh",
    "locale": "en",
    // user fields
    "title": "Article A"
    "relation": {
      // system fields
      "documentId": "clkgylw7d000108lc4rw1bb6s"
      // user fields
      "name": "Category A"
    }
  }
  "meta": {
    // …
  }
}

迁移​

¥Migration

注意​

¥Notes

  • 此重大更改会影响路线和关系。

    ¥This breaking change impacts routes and relations.

  • 为了简化从 v4 到 Strapi 5 的过渡，对条目的 API 调用可能仍会在其响应中包含 id 字段，尤其是 文档服务 API。但建议你开始养成使用 documentId 而不是 id 的习惯，因为它将简化向未来 Strapi 版本的过渡。

    ¥To ease the transition from v4 to Strapi 5, API calls to entries might still include an id field in their response, especially with the Document Service API. But it's recommended that you start making an habit of using documentId instead of id as it will ease handling the transition to future Strapi versions.

迁移程序​

¥Migration procedure

codemod 将部分处理更改，但可能会将 __TODO__ 项添加到你的代码中，因为 codemod 不可能自动猜测内容的新 documentId。

¥A codemod will partly handle the change, but might probably add __TODO__ items to your code since it's impossible for the codemod to automatically guess the new documentId of your content.

有关更多信息，请参阅相关的 重大变更条目、分步指南 以升级到 Strapi 5，以及 实体服务 API 到文档服务 API 的转换 的专用迁移指南（如果这适用于你的自定义代码）。

¥For additional information, please refer to the related breaking change entry, the step-by-step guide to upgrade to Strapi 5, and the dedicated migration guide for the Entity Service API to Document Service API transition if this applies to your custom code.