Google Cloud Search 索引队列

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

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

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

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

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

队列是分配给已编入索引的商品的标签，例如默认队列的标签为“default”，队列 B 的标签为“B”。

状态和优先级

文档在队列中的优先级取决于其 ItemStatus 代码。下面按优先级顺序（即从第一个处理到最后一个处理的顺序）列出了可用的 ItemStatus 代码：

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

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

  • NEW_ITEM - 未编入索引的项。

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

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

使用索引编制队列将新项或已更改的项编入索引的概览

图 1 显示了使用索引队列为新项或已更改的项编制索引的步骤。以下步骤展示了 REST API 调用。如需了解等效的 SDK 调用，请参阅队列操作 (Connector SDK)。

Google Cloud Search 索引编制概览
图 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 调用，请参阅队列操作 (Connector SDK)。

Google Cloud Search 索引编制概览
图 2. 删除商品

  1. 在初始遍历时，内容连接器使用 items.push 将商品（元数据和哈希）推送到索引队列（即“队列 A”），因为 NEW_ITEM 不在队列中。每个商品都分配有“A”标签，表示“队列 A”。内容会编入 Cloud Search 的索引。

  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 返回该项。 将 type 用作 NOT_MODIFIED、REPOSITORY_ERROR 或 REQUEUE 时，使用 Items.push 会取消预留轮询的条目。如需进一步了解预留条目和未预留条目，请参阅 Items.poll 部分。

采用哈希值的 Items.push

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

Items.poll

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

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

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