REST API：`publicationFilter`

🌐 REST API: publicationFilter

Page summary:
添加可选的 publicationFilter 查询参数，以根据文档草稿版本与已发布版本之间的关系查询文档，例如从未发布的文档，或自上次发布以来已修改的文档。它可以与其他查询参数结合使用，而 status 仍然决定你获取的是草稿版本还是已发布版本。
🌐 Add the optional publicationFilter query parameter to query documents by the relationship between their draft and published versions, for example documents that were never published, or documents modified since they were last published. It combines with other query parameters, and status still decides whether you get the draft or the published version.

publicationFilter 是一个查询参数，与 status 参数结合使用时，可以帮助你通过 REST API 完成复杂查询，精确找到所需内容。

🌐 The publicationFilter is a query parameter that, combined with the status parameter, can help you cover complex queries to find exactly what you need with the REST API.

当 status 回答“我想要草稿版还是发布版？”时，publicationFilter 参数回答的是一个不同的问题：“根据文档的草稿版和发布版之间的关系，我想要哪些文档？”这对于例如查找从未发布的文档，或草稿与已发布内容相比有未保存更改的文档非常有用。

🌐 While status answers "do I want the draft or the published version?", the publicationFilter parameter answers a different question: "which documents do I want, based on how their draft and published versions relate?". This is useful for example to find documents that were never published, or documents whose draft has unsaved changes compared to what is live.

publicationFilter 的工作原理背后的基础模型是在后端服务器上由 Document Service API 处理的。本页遵循完全相同的结构和解释，但示例针对 REST API 进行了定制，因此你无需在两个不同的页面之间切换。

🌐 The underlying model behind how publicationFilter works is handled on the back-end server by the Document Service API. The present page follows the exact same structure and explanations, but with examples tailored for the REST API, so you don't have to jump between 2 different pages.

Prerequisites

内容类型必须启用草稿与发布功能。如果草稿与发布被禁用，publicationFilter将不起作用。

🌐 The Draft & Publish feature must be enabled on the content-type. If Draft & Publish is disabled, publicationFilter has no effect.

可用值

🌐 Available values

publicationFilter 接受以下值之一：

值	选择
`never-published`	从未在特定语言环境中发布的文档
`never-published-document`	从未在任何语言环境中发布的文档
`modified`	自上次发布以来草稿被编辑过的文档
`unmodified`	自上次发布以来草稿未更改的文档
`has-published-version`	同时拥有草稿和已发布版本的文档
`published-without-draft`	已发布但没有草稿对应的文档 (仅用于诊断)
`published-with-draft`	已发布且同时拥有草稿的文档 (仅用于诊断)
`has-published-version-document`	至少在一个语言环境中发布的文档 (在启用 i18n 时有用)

有关如何使用 publicationFilter 值的详细示例，包括与 status 参数一起使用，请参见可能的用例表。

🌐 For detailed examples of how to use the publicationFilter values, including with the status parameter, see the possible use cases table.

Note

未知值返回 HTTP 400 错误。
以 -document 结尾的值会考虑文档的所有语言环境，这在启用国际化 (i18n) 时很重要：例如，never-published-document 一旦文档的某个语言环境被发布就会将其排除。所有其他值则一次只考虑一个语言环境。在未启用 i18n 的情况下，这两种变体的行为相同。

Caution: Different default behaviors for different APIs

当省略 status 时，REST API 会返回文档的已发布版本，因此对仅草稿值（如 never-published）的查询需要明确指定 status=draft。而文档服务 API 则返回草稿版本（参见 Document Service API: publicationFilter）。

🌐 The REST API returns published versions of documents when status is omitted, so queries for draft-only values such as never-published need an explicit status=draft. The Document Service API returns draft versions instead (see Document Service API: publicationFilter).

可能的使用场景

🌐 Possible use cases

下表列出了许多可能的使用场景，说明了如何将 status 和 publicationFilter 参数结合使用，以在 REST API 中准确找到所需内容。点击一个使用场景即可跳转到完整示例：

