Connector SDK と Google Cloud Search API を使用すると、次のタスクを実行するために使用する Cloud Search インデックス登録キューを作成できます。
インデックスとリポジトリとの同期を保つために使用できるドキュメントごとの状態(ステータス、ハッシュ値など)を維持する。
走査プロセスで検出されたインデックス登録されるアイテムのリストを維持する。
アイテム ステータスに基づいてキュー内のアイテムの優先順位を付ける。
チェックポイント、変更トークンなど、効率的に統合するための追加の状態情報を維持する。
キューはインデックス付きアイテムに割り当てられるラベルです。たとえば、デフォルト キューの場合は「default」、キュー B の場合は「B」です。
ステータスと優先度
キュー内のドキュメントの優先度は、ItemStatus
コードに基づきます。以下に、可能な ItemStatus
コードを優先度順に示します(最初に処理されるものから最後に処理されるもの)。
ERROR
- インデックス登録中に非同期エラーが発生し、インデックスに再登録する必要があるアイテム。MODIFIED
- 以前にインデックスに登録され、前回のインデックス登録以降にリポジトリ内で変更されたアイテム。NEW_ITEM
- インデックスに登録されていないアイテム。ACCEPTED
- 以前にインデックスに登録され、前回のインデックス登録以降にリポジトリ内で変更されていないドキュメント。
キュー内の 2 つのアイテムのステータスが同じ場合、長い時間キューに入っているアイテムの優先度が高くなります。
インデックス登録キューを使用して新しいアイテムまたは変更されたアイテムをインデックスに登録する方法の概要
図 1 は、インデックス登録キューを使用して新しいアイテムまたは変更されたアイテムをインデックスに登録する手順を示しています。この手順では、REST API 呼び出しについて説明します。同等の SDK 呼び出しについては、キュー オペレーション(コネクタ 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
コンテンツ コネクタは、
items.poll
を使用してキューをポーリングし、インデックスに登録するアイテムを決定します。Cloud Search は、ステータス コード順、キュー内時間順に並べ替えられ、インデックス登録が必要なアイテムをコネクタに指示します。コネクタは、これらのアイテムをリポジトリから取得して、インデックス API リクエストを作成します。
コネクタは、
items.index
を使用してアイテムをインデックスに登録します。アイテムがACCEPTED
状態になるのは、Cloud Search がアイテムの処理を正常に終了した後のみです。
コネクタは、リポジトリに存在しなくなったアイテムを削除することもできます。また、アイテムが変更されていない場合やソース リポジトリにエラーが発生した場合は、アイテムを再度 push することもできます。アイテムの削除については、次のセクションをご覧ください。
インデックス登録キューを使用してアイテムを削除する方法の概要
フル走査戦略では、2 キュー プロセスを使用してアイテムをインデックスに登録し、削除を検出します。図 2 は、2 つのインデックス登録キューを使用してアイテムを削除する手順を示しています。具体的には、図 2 はフル走査戦略を使用して実行される 2 番目の走査を示しています。以下の手順では、REST API 呼び出しを使用します。同等の SDK 呼び出しについては、キュー オペレーション(コネクタ SDK)をご覧ください。
最初の走査時に、コンテンツ コネクタは
items.push
を使用してアイテム(メタデータとハッシュ)をインデックス キュー「キュー A」にNEW_ITEM
として push します(キューに存在しないため)。各項目には「キュー A」のラベル「A」が割り当てられます。コンテンツは Cloud Search のインデックスに登録されます。コンテンツ コネクタは、
items.poll
を使用してキュー A をポーリングし、インデックスに登録するアイテムを決定します。Cloud Search は、ステータス コード順、キュー内時間順に並べ替えられ、インデックス登録が必要なアイテムをコネクタに指示します。コネクタは、これらのアイテムをリポジトリから取得して、インデックス API リクエストを作成します。
コネクタは、
items.index
を使用してアイテムをインデックスに登録します。アイテムがACCEPTED
状態になるのは、Cloud Search がアイテムの処理を正常に終了した後のみです。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
を使用してアイテムをインデックスに登録します。アイテムがACCEPTED
状態になるのは、Cloud Search がアイテムの処理を正常に終了した後のみです。最後に、キュー A で
deleteQueueItems
が呼び出され、以前にインデックス付けされた CCloud Search アイテムのうち、まだキュー「A」のラベルが付いているものがすべて削除されます。その後のフル走査で、インデックス登録に使用されるキューと削除に使用されるキューがスワップされます。
キュー オペレーション(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 されたアイテムには 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
で type
を NOT_MODIFIED
、REPOSITORY_ERROR
、または REQUEUE
として使用すると、ポーリングされたエントリの予約解除が行われます。予約済みエントリと予約解除されたエントリの詳細については、Items.poll セクションをご覧ください。
ハッシュを含む Items.push
Google Cloud Search API では、Items.index
リクエストでメタデータとコンテンツ ハッシュ値を指定できます。type
を指定する代わりに、メタデータやコンテンツのハッシュ値を push リクエストで指定できます。Cloud Search インデックス登録キューは、指定されたハッシュ値を、データソース内のアイテムで利用可能な保存済み値と比較します。一致しない場合、そのエントリは MODIFIED
とマークされます。対応するアイテムがインデックスに存在しない場合、ステータスは NEW_ITEM
です。
Items.poll
Items.poll メソッドは、キューから優先度が最も高いエントリを取得します。リクエストされて返されるステータス値は、リクエストされた優先キューのステータスまたは返された ID のステータスを示します。
デフォルトでは、優先度に基づいてキューのいずれかのセクションからエントリが返されます。返される各エントリは予約されており、次のいずれかの条件が満たされるまで、Items.poll
の他の呼び出しでは返されません。
- 予約がタイムアウトする。
- エントリが
Items.index
によって再びキューに追加される。 Items.push
は、type
の値としてNOT_MODIFIED
、REPOSITORY_ERROR
、またはREQUEUE
を指定して呼び出されます。