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)をご覧ください。
コンテンツ コネクタは、
items.push
を使用してアイテム(メタデータとハッシュ)をインデックス登録キューに push し、アイテムのステータス(MODIFIED
、NEW_ITEM
、DELETED
)を確立します。具体的には、次のようになります。- push する場合、コネクタには push の
type
またはcontentHash
が明示的に含まれます。 - コネクタに
type
が含まれていない場合、Cloud Search は自動的にcontentHash
を使用してアイテムのステータスを判断します。 - アイテムが不明な場合、アイテムのステータスは
NEW_ITEM
に設定されます。 - アイテムが存在し、ハッシュ値が一致する場合、ステータスは
ACCEPTED
のままです。 - アイテムが存在し、ハッシュが異なる場合、ステータスは
MODIFIED
になります。
アイテム ステータスの設定方法について詳しくは、Cloud Search スタートガイドのチュートリアルで GitHub リポジトリの走査のサンプルコードをご覧ください。
通常、push はコネクタのコンテンツ走査や変更検出プロセスに関連付けられます。
- push する場合、コネクタには push の
コンテンツ コネクタは
items.poll
を使用してキューをポーリングし、インデックス登録するアイテムを決定します。Cloud Search は、インデックス登録が最も必要なアイテムをコネクタに伝え、まずステータス コードで並べ替えられ、次にキューに入っている時間で並べ替えます。コネクタは、これらのアイテムをリポジトリから取得し、インデックス API リクエストを作成します。
コネクタは、
items.index
を使用してアイテムをインデックスに登録します。Cloud Search でアイテムの処理が正常に完了した後にのみ、アイテムがACCEPTED
状態になります。
コネクタは、アイテムがリポジトリに存在しなくなった場合は、そのアイテムを削除できます。また、アイテムが変更されていない場合や、ソース リポジトリにエラーが発生した場合には、アイテムを再度 push することもできます。アイテムの削除については、次のセクションをご覧ください。
インデックス登録キューを使用したアイテム削除の概要
フル走査戦略では、2 つのキュー プロセスを使用してアイテムにインデックスを作成し、削除を検出します。図 2 は、2 つのインデックス キューを使用してアイテムを削除する手順を示しています。特に図 2 は、フル走査戦略を使用して実行される 2 番目の走査を示しています。以下の手順では、REST API 呼び出しを使用します。同等の SDK 呼び出しについては、キュー オペレーション(Connector SDK)をご覧ください。
最初の走査時に、コンテンツ コネクタは
items.push
を使用してアイテム(メタデータとハッシュ)をインデックス登録キューに push します。「キュー A」はキューには存在しないためNEW_ITEM
となります。各アイテムには「キュー A」に対応するラベル「A」が割り当てられます。コンテンツが Cloud Search にインデックス登録されます。コンテンツ コネクタは
items.poll
を使用してキュー A をポーリングし、インデックス登録するアイテムを決定します。Cloud Search は、インデックス登録が最も必要なアイテムをコネクタに伝え、まずステータス コードで並べ替えられ、次にキューに入っている時間で並べ替えます。コネクタは、これらのアイテムをリポジトリから取得し、インデックス API リクエストを作成します。
コネクタは、
items.index
を使用してアイテムをインデックスに登録します。Cloud Search でアイテムの処理が正常に完了した後にのみ、アイテムがACCEPTED
状態になります。deleteQueueItems
メソッドは「キュー B」に対して呼び出されます。ただし、キュー B にアイテムが push されていないため、何も削除できません。2 回目のフル走査では、コンテンツ コネクタが
items.push
を使用してアイテム(メタデータとハッシュ)をキュー B に push します。- push する場合、コネクタには push の
type
またはcontentHash
が明示的に含まれます。 - コネクタに
type
が含まれていない場合、Cloud Search は自動的にcontentHash
を使用してアイテムのステータスを判断します。 - アイテムが不明な場合、アイテムのステータスは
NEW_ITEM
に設定され、キューのラベルは「B」に変更されます。 - アイテムが存在し、ハッシュ値が一致する場合、ステータスは
ACCEPTED
のままで、キューラベルは「B」に変更されます。 - アイテムが存在し、ハッシュが異なる場合、ステータスは
MODIFIED
になり、キューラベルは「B」に変更されます。
- push する場合、コネクタには push の
コンテンツ コネクタは
items.poll
を使用してキューをポーリングし、インデックス登録するアイテムを決定します。Cloud Search は、インデックス登録が最も必要なアイテムをコネクタに伝え、まずステータス コードで並べ替えられ、次にキューに入っている時間で並べ替えます。コネクタは、これらのアイテムをリポジトリから取得し、インデックス API リクエストを作成します。
コネクタは、
items.index
を使用してアイテムをインデックスに登録します。Cloud Search でアイテムの処理が正常に完了した後にのみ、アイテムがACCEPTED
状態になります。最後に、キュー A で
deleteQueueItems
が呼び出され、キュー「A」ラベルを持つ、以前にインデックスに登録された CCloud Search アイテムがすべて削除されます。その後のフル走査では、インデックス作成に使用されるキューと削除に使用されるキューが入れ替わります。
キュー オペレーション(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
に設定して呼び出されます。