Google Cloud Search 索引佇列

Connector SDK 和 Google Cloud Search API 允許建立 Cloud Search 索引佇列，用於執行下列工作：

• 保留每份文件的狀態 (狀態、雜湊值等)，可用於讓索引與存放區保持同步。

• 維護項目清單，以利在周遊過程中找到並編入索引。

• 根據項目狀態決定佇列中的項目優先順序。

• 保留其他狀態資訊，以提升整合效率，例如查核點、變更權杖等。

佇列是指派給已建立索引項目的標籤，例如「預設」代表預設佇列，「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 呼叫，請參閱佇列作業 (連接器 SDK)。

圖 2. 刪除項目

注意： 在下面的步驟清單中，步驟 1 到 4 不會顯示，因為步驟 1 到 4 與上圖的步驟 1-4 相同，不屬於本節的涵蓋範圍。未顯示步驟 5，因為在空白佇列呼叫 deleteQueueItems 不在本節的範圍內。本圖表著重在第二個週遊。

1. 在初始週遊時，內容連接器會使用 items.push 將項目 (中繼資料和雜湊) 推送到索引佇列中，因為 A 佇列 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」佇列標籤的所有 CCloud Search 項目。

11. 隨著後續的完整週轉，用於建立索引的佇列和用於刪除的佇列會遭到替換。

佇列作業 (連接器 SDK)

Content Connector SDK 提供將項目推送至佇列中的作業，以及從佇列中提取項目的作業。

如要封裝及推送項目至佇列，請使用 pushItems 建構工具類別。

您無須對從佇列提取項目進行處理。相反地，SDK 會使用存放區類別的 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 會再次將項目排入佇列。
• 系統會用 NOT_MODIFIED、REPOSITORY_ERROR 或 REQUEUE 的 type 值呼叫 Items.push。