🌐 The following table lists many possible use cases, illustrating how the status and publicationFilter parameters can be combined to find exactly what you need with the REST API. Click a use case to jump to a complete example:

我想要…	使用 `status` 作为…	使用 `publicationFilter` 作为…
查找从未发布的稿件	`draft`	`never-published`
查找在任何地区从未发布的稿件	`draft`	`never-published-document`
查找已修改的文档	`draft` 或 `published`	`modified`
查找未修改的文档	`draft` 或 `published`	`unmodified`
查找有已发布版本的文档	`draft` 或 `published`	`has-published-version`
查找至少在一个地区有已发布版本的文档	`draft` 或 `published`	`has-published-version-document`

Note

将一个值与上表中的相反 status 配对是有效的，但不会返回错误，而是返回空结果：例如，never-published 与 status=published 配对会返回空结果，因为这些文档尚无已发布版本。

🌐 Pairing a value with the opposite status from the table above is valid but returns nothing rather than an error: for example, never-published with status=published returns an empty result, because these documents have no published version yet.

例子

🌐 Examples

以下部分列出了上方表格中总结的最常见用例。

🌐 The following section lists the most common use cases summed up in the table above.

查找从未发布的草稿

🌐 Find never published drafts

最常见的用例之一是查找从未发布的草稿。为此，请传递 status=draft 和 publicationFilter=never-published。

🌐 One of the most common use cases is to find the drafts that have never been published. To do so, pass status=draft and publicationFilter=never-published.

此参数组合仅适用于特定语言环境；要在所有语言环境中查找这些文档，请改为使用 never-published-document。

🌐 This parameter combination works only on a given locale; to find these documents across all locales, use never-published-document instead.

GET/api/restaurants?status=draft&publicationFilter=never-published

获取从未在其所在地区发布过的餐厅草稿

返回从未在其所在地区发布的草稿。

cURL
JavaScript

terminal
curl 'http://localhost:1337/api/restaurants?status=draft&publicationFilter=never-published' \
  -H 'Authorization: Bearer <token>'

const qs = require('qs');
const query = qs.stringify({
    status: 'draft',
    publicationFilter: 'never-published',
  }, {
    encodeValuesOnly: true, // prettify URL
});

await request(`/api/restaurants?${query}`);

200 OK

{
    "data": [
      {
        "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
        "name": "New Restaurant",
        "publishedAt": null,
        "locale": "en"
      }
    ],
    "meta": {
      "pagination": {
        "page": 1,
        "pageSize": 25,
        "pageCount": 1,
        "total": 1
      }
    }
}

查找从未在任何地区发布的草稿

🌐 Find drafts never published in any locale

publicationFilter=never-published-document 返回从未在任何语言环境下发布过的文档。它查看整个文档的所有语言环境，而不是一次查看一个语言环境。要仅查找特定语言环境的这些文档，请使用 never-published。

一旦文档的其中一个本地化版本被发布，该文档就算作已发布：文档随后会被排除在外，即使其他本地化版本仅以草稿形式存在。下面的示例返回那些从未在任何地方发布过的文档的草稿版本：

🌐 A document counts as published as soon as one of its locales is published: the document is then left out, even the locales that only exist as a draft. The example below returns the draft versions of documents that were never published anywhere:

GET/api/restaurants?status=draft&publicationFilter=never-published-document

获取从未在任何地方发布过的餐厅草稿

返回从未在任何地区发布的文件草稿。

cURL
JavaScript

terminal
curl 'http://localhost:1337/api/restaurants?status=draft&publicationFilter=never-published-document' \
  -H 'Authorization: Bearer <token>'

const qs = require('qs');
const query = qs.stringify({
    status: 'draft',
    publicationFilter: 'never-published-document',
}, {
    encodeValuesOnly: true, // prettify URL
});

await request(`/api/restaurants?${query}`);

