Skip to main content

文档服务 API：与草稿和发布一起使用

¥Document Service API: Usage with Draft & Publish

默认情况下，当启用 起草并发布 功能时，文档服务 API 会返回文档的草稿版本。本页介绍如何使用 status 参数来：

¥By default the Document Service API returns the draft version of a document when the Draft & Publish feature is enabled. This page describes how to use the status parameter to:

  • 返回文档的已发布版本，

    ¥return the published version of a document,

  • 根据文档的状态计数文档，

    ¥count documents depending on their status,

  • 并在创建或更新文档时直接发布文档。

    ¥and directly publish a document while creating it or updating it.

✏️ 注意

将 { status: 'draft' } 传递给文档服务 API 查询返回的结果与不传递任何 status 参数相同。

¥Passing { status: 'draft' } to a Document Service API query returns the same results as not passing any status parameter.

获取使用 findOne() 的已发布版本​

¥Get the published version with findOne()

findOne() 查询默认返回文档的草稿版本。

¥findOne() queries return the draft version of a document by default.

要使用文档服务 API 返回已发布的版本，同时 查找特定文档 与文档服务 API 匹配，请传递 status: 'published'：

¥To return the published version while finding a specific document with the Document Service API, pass status: 'published':

Example request
await strapi.documents('api::restaurant.restaurant').findOne({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  status: 'published'
});
Example response
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  publishedAt: "2024-03-14T15:40:45.330Z",
  locale: "en", // default locale
  // …
}

获取使用 findFirst() 的已发布版本​

¥Get the published version with findFirst()

findFirst() 查询默认返回文档的草稿版本。

¥findFirst() queries return the draft version of a document by default.

要使用文档服务 API 返回已发布的版本，同时 查找第一个文档 与文档服务 API 匹配，请传递 status: 'published'：

¥To return the published version while finding the first document with the Document Service API, pass status: 'published':

Example request


const document = await strapi.documents("api::restaurant.restaurant").findFirst({


  status: 'published',
});
Example response
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  publishedAt: "2024-03-14T15:40:45.330Z",
  locale: "en", // default locale
  // …
}

获取使用 findMany() 的已发布版本​

¥Get the published version with findMany()

findMany() 查询默认返回文档的草稿版本。

¥findMany() queries return the draft version of documents by default.

要使用文档服务 API 返回已发布的版本，同时 查找文档 与文档服务 API 匹配，请传递 status: 'published'：

¥To return the published version while finding documents with the Document Service API, pass status: 'published':

Example request


const documents = await strapi.documents("api::restaurant.restaurant").findMany({


  status: 'published'
});
Example response
[
  {
    documentId: "a1b2c3d4e5f6g7h8i9j0klm",
    name: "Biscotte Restaurant",
    publishedAt: "2024-03-14T15:40:45.330Z",
    locale: "en", // default locale
    // …
  }
  // …
]

count() 仅限草稿或已发布版本​

¥count() only draft or published versions

要使用文档服务 API 进行 计数文档 时仅考虑文档的草稿或已发布版本，请传递相应的 status 参数：

¥To take into account only draft or published versions of documents while counting documents with the Document Service API, pass the corresponding status parameter:

// Count draft documents (also actually includes published documents)


const draftsCount = await strapi.documents("api::restaurant.restaurant").count({


  status: 'draft'
});
// Count only published documents


const publishedCount = await strapi.documents("api::restaurant.restaurant").count({


  status: 'published'
});
✏️ 注意

由于已发布的文档必然也有草稿副本，因此已发布的文档仍算作具有草稿版本。

¥Since published documents necessarily also have a draft counterpart, a published document is still counted as having a draft version.

这意味着使用 status: 'draft' 参数计数仍会返回与其他参数匹配的文档总数，即使某些文档已经发布并且不再在内容管理器中显示为 "draft" 或 "modified"。目前没有办法阻止已发布的文档被计算在内。

¥This means that counting with the status: 'draft' parameter still returns the total number of documents matching other parameters, even if some documents have already been published and are not displayed as "draft" or "modified" in the Content Manager anymore. There currently is no way to prevent already published documents from being counted.

创建草稿并发布​

¥Create a draft and publish it

要在创建文档时自动发布文档，请将 status: 'published' 添加到传递给 create() 的参数中：

¥To automatically publish a document while creating it, add status: 'published' to parameters passed to create():

Example request
await strapi.documents('api::restaurant.restaurant').create({
  data: {
    name: "New Restaurant",
  },
  status: 'published',
})
Example response
{
  documentId: "d41r46wac4xix5vpba7561at",
  name: "New Restaurant",
  publishedAt: "2024-03-14T17:29:03.399Z",
  locale: "en" // default locale
  // …
}

更新草稿并发布​

¥Update a draft and publish it

要在更新文档时自动发布文档，请将 status: 'published' 添加到传递给 update() 的参数中：

¥To automatically publish a document while updating it, add status: 'published' to parameters passed to update():

Example request
await strapi.documents('api::restaurant.restaurant').update({
  data: {
    documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
    name: "Biscotte Restaurant (closed)",
  },
  status: 'published',
})
Example response
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant (closed)",
  publishedAt: "2024-03-14T17:29:03.399Z",
  locale: "en" // default locale
  // …
}