Google Cloud Search 索引队列

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

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

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

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

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

队列是分配给索引项的标签，例如“default”（默认队列）或“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. 删除内容

注意 ：在以下步骤列表中，步骤 1-4 未显示在图 2 中，因为它们与上图中的步骤 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. 系统会在“队列 B”上调用 deleteQueueItems 方法。但是，尚未将任何项推送到队列 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”标签的所有 CCloud 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（采用哈希值）

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

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

Items.poll

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

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

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