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 將項目 (中繼資料和雜湊) 推送至索引佇列,以建立項目狀態 (MODIFIEDNEW_ITEMDELETED)。具體來說:

    • 當推送時,連接器會明確包含推送 typecontentHash
    • 如果連接器未包含 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 將項目 (中繼資料和雜湊) 推送至索引佇列「queue A」,因為 NEW_ITEM 不存在於佇列中。每個項目都會指派「A」標籤,代表「佇列 A」。內容會建立索引並納入 Cloud Search。

  2. 內容連接器會使用 items.poll 輪詢佇列 A,以決定要索引的項目。Cloud Search 會告知連接器哪些項目最需要建立索引,並依狀態碼和佇列中等候的時間排序。

  3. 連接器會從存放區擷取這些項目,並建構索引 API 要求。

  4. 連接器會使用 items.index 為商品建立索引。只有在 Cloud Search 成功處理項目後,項目才會進入 ACCEPTED 狀態。

  5. 系統會在「佇列 B」上呼叫 deleteQueueItems 方法。但沒有任何項目已推送至佇列 B,因此無法刪除任何項目。

  6. 在第二次完整檢索時,內容連接器會使用 items.push 將項目 (中繼資料和雜湊值) 推送至佇列 B:

    • 當推送時,連接器會明確包含推送 typecontentHash
    • 如果連接器未包含 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,刪除所有先前已編入索引的 CCloud Search 項目,這些項目仍具有佇列「A」標籤。

  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_MODIFIEDREPOSITORY_ERRORREQUEUE,即可取消保留輪詢的項目。如要進一步瞭解已保留和未保留的項目,請參閱 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 會使用 typeNOT_MODIFIEDREPOSITORY_ERRORREQUEUE 來呼叫。