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

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

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

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

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

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

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

ステータスと優先度

キュー内のドキュメントの優先度は、ItemStatus コードに基づいて決まります。以下に、使用可能な ItemStatus コードを優先度順（処理される順）に示します。

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

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

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

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

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

インデックス登録キューを使用して新規または変更されたアイテムをインデックス登録する概要

図 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 を使用してアイテムをインデックス登録します。アイテムが ACCEPTED 状態になるのは、Cloud Search がアイテムの処理を正常に完了した後のみです。

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

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

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

完全なトラバーサル戦略では、2 つのキュープロセスを使用してアイテムをインデックス登録し、削除を検出します。図 2 は、2 つのインデックス キューを使用してアイテムを削除する手順を示しています。具体的には、図 2 は、全走査戦略を使用して実行された 2 回目の走査を示しています。次の手順では、REST API 呼び出しを使用します。同等の SDK 呼び出しについては、キュー オペレーション（Connector SDK）をご覧ください。

図 2. アイテムの削除

注: 次の手順のリストでは、手順 1 ～ 4 は図 2 に示されていません。これは、前の図の手順 1 ～ 4 と同じであり、このセクションの範囲外であるためです。空のキューで deleteQueueItems を呼び出すことはこのセクションの範囲外であるため、ステップ 5 は表示されていません。この図は、2 回目のトラバーサルに焦点を当てています。

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

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

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

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

4. コネクタは items.index を使用してアイテムをインデックス登録します。アイテムが ACCEPTED 状態になるのは、Cloud Search がアイテムの処理を正常に完了した後のみです。

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

6. 2 回目の完全なトラバーサルでは、コンテンツ コネクタは 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 を使用してアイテムをインデックス登録します。アイテムが ACCEPTED 状態になるのは、Cloud Search がアイテムの処理を正常に完了した後のみです。

10. 最後に、キュー A で deleteQueueItems が呼び出され、キュー「A」ラベルがまだ付いている以前にインデックス登録されたすべての CCloud 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 をプッシュすると、NEW_ITEM ItemStatus コードの新しいエントリが追加されます。

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

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

ハッシュを含む Items.push

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

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

Items.poll

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

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

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