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)。

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 佇列 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 後便無法傳回該項目。將 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。