200 OK

{
    "data": [
      {
        "documentId": "d41r46wac4xix5vpba7561at",
        "name": "New Restaurant",
        "publishedAt": null,
        "locale": "en"
      }
    ],
    "meta": {
      "pagination": {
        "page": 1,
        "pageSize": 25,
        "pageCount": 1,
        "total": 1
      }
    }
}

查找已修改的文档

🌐 Find modified documents

publicationFilter=modified 选择草稿有修改但未发布更改的文档。然后 status 决定你得到这些文档的哪个版本。

例如，使用 status=draft 时，查询返回草稿版本：

🌐 For instance, with status=draft, the query returns the draft versions:

GET/api/restaurants?status=draft&publicationFilter=modified

获取修改过的餐厅的草稿版本

返回含有未发布更改的文档草稿版本。

cURL
JavaScript

terminal
curl 'http://localhost:1337/api/restaurants?status=draft&publicationFilter=modified' \
  -H 'Authorization: Bearer <token>'

const qs = require('qs');
const query = qs.stringify({
    status: 'draft',
    publicationFilter: 'modified',
}, {
    encodeValuesOnly: true, // prettify URL
});

await request(`/api/restaurants?${query}`);

200 OK

{
    "data": [
      {
        "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
        "name": "Biscotte Restaurant (updated)",
        "publishedAt": null,
        "locale": "en"
      }
    ],
    "meta": {
      "pagination": {
        "page": 1,
        "pageSize": 25,
        "pageCount": 1,
        "total": 1
      }
    }
}

使用 status=published（REST 默认值）时，相同的查询将返回这些文档的当前最新版本：

GET/api/restaurants?publicationFilter=modified

获取当前已修改餐厅的实时版本

返回具有未发布更改的文档的当前版本。

cURL
JavaScript

terminal
curl 'http://localhost:1337/api/restaurants?publicationFilter=modified' \
  -H 'Authorization: Bearer <token>'

const qs = require('qs');
const query = qs.stringify({
    publicationFilter: 'modified',
}, {
    encodeValuesOnly: true, // prettify URL
});

await request(`/api/restaurants?${query}`);

200 OK

{
    "data": [
      {
        "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
        "name": "Biscotte Restaurant",
        "publishedAt": "2024-03-14T15:40:45.330Z",
        "locale": "en"
      }
    ],
    "meta": {
      "pagination": {
        "page": 1,
        "pageSize": 25,
        "pageCount": 1,
        "total": 1
      }
    }
}

查找未修改的文档

🌐 Find unmodified documents

publicationFilter=unmodified 选择自上次发布后草稿未更改的文档。然后 status 决定你将获取这些文档的哪个版本。

例如，使用 status=draft 时，查询返回草稿版本：

🌐 For instance, with status=draft, the query returns the draft versions:

GET/api/restaurants?status=draft&publicationFilter=unmodified

获取未修改餐厅的草稿版本

返回自上次发布以来未更改的文件草稿版本。

cURL
JavaScript

terminal
curl 'http://localhost:1337/api/restaurants?status=draft&publicationFilter=unmodified' \
  -H 'Authorization: Bearer <token>'

const qs = require('qs');
const query = qs.stringify({
    status: 'draft',
    publicationFilter: 'unmodified',
}, {
    encodeValuesOnly: true, // prettify URL
});

await request(`/api/restaurants?${query}`);

200 OK

{
    "data": [
      {
        "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
        "name": "Biscotte Restaurant",
        "publishedAt": null,
        "locale": "en"
      }
    ],
    "meta": {
      "pagination": {
        "page": 1,
        "pageSize": 25,
        "pageCount": 1,
        "total": 1
      }
    }
}

使用 status=published（REST 默认值）时，相同的查询将返回这些文档的当前最新版本：

GET/api/restaurants?publicationFilter=unmodified

获取当前未修改餐厅的实时版本

返回自上次发布以来未更改的文档当前版本。

