Skip to main content

文档服务 API：草稿与发布的使用

🌐 Document Service API: Usage with Draft & Publish

Page summary:

使用 Document Service API 的 status 参数可以检索文档的已发布或草稿版本，按状态统计文档数量，并在创建或更新文档时直接发布文档。

🌐 Use the status parameter with the Document Service API to retrieve published or draft versions of documents, count documents by status, and directly publish documents during creation or updates.

默认情况下，当启用 Draft & Publish 功能时，Document Service 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:

  • 返回文档的已发布版本，
  • 返回填充关系的草稿或已发布版本,
  • 根据文档的状态计数文档，
  • 并在创建或更新文档时直接发布文档。
Note

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

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

Note

文档服务 API 默认使用 draft，但 REST API 默认使用 published。因此，如果向 REST API 发送 POST 或 PUT 请求却没有 status 参数，它会立即发布，这跟本页描述的行为正好相反。

🌐 The Document Service API defaults to draft, but the REST API defaults to published. A POST or PUT request sent to the REST API without a status parameter therefore publishes immediately, which is the opposite of the behavior described on this page.

要根据文档的草稿版本和已发布版本的关系（从未发布、已修改等）选择文档，请参见 Document Service API: publicationFilter。

🌐 To select documents by how their draft and published versions relate (never-published, modified, and others), see Document Service API: publicationFilter.

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

🌐 Get the published version with findOne()

strapi.documents().findOne()

findOne() 状态为：'已发布'

返回特定文档的已发布版本。

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

获取带有 findFirst() {#find-first} 的已发布版本​

🌐 Get the published version with findFirst()

strapi.documents().findFirst()

findFirst()，状态：'已发布'

返回第一个匹配文档的已发布版本。

const document = await strapi.documents("api::restaurant.restaurant").findFirst({
  status: 'published',
});
200 OK
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  publishedAt: "2024-03-14T15:40:45.330Z",
  locale: "en", // default locale
  // …
}

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

🌐 Get the published version with findMany()

strapi.documents().findMany()

使用 status: 'published' 的 findMany()

返回所有匹配文档的已发布版本。

const documents = await strapi.documents("api::restaurant.restaurant").findMany({
  status: 'published'
});
200 OK
[
  {
    documentId: "a1b2c3d4e5f6g7h8i9j0klm",
    name: "Biscotte Restaurant",
    publishedAt: "2024-03-14T15:40:45.330Z",
    locale: "en", // default locale
    // …
  }
  // …
]

填充草稿或已发布的关系​

🌐 Populate draft or published relations

status 参数也适用于已填充关系。当内容类型启用草稿和发布时，已填充的关系会返回与查询文档相同的版本。

🌐 The status parameter also applies to populated relations. Populated relations return the same version as the queried documents when their content-type has Draft & Publish enabled.

Caution

status 仅在查询的根部被接受。将它添加到 populate 对象中，比如 populate: { categories: { status: 'draft' } }，会抛出一个 ValidationError，并显示类似 Invalid key status at categories 的信息。

[publicationFilter](/cms/api/document-service/publication-filter) 参数遵循相同的规则。它只在查询的根部被接受，Strapi 会用相同的值过滤已填充的关联关系。

🌐 The publicationFilter parameter follows the same rules. It is only accepted at the root of the query, and Strapi filters populated relations with the same value.

下面的例子会返回餐厅及其类别的已发布版本：

🌐 The following example returns the published versions of restaurants and of their categories:

strapi.documents().findMany()

使用 status: 'published' 的 findMany() 并进行 populate

返回所有匹配文档以及它们关联内容的已发布版本。

const documents = await strapi.documents("api::restaurant.restaurant").findMany({
  status: 'published',
  populate: ['categories'],
});
200 OK
[
  {
    documentId: "a1b2c3d4e5f6g7h8i9j0klm",
    name: "Biscotte Restaurant",
    publishedAt: "2024-03-14T15:40:45.330Z",
    locale: "en", // default locale
    categories: [
      {
        documentId: "z0y2x4w6v8u1t3s5r7q9onm",
        name: "French cuisine",
        publishedAt: "2024-03-14T15:38:12.004Z",
        // …
      }
    ],
    // …
  }
  // …
]

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'
});
Note

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

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

这意味着，即使某些文档已经发布，并且在内容管理器中不再显示为“草稿”或“已修改”，使用 status: 'draft' 参数进行计数仍会返回匹配其他参数的文档总数。要仅计数从未发布的草稿，请传递 publicationFilter 值，例如 'never-published' 或 'never-published-document'。

🌐 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. To count only never-published drafts, pass a publicationFilter value such as 'never-published' or 'never-published-document'.

创建草稿并发布它​

🌐 Create a draft and publish it

strapi.documents().create()

create() 状态：'已发布'

新建一个文档并立即发布它。

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

更新草稿并发布它​

🌐 Update a draft and publish it

strapi.documents().update()

update() 状态：'已发布'

更新现有文档并立即发布。

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