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 呼叫，請參閱佇列作業 (Connector 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 呼叫，請參閱「佇列作業 (Connector SDK)」。

圖 2. 刪除項目

注意： 在下列步驟清單中，步驟 1 至 4 未顯示於圖 2，因為這些步驟與上一個圖表的步驟 1 至 4 相同，且不在本節的範圍內。由於在空白佇列上呼叫 deleteQueueItems 不屬於本節範圍，因此不會顯示步驟 5。這張圖著重於第二次遍歷。

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. 系統會對「佇列 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」佇列標籤的 Cloud 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 索引佇列會比較提供的雜湊值與資料來源中項目可用的儲存值。如果兩者不符，該項目會標示為 MODIFIED。如果索引中沒有對應項目，狀態會顯示 NEW_ITEM。

注意： 系統不會將透過 Items.push 要求提供的雜湊值與項目一併儲存。這些項目只會用於判斷項目是否經過修改。

Items.poll

Items.poll 方法會從佇列中擷取優先順序最高的項目。要求和傳回的狀態值會指出所要求優先順序佇列的狀態，或是傳回 ID 的狀態。

根據預設，系統可能會根據優先順序，傳回佇列中任何部分的項目。每個傳回的項目都會保留，且在符合下列其中一種情況前，不會由其他對 Items.poll 的呼叫傳回：

• 預留時間逾時。
• Items.index 會再次將項目加入佇列。
• Items.push 呼叫時，type 值為 NOT_MODIFIED、REPOSITORY_ERROR 或 REQUEUE。