借助 Connector SDK 和 Google Cloud Search API,您可以创建 Cloud Search 索引队列,用于执行以下任务:
维护每个文档的多方面状况(状态、哈希值等),以便用于确保索引与存储区保持同步。
维护在遍历过程中发现的一系列项以将其编入索引。
根据项的状态确定该项在队列中的优先级。
维护其他状态信息(如检查点、更改标记等),以确保高效集成。
队列是分配给索引项的标签,例如,“default”表示默认队列,“B”表示队列 B。
状态和优先级
文档在队列中的优先级取决于其 ItemStatus
代码。可能的 ItemStatus
代码按优先级顺序(从最先处理到最后处理)排列:
ERROR
- 将项编入索引期间发生了异步错误,并且需要重新编入索引。MODIFIED
- 已编入索引的项自上次编入索引后在存储区中发生了修改。NEW_ITEM
- 未编入索引的项。ACCEPTED
- 已编入索引的文档自上次编入索引后在代码库中没有更改。
如果队列中的两个项具有相同状态,则在队列中停留时间最长的项将被赋予更高优先级。
使用索引编制队列将新项或已更改的项编入索引概览
图 1 显示了使用索引编制队列将新项或已更改项编入索引的步骤。以下步骤显示了 REST API 调用。如需了解等效的 SDK 调用,请参阅队列操作(连接器 SDK)。
内容连接器使用
items.push
将项(元数据和哈希)推送到索引编制队列中,以确定项的状态(MODIFIED
、NEW_ITEM
、DELETED
)。具体而言:- 推送时,连接器明确包含推送
type
或contentHash
。 - 如果连接器不包含
type
,则 Cloud Search 会自动使用contentHash
来确定项的状态。 - 如果内容未知,则内容状态会设为
NEW_ITEM
。 - 如果内容存在且哈希值匹配,则状态会保持为
ACCEPTED
。 - 如果内容存在且哈希不同,则状态会变为
MODIFIED
。
如需详细了解如何建立项目状态,请参阅 Cloud Search 使用入门教程中的遍历 GitHub 代码库示例代码。
通常,推送与连接器中的内容遍历和/或更改检测过程有关。
- 推送时,连接器明确包含推送
内容连接器使用
items.poll
轮询队列,以确定要编入索引的项。Cloud Search 会告知连接器哪些项最需要编入索引,然后依次按状态代码和排队时间排序。连接器会从代码库中检索这些项,并构建索引 API 请求。
连接器使用
items.index
将这些项编入索引。只有在 Cloud Search 成功处理该项后,该项才会进入ACCEPTED
状态。
如果某项内容在代码库中已不存在,连接器也可以将其删除;如果该内容未修改或源代码库存在错误,则再次推送该内容。如需了解如何删除项,请参阅下一部分。
使用索引编制队列删除项的概览
完全遍历策略使用双队列过程将项编入索引并检测删除。图 2 显示了使用两个索引队列删除项的步骤。具体而言,图 2 显示了使用完全遍历策略执行的第二次遍历。这些步骤使用 REST API 调用。如需了解等效的 SDK 调用,请参阅队列操作(连接器 SDK)。
在首次遍历时,内容连接器使用
items.push
将各项(元数据和哈希)推送到索引队列,并将“队列 A”作为NEW_ITEM
推送到索引队列,因为队列中不存在该队列。每个项目的“队列 A”都分配有一个标签“A”。相应内容会编入 Cloud Search 索引。内容连接器使用
items.poll
轮询队列 A 以确定要编入索引的项。Cloud Search 会告知连接器哪些项最需要编入索引,然后依次按状态代码和排队时间排序。连接器会从代码库中检索这些项,并构建索引 API 请求。
连接器使用
items.index
将这些项编入索引。只有在 Cloud Search 成功处理该项后,该项才会进入ACCEPTED
状态。deleteQueueItems
方法在“队列 B”上调用。但是,没有任何项被推送到队列 B,因此无法删除任何内容。在第二次完全遍历时,内容连接器使用
items.push
将项(元数据和哈希)推送到队列 B:- 推送时,连接器明确包含推送
type
或contentHash
。 - 如果连接器不包含
type
,则 Cloud Search 会自动使用contentHash
来确定项的状态。 - 如果项未知,项状态会设置为
NEW_ITEM
,队列标签会更改为“B”。 - 如果该项存在且哈希值匹配,则状态将保留为
ACCEPTED
,队列标签将更改为“B”。 - 如果该项存在并且哈希不同,则状态变为
MODIFIED
,队列标签将更改为“B”。
- 推送时,连接器明确包含推送
内容连接器使用
items.poll
轮询队列,以确定要编入索引的项。Cloud Search 会告知连接器哪些项最需要编入索引,然后依次按状态代码和排队时间排序。连接器会从代码库中检索这些项,并构建索引 API 请求。
连接器使用
items.index
将这些项编入索引。只有在 Cloud Search 成功处理该项后,该项才会进入ACCEPTED
状态。最后,对队列 A 调用
deleteQueueItems
,以删除先前编入索引但仍具有队列“A”标签的所有 CCloud Search 项。对于后续的完全遍历,用于编入索引的队列和用于删除的队列会交换。
队列操作 (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.poll
Items.poll 方法用于从队列中检索具有最高优先级的条目。请求的状态值和返回的状态值分别指示所请求优先级队列的状态或所返回 ID 的状态。
默认情况下,系统可以根据优先级返回任意队列部分中的条目。除非出现以下任一情况,否则返回的每个条目都会被预留,并且不会对 Items.poll
的其他调用返回:
- 预留超时。
- 通过
Items.index
将该条目再次加入队列。 Items.push
使用type
值NOT_MODIFIED
、REPOSITORY_ERROR
或REQUEUE
调用。