Google Cloud Search Indexing Queue

借助 Connector SDK 和 Cloud Search REST API，您可以创建 Cloud Search 索引队列，以用来执行以下任务：

• 维护每个文档的多方面状况（状态、哈希值等），以便用于确保索引与存储区保持同步。

• 维护在遍历过程中发现的一系列项以将其编入索引。

• 根据项的状态确定该项在队列中的优先级。

• 维护其他状态信息（如检查点、更改标记等），以确保高效集成。

队列是分配给编入索引项的标签，例如表示默认队列的“默认”或表示队列 B 的“B”。

状态和优先级

文档在队列中的优先级取决于其 ItemStatus 代码。以下是可能的 ItemStatus 代码（按优先级处理，最后处理到最后）：

• ERROR - 将项编入索引期间发生了异步错误，并且需要重新编入索引。

• MODIFIED - 已编入索引的项自上次编入索引后在存储区中发生了修改。

• NEW_ITEM - 未编入索引的项。

• ACCEPTED - 已编入索引的文档自上次编入索引后在存储库中未发生更改。

如果队列中的两个项具有相同状态，则在队列中停留时间最长的项将被赋予更高优先级。

使用索引队列将新内容或已更改的内容编入索引

图 1 显示了使用索引编制队列将新内容或已更改的内容编入索引的步骤。以下步骤显示了 REST API 调用。如需了解等效的 SDK 调用，请参阅队列操作（连接器 SDK）。

图 1. 添加或更新商品的编入索引步骤

1. 内容连接器使用 items.push 将项（元数据和哈希）推送到索引队列中，以建立项的状态（MODIFIED、NEW_ITEM、DELETED）。具体而言：

   • 推送时，连接器明确包含推送 type 或 contentHash。
   • 如果连接器未包含 type，则 Cloud Search 会自动使用 contentHash 确定项目的状态。
   • 如果商品未知，则商品状态会设置为 NEW_ITEM。
   • 如果内容存在且哈希值匹配，则状态保留为 ACCEPTED。
   • 如果内容存在且哈希值不同，则状态变为 MODIFIED。

   如需详细了解如何确定项的状态，请参阅 Cloud Search 入门教程中的遍历 GitHub 代码库示例代码。

   通常情况下，推送与连接器中的内容遍历和/或更改更改检测流程相关联。

2. 内容连接器使用 items.poll 轮询队列，以确定要编入索引的项。Cloud Search 会告知连接器，哪些项目最需要编入索引，首先按状态代码排序，然后按队列时间排序。

3. 连接器会从代码库中检索这些项并构建索引 API 请求。

4. 连接器使用 items.index 将项编入索引。仅当 Cloud Search 成功处理完内容后，内容才会进入 ACCEPTED 状态。

如果资源库中不再存在某个项目，连接器也可以将其删除；如果该项目未修改或存在源代码库错误，则会再次推送该项目。如需了解如何删除内容，请参阅下一部分。

注意：某些遍历策略（如完全遍历）会使用多个索引队列。如需查看有关如何使用两个队列的示例，请参阅下一部分。

使用索引队列删除项的概览

完全遍历策略使用双队列流程来将项编入索引并检测删除情况。图 2 显示了使用两个索引队列删除项的步骤。具体而言，图 2 显示了使用完全遍历策略执行的第二次遍历。这些步骤使用 REST API 调用。如需了解等效的 SDK 调用，请参阅队列操作（连接器 SDK）。

图 2. 删除项目

注意：在以下步骤中，图 2 中未显示第 1-4 步，因为它们与上图中的第 1-4 步相同，不在本部分的讨论范围内。第 5 步未显示，因为在空队列上调用 deleteQueueItems 不在本部分的讨论范围内。下图重点介绍第二次遍历。

1. 在首次遍历时，内容连接器使用 items.push 将项（元数据和哈希）推送到索引队列，并将“A”排入 NEW_ITEM，因为它在队列中不存在。会为每项内容分配“A”队列“A”标签。内容会编入 Cloud Search 索引。

   注意：在执行 item.push 或 item.index 操作期间，连接器可以使用相应项的 queue 字段为项分配队列标签。每当重新推送项目或将其重新编入索引时，您都可以修改此标签。

2. 内容连接器使用 items.poll 来轮询队列 A，以确定要编入索引的项。Cloud Search 会告知连接器，哪些项目最需要编入索引，首先按状态代码排序，然后按队列时间排序。

