Google Cloud Search インデックス登録キュー

Connector SDK と Cloud Search REST API を使用すると、次のタスクを実行するために使用される Cloud Search インデックス登録キューを作成できます。

• インデックスとリポジトリとの同期を保つために使用できるドキュメントごとの状態（ステータス、ハッシュ値など）を維持する。

• 走査プロセスで検出されたインデックス登録されるアイテムのリストを維持する。

• アイテム ステータスに基づいてキュー内のアイテムの優先順位を付ける。

• チェックポイント、変更トークンなど、効率的に統合するための追加の状態情報を維持する。

キューはインデックス登録されたアイテムに割り当てられたラベルです。たとえば、デフォルトのキューの場合は「default」、キュー B の場合は「B」です。

ステータスと優先度

キュー内のドキュメントの優先度は、その ItemStatus コードに基づきます。次の ItemStatus コードは、優先度の高いものから順に処理されます。

• ERROR - インデックス登録中に非同期エラーが発生し、インデックスに再登録する必要があるアイテム。

• MODIFIED - 以前にインデックスに登録され、前回のインデックス登録以降にリポジトリ内で変更されたアイテム。

• NEW_ITEM - インデックスに登録されていないアイテム。

• ACCEPTED - 以前にインデックスに登録され、前回のインデックス登録以降にリポジトリ内で変更されていないドキュメント。

キュー内の 2 つのアイテムのステータスが同じ場合、長い時間キューに入っているアイテムの優先度が高くなります。

インデックス登録キューを使用した、新規または変更したアイテムのインデックス登録の概要

図 1 は、インデックス登録キューを使用して新規または変更したアイテムをインデックスに登録する手順を示しています。次の手順は REST API 呼び出しを示しています。同等の SDK 呼び出しについては、キュー オペレーション（Connector SDK）をご覧ください。

図 1. アイテムを追加または更新するためのインデックス登録手順

1. コンテンツ コネクタは items.push を使用してアイテム（メタデータとハッシュ）をインデックス登録キューに push し、アイテムのステータス（MODIFIED、NEW_ITEM、DELETED）を設定します。具体的には、次のようになります。

   • push する場合、コネクタには push type または contentHash が明示的に含まれます。
   • コネクタに type が含まれていない場合、Cloud Search は自動的に contentHash を使用してアイテムのステータスを判断します。
   • 商品アイテムが不明な場合、商品アイテムのステータスは NEW_ITEM に設定されます。
   • アイテムが存在し、ハッシュ値が一致する場合、ステータスは ACCEPTED として保持されます。
   • アイテムが存在し、ハッシュが異なる場合、ステータスは MODIFIED になります。

   アイテム ステータスの確立方法について詳しくは、Cloud Search スタートガイド チュートリアルの GitHub リポジトリの走査のサンプルコードをご覧ください。

   通常、push はコネクタでのコンテンツ走査と変更検出プロセスの両方またはいずれかに関連付けられます。

2. コンテンツ コネクタは、items.poll を使用してキューをポーリングし、インデックス登録するアイテムを決定します。Cloud Search は、最もインデックス登録が必要なアイテムをコネクタに示します。まず、ステータス コードで並べ替えられ、次にキューに入れられた時間で並べ替えられます。

3. コネクタは、これらのアイテムをリポジトリから取得し、インデックス API リクエストを作成します。

4. コネクタは、items.index を使用してアイテムをインデックスに登録します。Cloud Search がアイテムの処理を正常に終了しないと、アイテムは ACCEPTED 状態になりません。

コネクタは、リポジトリに存在しなくなったアイテムを削除することもできます。また、変更されていない場合やソース リポジトリ エラーが発生した場合は、アイテムを再度 push できます。アイテムの削除については、次のセクションをご覧ください。

注: フル走査など、一部の走査戦略では複数のインデックス登録キューが使用されます。2 つのキューがどのように使用されるかの例については、次のセクションをご覧ください。

インデックス登録キューを使用したアイテムの削除の概要

フル走査戦略では 2 キューのプロセスを使用してアイテムをインデックスに登録し、削除を検出します。図 2 は、2 つのインデックス キューを使用してアイテムを削除する手順を示しています。特に、図 2 はフル走査戦略を使用して実行された 2 回目の走査を示しています。この手順では、REST API 呼び出しを使用します。同等の SDK 呼び出しについては、キュー操作（コネクタ SDK）をご覧ください。

図 2. 項目の削除

注: 以下のステップリストでは、前の図のステップ 1 ～ 4 と同じで、このセクションでは説明していないステップ 1 ～ 4 を図 2 に示します。空のキューで deleteQueueItems を呼び出すことは、このセクションの対象範囲ではないため、ステップ 5 は表示されません。この図では、2 番目の走査に焦点を当てています。

