Connector SDK 和 Google Cloud Search API 可讓您建立用於執行下列任務的 Cloud Search 索引佇列:
維護每個文件的狀態 (狀態、雜湊值等),可用於讓索引與存放區保持同步。
在遍歷程序中發現的項目,會保留一份用於建立索引的項目清單。
根據項目狀態,決定佇列中項目的優先順序。
維護其他狀態資訊,以便有效整合,例如檢查點、變更權杖等。
佇列是指派給已編入索引項目的標籤,例如預設佇列的「default」或佇列 B 的「B」。
狀態和優先順序
文件在佇列中的優先順序取決於其 ItemStatus
程式碼。以下是可能的 ItemStatus
代碼,依優先順序排列 (先處理的代碼排在前面):
ERROR
- 項目在索引處理期間發生非同步錯誤,需要重新索引。MODIFIED
:先前已編入索引的項目,且自上次編入索引後,已在存放區中進行修改。NEW_ITEM
- 未編入索引的項目。ACCEPTED
:先前已編入索引的文件,且自上次編入索引後,在存放區中並未變更。
如果佇列中的兩項項目狀態相同,系統會將較高優先順序給予在佇列中等待最久的項目。
使用索引排程為新項目或變更項目建立索引的簡介
圖 1 顯示使用索引佇列為新項目或變更項目建立索引的步驟。這些步驟會顯示 REST API 呼叫。如需等同的 SDK 呼叫,請參閱「佇列作業 (Connector 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 呼叫,請參閱「佇列作業 (Connector SDK)」。
在初始遍歷時,內容連接器會使用
items.push
將項目 (中繼資料和雜湊) 推送至索引佇列「queue A」,因為NEW_ITEM
不存在於佇列中。每個項目都會指派「A」標籤,代表「佇列 A」。內容會建立索引並納入 Cloud Search。內容連接器會使用
items.poll
輪詢佇列 A,以決定要索引的項目。Cloud Search 會告知連接器哪些項目最需要建立索引,並依狀態碼和佇列中等候的時間排序。連接器會從存放區擷取這些項目,並建構索引 API 要求。
連接器會使用
items.index
為商品建立索引。只有在 Cloud Search 成功處理項目後,項目才會進入ACCEPTED
狀態。系統會在「佇列 B」上呼叫
deleteQueueItems
方法。但沒有任何項目已推送至佇列 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
,刪除所有先前已編入索引的 CCloud Search 項目,這些項目仍具有佇列「A」標籤。在後續的完整檢查作業中,系統會交換用於建立索引的佇列和用於刪除的佇列。
佇列作業 (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 索引佇列會將提供的雜湊值,與資料來源中項目可用的已儲存值進行比較。如果不相符,該項目會標示為 MODIFIED
。如果索引中沒有對應項目,則狀態為 NEW_ITEM
。
Items.poll
Items.poll 方法會從佇列中擷取最高優先順序的項目。所要求及傳回的狀態值,表示所要求的優先順序佇列狀態,或傳回 ID 的狀態。
根據預設,系統會根據優先順序,傳回佇列中任何部分的項目。每個傳回的項目都會保留,且不會由其他對 Items.poll
的呼叫傳回,直到符合下列任一情況為止:
- 預留作業逾時。
Items.index
會再次將項目排入佇列。Items.push
會使用type
值NOT_MODIFIED
、REPOSITORY_ERROR
或REQUEUE
來呼叫。