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. 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”标签的所有 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 使用 type 值 NOT_MODIFIED、REPOSITORY_ERROR 或 REQUEUE 调用。