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
將項目 (中繼資料和雜湊) 推送至索引佇列,由於項目不存在於佇列中,「佇列 A」則是NEW_ITEM
。每個項目都會獲派「佇列 A」的標籤「A」。內容已編入索引到 Cloud Search。內容連接器會使用
items.poll
輪詢 A 佇列 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
,刪除先前編入索引但仍具有佇列「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 佇列會將提供的雜湊值與資料來源中項目的可用儲存值進行比較。如果不相符,該項目會標示為 MODIFIED
。如果索引中沒有對應的項目,則狀態是 NEW_ITEM
。
Items.poll
Items.poll 方法會從佇列中擷取優先順序最高的項目。要求和傳回的狀態值會指出要求的優先順序佇列狀態,或傳回 ID 的狀態。
根據預設,系統可能會根據優先順序傳回佇列中任何區段的項目。每個傳回的項目都會保留下來,除非滿足下列任一情況,否則對 Items.poll
的其他呼叫不會傳回傳回的項目:
- 預訂逾時。
- 項目會由
Items.index
再次排入佇列。 - 系統會使用
NOT_MODIFIED
、REPOSITORY_ERROR
或REQUEUE
的type
值呼叫Items.push
。