cURL
JavaScript

terminal
curl 'http://localhost:1337/api/restaurants?publicationFilter=unmodified' \
  -H 'Authorization: Bearer <token>'

const qs = require('qs');
const query = qs.stringify({
    publicationFilter: 'unmodified',
}, {
    encodeValuesOnly: true, // prettify URL
});

await request(`/api/restaurants?${query}`);

200 OK

{
    "data": [
      {
        "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
        "name": "Biscotte Restaurant",
        "publishedAt": "2024-03-14T15:40:45.330Z",
        "locale": "en"
      }
    ],
    "meta": {
      "pagination": {
        "page": 1,
        "pageSize": 25,
        "pageCount": 1,
        "total": 1
      }
    }
}

查找有已发布版本的文档

🌐 Find documents with a published version

publicationFilter=has-published-version 选择那些在相同语言环境下既有草稿版本又有已发布版本的文档。status 然后决定你获得这些文档的哪个版本。

例如，使用 status=draft 时，查询返回草稿版本：

🌐 For instance, with status=draft, the query returns the draft versions:

GET/api/restaurants?status=draft&publicationFilter=has-published-version

获取也有已发布版本的餐厅的草稿版本

返回那些在相同语言环境下也有已发布版本的文档草稿版本。

cURL
JavaScript

terminal
curl 'http://localhost:1337/api/restaurants?status=draft&publicationFilter=has-published-version' \
  -H 'Authorization: Bearer <token>'

const qs = require('qs');
const query = qs.stringify({
    status: 'draft',
    publicationFilter: 'has-published-version',
}, {
    encodeValuesOnly: true, // prettify URL
});

await request(`/api/restaurants?${query}`);

200 OK

{
    "data": [
      {
        "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
        "name": "Biscotte Restaurant",
        "publishedAt": null,
        "locale": "en"
      }
    ],
    "meta": {
      "pagination": {
        "page": 1,
        "pageSize": 25,
        "pageCount": 1,
        "total": 1
      }
    }
}

使用 status=published（REST 默认值）时，相同的查询将返回这些文档的当前最新版本：

GET/api/restaurants?publicationFilter=has-published-version

获取同时拥有草稿的餐厅的当前在线版本

返回当前在线版本的文档，这些文档在同一语言区域也有已发布的版本。

cURL
JavaScript

terminal
curl 'http://localhost:1337/api/restaurants?publicationFilter=has-published-version' \
  -H 'Authorization: Bearer <token>'

const qs = require('qs');
const query = qs.stringify({
    publicationFilter: 'has-published-version',
}, {
    encodeValuesOnly: true, // prettify URL
});

await request(`/api/restaurants?${query}`);

200 OK

{
    "data": [
      {
        "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
        "name": "Biscotte Restaurant",
        "publishedAt": "2024-03-14T15:40:45.330Z",
        "locale": "en"
      }
    ],
    "meta": {
      "pagination": {
        "page": 1,
        "pageSize": 25,
        "pageCount": 1,
        "total": 1
      }
    }
}

查找在至少一个地区有已发布版本的文档

🌐 Find documents with a published version in at least one locale

publicationFilter=has-published-version-document 会考虑所有地区，因此只要文档的某个地区已发布，它就会匹配该文档。使用 status=draft 时，它会返回这些文档每个地区的草稿版本，包括那些从未发布过的地区：

GET/api/restaurants?status=draft&publicationFilter=has-published-version-document

获取至少在一个地区发布的餐厅草稿

返回至少在一个地区发布的文档的草稿版本。

cURL
JavaScript

terminal
curl 'http://localhost:1337/api/restaurants?status=draft&publicationFilter=has-published-version-document' \
  -H 'Authorization: Bearer <token>'

const qs = require('qs');
const query = qs.stringify({
    status: 'draft',
    publicationFilter: 'has-published-version-document',
}, {
    encodeValuesOnly: true, // prettify URL
});

