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. 刪除項目

注意： 在下列步驟清單中，圖 2 未顯示步驟 1 至 4，因為這些步驟與上一個圖表中的步驟 1 至 4 相同，且不在本節的範圍內。系統不會顯示步驟 5，因為在空白佇列上呼叫 deleteQueueItems 不在本節的範圍內。下圖著重說明第二週遊。

1. 在初始遍歷時，內容連接器會使用 items.push 將項目 (中繼資料和雜湊) 推送至索引佇列，並將「queue A」設為 NEW_ITEM，因為該項目不在佇列中。每個項目都會獲派「佇列 A」的標籤「A」。內容會建立索引並納入 Cloud Search。

   注意： 連接器可以在 item.push 或 item.index 作業期間，使用項目的 queue 欄位，將佇列標籤指派給項目。每次重新推送或重新建立索引項目時，都可以修改這個標籤。

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 索引佇列會將提供的雜湊值，與資料來源中項目可用的已儲存值進行比較。如果不相符，該項目會標示為 MODIFIED。如果索引中沒有對應項目，則狀態為 NEW_ITEM。

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

Items.poll

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

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

• 預訂逾時。
• 項目會由 Items.index 再次排入佇列。
• Items.push 會使用 type 值 NOT_MODIFIED、REPOSITORY_ERROR 或 REQUEUE 來呼叫。