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）をご覧ください。

Google Cloud Search のインデックス登録の概要
図 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 番目の走査を示しています。以下の手順では、REST API 呼び出しを使用します。同等の SDK 呼び出しについては、キュー オペレーション（Connector SDK）をご覧ください。

Google Cloud Search のインデックス登録の概要
図 2. アイテムの削除

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

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

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

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

  5. deleteQueueItems メソッドは「キュー 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」ラベルを持つ、以前にインデックスに登録された 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 を push すると、NEW_ITEM ItemStatus コードを使用して新しいエントリが追加されます。

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

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

Items.push（ハッシュ付き）

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

Items.poll

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

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

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