await request(`/api/restaurants?${query}`);

200 OK

{
    "data": [
      {
        "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
        "name": "Biscotte Restaurant",
        "publishedAt": null,
        "locale": "en"
      }
    ],
    "meta": {
      "pagination": {
        "page": 1,
        "pageSize": 25,
        "pageCount": 1,
        "total": 1
      }
    }
}

诊断值

🌐 Diagnostic values

published-without-draft 和 published-with-draft 值仅用于数据完整性检查，而不是日常查询。在一个健康的数据库中，每个已发布的文档也都有一个草稿版本，因此这些值仅用于检测由遗留数据或人工数据库编辑导致的文档不一致状态。它们描述已发布的行，因此 REST 会随默认的 status=published 一起返回它们。

🌐 The published-without-draft and published-with-draft values are meant for data-integrity checks only, not for everyday queries. In a healthy database, every published document also has a draft version, so these values are only useful to detect documents left in an inconsistent state by legacy data or manual database edits. They describe published rows, so REST returns them with the default status=published.

显示诊断值示例

publicationFilter=published-without-draft 选择没有草稿对应的已发布文档。在正常操作中，这应返回空值：

GET/api/restaurants?publicationFilter=published-without-draft

获取同一地点没有草稿的已发布餐厅

返回在同一语言环境下没有匹配草稿版本的已发布文档。

cURL
JavaScript

terminal
curl 'http://localhost:1337/api/restaurants?publicationFilter=published-without-draft' \
  -H 'Authorization: Bearer <token>'

const qs = require('qs');
const query = qs.stringify({
    publicationFilter: 'published-without-draft',
}, {
    encodeValuesOnly: true, // prettify URL
});

await request(`/api/restaurants?${query}`);

200 OK

{
    "data": [
      {
        "documentId": "j0klm1n2o3p4q5r6s7t8u9v",
        "name": "Legacy Restaurant",
        "publishedAt": "2024-01-10T09:15:00.000Z",
        "locale": "en"
      }
    ],
    "meta": {
      "pagination": {
        "page": 1,
        "pageSize": 25,
        "pageCount": 1,
        "total": 1
      }
    }
}

publicationFilter=published-with-draft 选择那些已发布且也有草稿的文档，在健康的数据库中，这几乎包括每个已发布的文档：

GET/api/restaurants?publicationFilter=published-with-draft

获取同一地区既已发布又有草稿的餐厅

返回那些也有相同本地版本草稿的已发布文档。

cURL
JavaScript

terminal
curl 'http://localhost:1337/api/restaurants?publicationFilter=published-with-draft' \
  -H 'Authorization: Bearer <token>'

const qs = require('qs');
const query = qs.stringify({
    publicationFilter: 'published-with-draft',
}, {
    encodeValuesOnly: true, // prettify URL
});

await request(`/api/restaurants?${query}`);

200 OK

{
    "data": [
      {
        "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
        "name": "Biscotte Restaurant",
        "publishedAt": "2024-03-14T15:40:45.330Z",
        "locale": "en"
      }
    ],
    "meta": {
      "pagination": {
        "page": 1,
        "pageSize": 25,
        "pageCount": 1,
        "total": 1
      }
    }
}

与其他参数结合

🌐 Combine with other parameters

publicationFilter 可以与 filters、locale、populate 以及其他 REST 参数结合使用。所有条件同时适用。

可用值​

可能的使用场景​

例子​

查找从未发布的草稿​

查找从未在任何地区发布的草稿​

查找已修改的文档​

查找未修改的文档​

查找有已发布版本的文档​

查找在至少一个地区有已发布版本的文档​

诊断值​

与其他参数结合​

可用值

可能的使用场景

例子

查找从未发布的草稿

查找从未在任何地区发布的草稿

查找已修改的文档

查找未修改的文档

查找有已发布版本的文档

查找在至少一个地区有已发布版本的文档

诊断值

与其他参数结合