1. 最初の走査で、コンテンツ コネクタは items.push を使用してアイテム（メタデータとハッシュ）をインデックス登録キューに「キュー A」をキューに push します（これはキューには存在しないためです）。各項目には「キュー A」に対して「A」というラベルが割り当てられます。コンテンツは Cloud Search にインデックスに登録されます。

   注: コネクタは、item.push または item.index オペレーション中に、アイテムの queue フィールドを使用してアイテムにキューラベルを割り当てることができます。このラベルは、アイテムが push または再インデックス登録されるたびに変更される可能性があります。

2. コンテンツ コネクタは、items.poll を使用してキュー A をポーリングし、インデックス登録するアイテムを決定します。Cloud Search は、最もインデックス登録が必要なアイテムをコネクタに示します。まず、ステータス コードで並べ替えられ、次にキューに入れられた時間で並べ替えられます。

3. コネクタは、これらのアイテムをリポジトリから取得し、インデックス API リクエストを作成します。

4. コネクタは、items.index を使用してアイテムをインデックスに登録します。Cloud Search がアイテムの処理を正常に終了しないと、アイテムは ACCEPTED 状態になりません。

5. deleteQueueItems メソッドは、「queue B."」で呼び出されます。ただし、キュー B にアイテムが push されていないため、何も削除できません。

6. 2 回目の完全走査では、コンテンツ コネクタは items.push を使用してアイテム（メタデータとハッシュ）をキュー B に push します。

   • push する場合、コネクタには push 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 は、キューにアイテムを push したり、キューからアイテムを pull したりするオペレーションを提供します。

アイテムをパッケージ化してキューに push するには、pushItems ビルダークラスを使用します。

処理のためにキューからアイテムを pull する場合、特別な操作を行う必要はありません。代わりに、SDK は Repository クラスの getDoc メソッドを使用して、順番にキューからアイテムを自動的に pull します。

キュー オペレーション（REST API）

REST API は、キューにアイテムを push し、キューからアイテムを pull する次の 2 つのメソッドを提供します。

• アイテムをキューに push するには、Items.push を使用します。
• キュー内のアイテムをポーリングするには、Items.poll を使用します。

Items.index を使用して、インデックス登録時にアイテムをキューに push することもできます。インデックス登録中にキューに push されたアイテムには type は不要であり、自動的に ACCEPTED のステータスが割り当てられます。

Items.push

Items.push メソッドは、キューに ID を追加します。このメソッドは、push オペレーションの結果を決定する特定の type 値で呼び出すことができます。type 値のリストについては、Items.push メソッドの item.type フィールドをご覧ください。

新しい ID を push すると、NEW_ITEM ItemStatus コードで新しいエントリが追加されます。

オプションのペイロードは常に保存され、不透明な値として扱われ、Items.poll から返されます。

ポーリングされたアイテムは予約され、Items.poll を再度呼び出すことで返せなくなります。type を Items.push を NOT_MODIFIED、REPOSITORY_ERROR、REQUEUE として使用して、ポーリングされたエントリを予約解除します。予約済みエントリと予約されていないエントリの詳細については、Items.poll をご覧ください。

ハッシュを含む Items.push

Cloud Search REST API では、Items.index リクエストでメタデータとコンテンツのハッシュ値を指定できます。type を指定する代わりに、push リクエストでメタデータやコンテンツのハッシュ値を指定できます。Cloud Search インデックス登録キューは、指定されたハッシュ値と、データソース内のアイテムに使用可能な格納値を比較します。一致しない場合、そのエントリは MODIFIED とマークされます。対応する項目がインデックスに存在しない場合、ステータスは NEW_ITEM になります。

注: Items.push リクエストで提供されたハッシュ値は、そのアイテムと一緒に保存されません。これらのアイテムは、アイテムが変更されたかどうかの判断にのみ使用されます。

Items.poll

Items.poll メソッドは、キューから優先度が最も高いエントリを取得します。リクエストされ、返されたステータス値は、リクエストされた優先キューのステータスまたは返された ID のステータスを示します。

デフォルトでは、優先度に基づいてキューのいずれかのセクションからエントリが返されます。返された各エントリは予約され、次のいずれかのケースが満たされるまで、Items.poll に対する他の呼び出しでは返されません。

• 予約がタイムアウトする。
• エントリが Items.index によって再びキューに追加されます。
• Items.push は、NOT_MODIFIED、REPOSITORY_ERROR、または REQUEUE の type 値で呼び出されます。