3. 连接器会从代码库中检索这些项并构建索引 API 请求。

4. 连接器使用 items.index 将项编入索引。仅当 Cloud Search 成功处理完内容后，内容才会进入 ACCEPTED 状态。

5. deleteQueueItems 方法在队列 B 上调用。但是，没有任何项被推送到队列 B，因此无法删除任何内容。

6. 在第二次完全遍历中，内容连接器使用 items.push 将项（元数据和哈希）推送到队列 B：

   • 推送时，连接器明确包含推送 type 或 contentHash。
   • 如果连接器未包含 type，则 Cloud Search 会自动使用 contentHash 确定项目的状态。
   • 如果该项未知，则该项的状态会设置为 NEW_ITEM，而队列标签会更改为 "B."
   • 如果列表项存在且哈希值一致，则状态保留为 ACCEPTED，队列标签更改为“B”。
   • 如果该项存在且哈希值不同，则状态变为 MODIFIED，队列标签会更改为“B”。

7. 内容连接器使用 items.poll 轮询队列，以确定要编入索引的项。Cloud Search 会告知连接器，哪些项目最需要编入索引，首先按状态代码排序，然后按队列时间排序。

8. 连接器会从代码库中检索这些项并构建索引 API 请求。

9. 连接器使用 items.index 将项编入索引。仅当 Cloud Search 成功处理完内容后，内容才会进入 ACCEPTED 状态。

10. 最后，在队列 A 上调用 deleteQueueItems 以删除先前具有队列“A”标签的之前已编入索引的所有 Cloud Search 项。

11. 在后续的完全遍历中，用于编入索引的队列和用于删除的队列会进行交换。

队列操作 (Connector SDK)

借助 Content Connector SDK，您可以将项推送到队列中，以及从队列中拉取项。

如需打包某个项并将其推送到队列中，请使用 pushItems 构建器类。

要从队列中拉取项以进行处理，您无需执行任何特定操作。SDK 会使用 Repository 类的 getDoc 方法按优先级顺序自动从队列中拉取项。

队列操作 (REST API)

通过 REST API，您可以分别使用以下两个方法将项推送到队列中以及从队列中拉取项：

• 如需将内容推送到队列中，请使用 Items.push。
• 如需轮询队列中的项，请使用 Items.poll。

在索引编制期间，您还可以使用 Items.index 将项推送到队列中。编入索引期间推送到队列的项不需要 type，系统会自动为其分配 ACCEPTED 状态。

Items.push

Items.push 方法用于将 ID 添加到队列中。此方法可使用特定 type 值调用，该值决定了推送操作的结果。如需查看 type 值的列表，请参阅 Items.push 方法中的 item.type 字段。

推送新 ID 会添加一个包含 NEW_ITEM ItemStatus 代码的新条目。

可选载荷始终会作为不透明值进行存储，并通过 Items.poll 返回。

轮询某个项时，系统会预留该项，这意味着另外对 Items.poll 的调用无法返回该项。将 Items.push 与 type 用作 NOT_MODIFIED、REPOSITORY_ERROR 或 REQUEUE 时，取消保留轮询条目。如需详细了解预留条目和未预留条目，请参阅 Items.poll 部分。

包含哈希值的 Items.push

Cloud Search REST API 支持在 Items.index 请求中指定元数据和内容哈希值。您可以在推送请求中指定元数据和/或内容哈希值，而不是指定 type。Cloud Search Indexing Queue 将提供的哈希值与数据源中该项的可用存储值进行比较。如果不匹配，则该条目将被标记为 MODIFIED。如果索引中不存在相应的项，则状态为 NEW_ITEM。

注意：随 Items.push 请求提供的哈希值不随项一起保存。这些项仅用于确定相应项是否已修改。

Items.poll

Items.poll 方法用于从队列中检索具有最高优先级的条目。请求的状态值和返回的状态值分别指示所请求优先级队列的状态和返回的 ID 的状态。

默认情况下，系统可以根据优先级返回任意队列部分中的条目。除非出现以下任一情况，否则返回的每个条目都会被预留，并且对 Items.poll 的其他调用都不会返回该条目：

• 预留超时。
• 该条目已被 Items.index 再次加入队列。
• 使用 type 的 NOT_MODIFIED、REPOSITORY_ERROR 或 REQUEUE 值调用 Items.push。