REST API：publicationFilter

页面摘要： 添加可选的 publicationFilter 查询参数，可依据文档草稿版本与已发布版本的关联关系来查询文档，例如从未发布的文档，或自上次发布后被修改的文档。它可与其他查询参数组合使用，而 status 仍决定你获取的是草稿还是已发布版本。

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

如果说 status 回答的是「我要草稿还是已发布版本？」，那么 publicationFilter 参数回答的则是另一个问题：「基于草稿与已发布版本的关联方式，我想要哪些文档？」。例如，这对于查找从未发布的文档，或草稿相比线上版本存在未保存改动的文档非常有用。

publicationFilter 的底层模型由 文档服务 API 在后端服务器上处理。本页采用完全相同的结构与说明，但示例针对 REST API 进行了调整，因此你无需在两个不同页面之间切换。

WARNING

content-type 上必须启用 草稿与发布 功能。如果禁用了草稿与发布，publicationFilter 将不起作用。

可用值 {#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 参数组合），请参阅可能的用例 表。

NOTE
  • 未知值会返回 HTTP 400 错误。
  • 以 -document 结尾的值会考虑文档的所有区域，这在启用 国际化（i18n） 时很重要：例如，只要文档的某个区域被发布，never-published-document 就会将该文档排除。所有其他值则一次只考虑一个区域。若未启用 i18n，两种变体行为一致。
注意：不同 API 的默认行为不同

REST API 在省略 status 时返回文档的已发布版本，因此对于仅针对草稿的值（如 never-published）需要显式传入 status=draft。而文档服务 API 则返回草稿版本（请参阅 文档服务 API：publicationFilter）。

可能的用例 {#use-cases}

下表列出了多种可能的用例，展示了如何将 status 与 publicationFilter 参数组合使用，以通过 REST API 精确找到所需内容。点击某个用例可跳转到完整示例：

我想要…将 status 设为…将 publicationFilter 设为…
查找从未发布的草稿draftnever-published
查找在任何区域中从未发布的草稿draftnever-published-document
查找已修改的文档draft 或 publishedmodified
查找未修改的文档draft 或 publishedunmodified
查找拥有已发布版本的文档draft 或 publishedhas-published-version
查找在至少一个区域中拥有已发布版本的文档draft 或 publishedhas-published-version-document
NOTE

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

示例

以下小节列出了上表中汇总的常见用例。

查找从未发布的草稿 {#never-published}

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

此参数组合仅针对给定区域生效；要跨所有区域查找这些文档，请改用 never-published-document。

返回其区域中从未被发布的草稿。

cURL

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

JavaScript

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

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

响应

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

查找在任何区域中从未发布的草稿 {#never-published-document}

publicationFilter=never-published-document 返回在任何区域中从未被发布的文档。它会跨文档的所有区域进行整体判断，而非一次只看一个区域。要仅针对给定区域查找这些文档，请改用 never-published。

只要文档的某个区域被发布，该文档即被视为已发布：此时文档会被排除，即便是那些仅以草稿形式存在的区域。下面的示例返回在任何地方都从未发布的文档的草稿版本：

返回在任何区域中从未发布的文档的草稿。

cURL

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

JavaScript

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

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

响应

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

查找已修改的文档 {#modified}

publicationFilter=modified 选择那些草稿存在已修改但未发布变更的文档。随后 status 决定你取回这些文档的哪个版本。

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

返回存在未发布变更的文档的草稿版本。

cURL

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

JavaScript

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

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

响应

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

使用 status=published（REST 的默认行为）时，同样的查询将改为返回这些文档当前线上的版本：

返回存在未发布变更的文档当前线上的版本。

cURL

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

JavaScript

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

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

响应

{
    "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
      }
    }
}

查找未修改的文档 {#unmodified}

publicationFilter=unmodified 选择那些自上次发布以来草稿未发生变化的文档。随后 status 决定你取回这些文档的哪个版本。

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

返回自上次发布以来未发生变化的文档的草稿版本。

cURL

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

JavaScript

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

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

响应

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

使用 status=published（REST 的默认行为）时，同样的查询将改为返回这些文档当前线上的版本：

返回自上次发布以来未发生变化的文档当前线上的版本。

cURL

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

JavaScript

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

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

响应

{
    "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
      }
    }
}

查找拥有已发布版本的文档 {#has-published-version}

publicationFilter=has-published-version 选择那些在同一区域中同时拥有草稿与已发布版本的文档。随后 status 决定你取回这些文档的哪个版本。

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

返回在同一区域中同时也拥有已发布版本的文档的草稿版本。

cURL

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

JavaScript

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

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

响应

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

使用 status=published（REST 的默认行为）时，同样的查询将改为返回这些文档当前线上的版本：

返回在同一区域中同时也拥有已发布版本的文档当前线上的版本。

cURL

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

JavaScript

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

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

响应

{
    "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
      }
    }
}

查找在至少一个区域中拥有已发布版本的文档 {#has-published-version-document}

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

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

cURL

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

JavaScript

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

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

响应

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

诊断用值 {#diagnostics}

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

显示诊断用值示例

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

返回同一区域中没有匹配草稿版本的已发布文档。

cURL

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

JavaScript

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

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

响应

{
    "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 选择同时拥有草稿的已发布文档，在健康的数据库中即为每一个已发布文档：

返回同一区域中同时也拥有匹配草稿版本的已发布文档。

cURL

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

JavaScript

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

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

响应

{
    "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}

publicationFilter 可与 filters、locale、populate 以及其它 REST 参数 组合使用。所有条件会同时生效。