Skip to main content

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

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

Page summary:

在 Strapi 5 中，documentId 字段取代了 id，用于在内容 API 调用（REST API 和 GraphQL）中识别文档，这是文档服务 API 过渡的一部分。

🌐 In Strapi 5, the documentId field replaces id for identifying documents in Content API calls (REST API and GraphQL) as part of the Document Service API transition.

在 Strapi 5 中，处理内容的底层 API 是 Document Service API，在 Content 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.

 Is this breaking change affecting plugins?Yes
 Is this breaking change automatically handled by a codemod?Partly
(see entity-service-document-service)

重大变更描述​

🌐 Breaking change description

在 Strapi v4 中

条目通过它们的 id 进行识别：

🌐 Entries were identified by their id:

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

在 Strapi 5 中

文件通过其 documentId 进行标识：

🌐 Documents are identified by their documentId:

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

迁移​

🌐 Migration

本节重新组合了有关引入的重大更改的有用说明和程序。

🌐 This section regroups useful notes and procedures about the introduced breaking change.

注意​

🌐 Notes

  • 此重大更改会影响路线和关系。
  • 为了简化从 v4 到 Strapi 5 的过渡，对条目的 API 调用在响应中可能仍会包含 id 字段，尤其是在使用 Document Service API 时。但建议你开始养成使用 documentId 而不是 id 的习惯，因为这将有助于处理向未来 Strapi 版本的过渡。

迁移程序​

🌐 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.

有关更多信息，请参阅以下资源：

🌐 For additional information, please refer to the following resources:

On this page