コンテンツ コネクタは、企業のリポジトリ内のデータを走査して所定のデータソースを完成する目的で使われるソフトウェア プログラムです。Google は以下のコンテンツ コネクタ開発オプションを提供しています。
Content Connector SDK。これは、Java でプログラミングする場合に適しています。Content Connector SDK は、コネクタをすばやく作成するための REST API を簡単に使えるようにしたラッパーです。この SDK でコンテンツ コネクタを作成する場合は、Content Connector SDK を使用してコンテンツ コネクタを作成するを参照してください。
低レベル REST API、その他の各種の API ライブラリ。Java を使用していない場合や、お客様のコードベースが REST API やライブラリに問題なく対応できる場合は、これらのオプションをご利用ください。この REST API を使用してコンテンツ コネクタを作成する場合は、REST API を使用してコンテンツ コネクタを作成するを参照してください。
コンテンツ コネクタで行われる標準的なタスクは次のとおりです。
- 構成パラメータを読み取り、処理する。
- インデックス登録可能な離散的なデータチャンク(これを「アイテム」と呼びます)をサードパーティのコンテンツ リポジトリから pull する。
- ACL、メタデータ、コンテンツ データを結合して、インデックス登録可能なアイテムを作成する。
- アイテムを Cloud Search データソースにインデックス登録する。
- (省略可)サードパーティのコンテンツ リポジトリからの変更通知を待ち受ける。変更通知をインデックス登録リクエストに変換し、これで Cloud Search データソースとサードパーティのリポジトリとの同期を維持する。なお、コンテンツ コネクタによるこのタスクは、リポジトリが変更検出機能に対応している場合にのみ行われます。
Content Connector SDK を使用してコンテンツ コネクタを作成する
以降のセクションでは、Content Connector SDK を使用してコンテンツ コネクタを作成する方法について説明します。
依存関係を設定する
SDK を使用するには、ビルドファイルに特定の依存関係を含める必要があります。下のタブをクリックすると、ビルド環境の依存関係が表示されます。
Maven
<dependency>
<groupId>com.google.enterprise.cloudsearch</groupId>
<artifactId>google-cloudsearch-indexing-connector-sdk</artifactId>
<version>v1-0.0.3</version>
</dependency>
Gradle
compile group: 'com.google.enterprise.cloudsearch',
name: 'google-cloudsearch-indexing-connector-sdk',
version: 'v1-0.0.3'
コネクタ構成を作成する
コネクタごとに対応する構成ファイルが存在し、コネクタはそこに含まれているパラメータ(お客様のリポジトリの ID など)を使用します。パラメータは api.sourceId=1234567890abcdef
などの Key-Value ペアとして定義されます。
Google Cloud Search SDK には、すべてのコネクタで使用される Google 提供構成パラメータが複数含まれています。以下の Google 提供パラメータをお客様の構成ファイル内で宣言してください。
- コンテンツ コネクタの場合、
api.sourceId
とapi.serviceAccountPrivateKeyFile
を宣言する必要があります。これらのパラメータにより、リポジトリの場所と、リポジトリへのアクセスに必要な秘密鍵が特定されます。
- ID コネクタの場合、このパラメータで外部 ID ソースの場所を識別するため、
api.identitySourceId
を宣言する必要があります。ユーザーを同期する場合は、api.customerId
を企業の Google Workspace アカウントの一意の ID として宣言する必要があります。
他の Google 提供パラメータのデフォルト値をオーバーライドしたい場合を除き、構成ファイルで宣言する必要はありません。特定の ID やキーの生成方法など、Google 提供の構成パラメータの詳細については、Google 提供の構成パラメータをご覧ください。
独自のリポジトリ パラメータを定義して、お客様の構成ファイル内で使用することもできます。
構成ファイルをコネクタに渡す
構成ファイルをコネクタに渡すには、システム プロパティ config
を設定します。このプロパティは、コネクタの起動時に -D
引数で設定できます。たとえば、次のコマンドは、MyConfig.properties
構成ファイルを使用してコネクタを起動します。
java -classpath myconnector.jar;... -Dconfig=MyConfig.properties MyConnector
この引数がない場合、SDK は connector-config.properties
という名前のデフォルト構成ファイルにアクセスしようとします。
使用する走査戦略を決める
コンテンツ コネクタの主な機能は、リポジトリを走査してそのデータをインデックス登録することです。お客様のリポジトリ内のデータの規模と配置に基づいて走査戦略を実装してください。お客様独自の戦略を設計することも、SDK に実装されている以下の戦略から選択することもできます。
- フル トラバーサル戦略
リポジトリ全体をスキャンして、すべてのアイテムを無分別にインデックス登録する戦略です。フル走査は、リポジトリの規模が小さく、インデックス登録するたびに全体を走査してもオーバーヘッドを許容できる場合によく使われる戦略です。
フル走査戦略は、概ね静的で階層構造を持たないデータを含む小規模なリポジトリに向いています。変更検出が困難なリポジトリや変更検出機能をサポートしていないリポジトリで使用することもあります。
- 走査戦略を一覧表示する
すべての子ノードを含むリポジトリ全体をスキャンして各アイテムのステータスを確認した後、2 回目のパスで前回のインデックス登録以降に作成または更新されたアイテムのみをインデックス登録する戦略です。リスト走査戦略は、インデックスを更新するたびに全体を走査しなくてもよい場合に、既存のインデックスを増分更新するためによく使われる戦略です。
リスト走査戦略は、変更検出が困難なリポジトリや変更検出機能をサポートしていないリポジトリで、データが階層化されておらず、扱うデータセットが非常に大規模であるようなケースに向いています。
- グラフ トラバーサル
親ノード全体をスキャンして各アイテムのステータスを確認した後、次に、コネクタは 2 回目のパスを行います。ルートノード内のインデックス アイテムは、前回のインデックス作成以降に新規に作成されたか、更新されています。最後に、コネクタは子 ID を渡してから、新規のノードまたは更新された子ノードのアイテムをインデックスに登録します。コネクタは、該当するアイテムがすべて処理されるまで、すべての子ノードを再帰的にスキャンします。この種の走査は、通常、ID をすべてリストすることが現実的でない階層的なリポジトリに対して使われます。
この戦略は、一連のディレクトリやウェブページなど、クロールする必要がある階層データがある場合に適しています。
各走査戦略は SDK のテンプレート コネクタクラスによって実装されます。独自の走査戦略を実装できますが、これらのテンプレートを使用すると、コネクタの開発が大幅に高速化されます。テンプレートを利用してコネクタを作成する場合は、使用する走査戦略に対応するセクションに進んでください。
- テンプレート クラスを使用してフル トラバーサル コネクタを作成する
- テンプレート クラスを使用してリスト トラバーサル コネクタを作成する
- テンプレート クラスを使用してグラフ トラバーサル コネクタを作成する
テンプレート クラスを使用してフル走査コネクタを作成する
Google ドキュメントの当該セクションのコード スニペットは、FullTraversalSample サンプルからの抜粋です。
コネクタのエントリ ポイントを実装する
コネクタのエントリ ポイントは main()
メソッドです。このメソッドの主なタスクは、Application
クラスのインスタンスを作成し、その start()
メソッドを呼び出してコネクタを実行することです。
application.start()
を呼び出す前に、IndexingApplication.Builder
クラスを使用して FullTraversalConnector
テンプレートをインスタンス化します。FullTraversalConnector
は、メソッドを実装する Repository
オブジェクトを受け入れます。次のコード スニペットは、main()
メソッドの実装方法を示しています。
コネクタの main()
メソッドが Application.build
を呼び出した後、バックグラウンドで SDK が initConfig()
メソッドを呼び出します。initConfig()
メソッドは、次のタスクを実行します。
Configuation.isInitialized()
メソッドを呼び出して、Configuration
が初期化されていないことを確認します。- Google 提供の Key-Value ペアを使用して
Configuration
オブジェクトを初期化します。各 Key-Value ペアは、Configuration
オブジェクト内のConfigValue
オブジェクトに格納されます。
Repository
インターフェースを実装する
Repository
オブジェクトの唯一の目的は、リポジトリ アイテムを走査してインデックスに登録することです。テンプレートを使用する場合は、Repository
インターフェース内の特定のメソッドをオーバーライドするだけでコンテンツ コネクタを作成できます。オーバーライドするメソッドは、使用するテンプレートと走査戦略によって異なります。FullTraversalConnector
で、次のメソッドをオーバーライドします。
init()
メソッド。データ リポジトリのセットアップと初期化を実行するには、init()
メソッドをオーバーライドします。getAllDocs()
メソッド。データ リポジトリ内のすべてのアイテムを走査してインデックスに登録するには、getAllDocs()
メソッドをオーバーライドします。このメソッドは、(お客様の構成で定義した)スケジュール済みの走査ごとに 1 回呼び出されます。(省略可)
getChanges()
メソッド。リポジトリが変更検出をサポートしている場合は、getChanges()
メソッドをオーバーライドします。このメソッドは、(お客様の構成で定義した)スケジュール済みの増分走査ごとに 1 回呼び出され、変更されたアイテムを取得してインデックス登録します。(省略可)
close()
メソッド。リポジトリのクリーンアップを行う必要がある場合は、close()
メソッドをオーバーライドします。このメソッドは、コネクタのシャットダウン時に 1 回呼び出されます。
Repository
オブジェクトの各メソッドは、ある種の ApiOperation
オブジェクトを返します。ApiOperation
オブジェクトは、1 回または場合によっては複数の IndexingService.indexItem()
呼び出しの形式でアクションを実行し、リポジトリの実際のインデックス登録を実行します。
カスタム構成パラメータを取得する
コネクタの構成を処理する一環として、Configuration
オブジェクトからカスタム パラメータを取得する必要があります。このタスクは通常、Repository
クラスの init()
メソッドで実行されます。
Configuration
クラスには、構成から異なるデータ型を取得するメソッドがいくつかあります。各メソッドは ConfigValue
オブジェクトを返します。次に、ConfigValue
オブジェクトの get()
メソッドを使用して、実際の値を取得します。次のスニペット(FullTraversalSample
)は、Configuration
オブジェクトから単一のカスタム整数値を取得する方法を示しています。
複数の値を含むパラメータを取得して解析するには、Configuration
クラスの型パーサーのいずれかを使用して、データを個別のチャンクに解析します。次のスニペットでは、チュートリアル コネクタから getMultiValue
メソッドを使用して、GitHub リポジトリ名のリストを取得します。
フル走査を実行する
getAllDocs()
をオーバーライドしてフル トラバーサルを実行し、リポジトリをインデックスに登録します。getAllDocs()
メソッドはチェックポイントを受け入れます。チェックポイントは、プロセスが中断された場合に特定のアイテムからインデックス登録を再開する目的で使用します。リポジトリ内のアイテムごとに、getAllDocs()
メソッドで次の手順を実行します。
- 権限を設定します。
- インデックス登録するアイテムのメタデータを設定する。
- メタデータとアイテムをインデックス可能な 1 つの
RepositoryDoc
にまとめます。 - インデックス登録可能な各アイテムを、
getAllDocs()
メソッドから返されたイテレータにパッケージ化します。getAllDocs()
は実際にはCheckpointCloseableIterable
を返します。これはApiOperation
オブジェクトの反復処理であり、各オブジェクトはインデックス作成などのRepositoryDoc
で実行される API リクエストを表します。
アイテムサイズが 1 回の呼び出しで処理するには大きすぎる場合は、チェックポイントを追加して hasMore(true)
を設定し、インデックス登録可能なアイテムが多いことを示します。
アイテムへのアクセス許可を設定する
リポジトリは、アイテムにアクセスできるユーザーまたはグループを識別するためにアクセス制御リスト(ACL)を使用します。ACL は、アイテムにアクセスできるグループまたはユーザーの ID のリストです。
検索結果には、アイテムにアクセスできるユーザーだけが、そのアイテムを使用する ACL を複製する必要があります。アイテムのインデックスを作成する際には、アイテムの ACL を含める必要があります。これにより、Google Cloud Search がアイテムへの適切なアクセスレベルを指定するために必要な情報が得られます。
Content Connector SDK は、リポジトリの ACL をモデル化するために必要な一連の ACL クラスやメソッドを潤沢に提供しているため、ほとんどのリポジトリに対応できます。アイテムをインデックス登録するときは、リポジトリ内の各アイテムの ACL を分析して、Google Cloud Search の対応する ACL を作成する必要があります。リポジトリの ACL で ACL の継承といったコンセプトが用いられている場合、その ACL をモデル化するのは厄介な作業になるかもしれません。Google Cloud Search の ACL の詳細は、Google Cloud Search の ACL を参照してください。
注: Cloud Search の Indexing API がサポートしているのは単一ドメインの ACL であって、クロスドメインの ACL ではありません。ACL を使用して各アイテムへのアクセスを設定するには、Acl.Builder
クラスを使用します。完全な走査のサンプルから得られる次のコード スニペットでは、検索を行うときにすべてのユーザーまたは「プリンシパル」(getCustomerPrincipal()
)をすべてのアイテムの「.setReaders()
」にすることができます。
リポジトリの ACL を適切にモデル化するには、ACL を理解する必要があります。たとえば、あるファイル システムのファイルをインデックス登録するとき、そのファイル システムである種の継承モデルが用いられているために、子フォルダが親フォルダからアクセス権を継承する場合があります。ACL の継承をモデル化するためには、Google Cloud Search の ACL で解説している追加情報が必要です。
アイテムのメタデータを設定する
メタデータは Item
オブジェクトに格納されます。Item
を作成するには、アイテムの一意の文字列 ID、アイテムタイプ、ACL、URL、およびバージョンが必要です。次のコード スニペットは、IndexingItemBuilder
ヘルパークラスを使用して、Item
を作成する方法を示しています。
インデックス登録可能なアイテムを作成する
アイテムのメタデータを設定したら、RepositoryDoc.Builder
クラスを使用して実際のインデックス登録可能なアイテムを作成できます。次の例は、単一のインデックス登録可能なアイテムを作成する方法を示しています。
RepositoryDoc
は、実際の IndexingService.indexItem()
リクエストを実行する ApiOperation
の一種です。
また、RepositoryDoc.Builder
クラスの setRequestMode()
メソッドを使用して、インデックス登録リクエストを ASYNCHRONOUS
または SYNCHRONOUS
として識別することもできます。
ASYNCHRONOUS
- 非同期モードを使用すると、インデックス登録から提供までのレイテンシが長くなり、インデックス登録リクエストに大量のスループット割り当てが適用されます。非同期モードは、リポジトリ全体の初期インデックス(バックフィル)に推奨されます。
SYNCHRONOUS
- 同期モードにすると、インデックス登録からサービス提供までのレイテンシが短くなり、スループットの割り当てが制限されます。同期モードは、リポジトリの更新や変更をインデックス登録するケースで使うことをおすすめします。指定しない場合、リクエスト モードはデフォルトで
SYNCHRONOUS
になります。
イテレータ内のインデックス登録可能な各アイテムをパッケージ化する
getAllDocs()
メソッドは、RepositoryDoc
オブジェクトの Iterator
(特に CheckpointCloseableIterable
)を返します。CheckpointClosableIterableImpl.Builder
クラスを使用して、イテレータを構築して返すことができます。次のコード スニペットは、イテレータを構築して返す方法を示しています。
SDK は、イテレータの範囲に含まれる各インデックス登録呼び出しを実行します。
次のステップ
必要に応じて次の手順を行います。
- (省略可)インデックス登録のスループットが遅いと思われる場合は、
FullTraversalConnector
のインデックス登録率を上げるをご覧ください。 - (省略可)
close()
メソッドを実装して、シャットダウン前にリソースを解放します。 - (省略可)Content Connector SDK で ID コネクタを作成する。
テンプレート クラスを使用してリスト走査コネクタを作成する
Cloud Search インデックス登録キューの目的は、リポジトリ内の各アイテムの ID(および必要に応じてハッシュ値)を保持することです。リスト走査コネクタは、Google Cloud Search インデックス登録キューにアイテム ID を push し、インデックス登録のためにそこから 1 つずつ取得します。Google Cloud Search はキューを維持管理し、キューの内容を比較することでアイテムのステータス(アイテムがリポジトリから削除済みかどうかなど)を確認します。Cloud Search インデックス登録キューの詳細については、Cloud Search インデックス登録キューをご覧ください。
ドキュメントの当該セクションのコード スニペットは、ListTraversalSample サンプルからの抜粋です。
コネクタのエントリ ポイントを実装する
コネクタのエントリ ポイントは main()
メソッドです。このメソッドの主なタスクは、Application
クラスのインスタンスを作成し、その start()
メソッドを呼び出してコネクタを実行することです。
application.start()
を呼び出す前に、IndexingApplication.Builder
クラスを使用して ListingConnector
テンプレートをインスタンス化します。ListingConnector
は、メソッドを実装する Repository
オブジェクトを受け入れます。次のスニペットは、ListingConnector
とそれに関連付けられた Repository
をインスタンス化する方法を示しています。
コネクタの main()
メソッドが Application.build
を呼び出した後、バックグラウンドで SDK が initConfig()
メソッドを呼び出します。initConfig()
メソッド:
Configuation.isInitialized()
メソッドを呼び出して、Configuration
が初期化されていないことを確認します。- Google 提供の Key-Value ペアを使用して
Configuration
オブジェクトを初期化します。各 Key-Value ペアは、Configuration
オブジェクト内のConfigValue
オブジェクトに格納されます。
Repository
インターフェースを実装する
Repository
オブジェクトの唯一の目的は、リポジトリ アイテムを走査してインデックスに登録することです。テンプレートを使用する場合は、Repository
インターフェース内の特定のメソッドをオーバーライドするだけでコンテンツ コネクタを作成できます。オーバーライドするメソッドは、使用するテンプレートと走査戦略によって異なります。ListingConnector
の場合は、次のメソッドをオーバーライドします。
init()
メソッド。データ リポジトリのセットアップと初期化を実行するには、init()
メソッドをオーバーライドします。getIds()
メソッド。リポジトリ内のすべてのレコードの ID とハッシュ値を取得するには、getIds()
メソッドをオーバーライドします。getDoc()
メソッド。インデックスの項目を追加、更新、変更、削除するには、getDoc()
メソッドをオーバーライドします。(省略可)
getChanges()
メソッド。リポジトリが変更検出をサポートしている場合は、getChanges()
メソッドをオーバーライドします。このメソッドは、(お客様の構成で定義した)スケジュール済みの増分走査ごとに 1 回呼び出され、変更されたアイテムを取得してインデックス登録します。(省略可)
close()
メソッド。リポジトリのクリーンアップを行う必要がある場合は、close()
メソッドをオーバーライドします。このメソッドは、コネクタのシャットダウン時に 1 回呼び出されます。
Repository
オブジェクトの各メソッドは、ある種の ApiOperation
オブジェクトを返します。ApiOperation
オブジェクトは、1 回または場合によっては複数の IndexingService.indexItem()
呼び出しの形式でアクションを実行し、リポジトリの実際のインデックス登録を実行します。
カスタム構成パラメータを取得する
コネクタの構成を処理する一環として、Configuration
オブジェクトからカスタム パラメータを取得する必要があります。このタスクは通常、Repository
クラスの init()
メソッドで実行されます。
Configuration
クラスには、構成から異なるデータ型を取得するメソッドがいくつかあります。各メソッドは ConfigValue
オブジェクトを返します。次に、ConfigValue
オブジェクトの get()
メソッドを使用して、実際の値を取得します。次のスニペット(FullTraversalSample
)は、Configuration
オブジェクトから単一のカスタム整数値を取得する方法を示しています。
複数の値を含むパラメータを取得して解析するには、Configuration
クラスの型パーサーのいずれかを使用して、データを個別のチャンクに解析します。次のスニペットでは、チュートリアル コネクタから getMultiValue
メソッドを使用して、GitHub リポジトリ名のリストを取得します。
リスト走査を実行する
getIds()
メソッドをオーバーライドして、リポジトリ内のすべてのレコードの ID とハッシュ値を取得します。getIds()
メソッドはチェックポイントを受け入れます。チェックポイントは、プロセスが中断された場合に特定のアイテムからインデックス登録を再開する目的で使用します。
次に、getDoc()
メソッドをオーバーライドして、Cloud Search インデックス登録キューの各項目を処理します。
アイテムの ID とハッシュ値を push する
getIds()
をオーバーライドして、アイテム ID とそれに関連するコンテンツ ハッシュ値をリポジトリから取得します。その後、ID とハッシュ値のペアをパッケージ化して、Cloud Search インデックス登録キューに対する push 操作リクエストを作成します。通常、ルート(または親)の ID が最初に push され、続いて子の ID が push されます。こうしてアイテムの階層全体が処理されます。
getIds()
メソッドは、インデックスに登録される最後のアイテムを表すチェックポイントを受け入れます。チェックポイントは、プロセスが中断された場合に特定のアイテムからインデックス登録を再開する目的で使用します。リポジトリ内のアイテムごとに、getIds()
メソッドで次の手順を実行します。
- 各アイテムの ID と関連ハッシュ値をリポジトリから取得する。
- 各 ID とハッシュ値のペアを
PushItems
にパッケージ化します。 - 各
PushItems
を、getIds()
メソッドから返されるイテレータに結合します。実際には、ApiOperation
オブジェクトの反復であるCheckpointCloseableIterable
が返されます。各オブジェクトは、RepositoryDoc
に対して実行された API リクエスト(アイテムをキューに push するなど)を表します。getIds()
次のコード スニペットは、各アイテム ID とハッシュ値を取得して、PushItems
に挿入する方法を示しています。
PushItems
は、アイテムを Cloud Search インデックス登録キューに push する ApiOperation
リクエストです。
次のコード スニペットは、PushItems.Builder
クラスを使用して、ID とハッシュ値を単一の push ApiOperation
にパッケージ化する方法を示しています。
アイテムは、Cloud Search インデックス登録キューに push 後、さらに処理されます。
各アイテムを取得して処理する
getDoc()
をオーバーライドして、Cloud Search インデックス登録キューの各項目を処理します。アイテムは、新規、変更、未変更にできます。また、ソース リポジトリに存在しなくなっている場合もあります。新規または変更済みの各アイテムを取得してインデックス登録します。ソース リポジトリにもう存在しないアイテムをインデックスから取り除きます。
getDoc()
メソッドは、Google Cloud Search インデックス登録キューのアイテムを受け入れます。キュー内のアイテムごとに、getDoc()
メソッドで次の操作を行います。
Cloud Search インデックス登録キュー内のアイテムの ID がリポジトリに存在するかどうかを確認し、存在しなければアイテムをインデックスから削除する。
インデックス登録対象のアイテムのステータスをポーリングし、アイテムが未変更(
ACCEPTED
)の場合は何もしない。変更済みまたは新規のアイテムをインデックス登録する:
- アクセス許可を設定する。
- インデックス登録するアイテムのメタデータを設定する。
- メタデータとアイテムをインデックス可能な 1 つの
RepositoryDoc
にまとめます。 RepositoryDoc
を返します。
注: ListingConnector
テンプレートでは、getDoc()
メソッドでの null
の返しをサポートしていません。null
の結果が NullPointerException.
になる
削除対象のアイテムを処理する
次のコード スニペットは、アイテムがリポジトリに存在するかどうか確認して存在しない場合に削除する方法を示しています。
documents
は、リポジトリを表すデータ構造です。documents
で documentID
が見つからない場合は、APIOperations.deleteItem(resourceName)
を返してインデックスからアイテムを削除します。
未変更のアイテムを処理する
次のコード スニペットは、Cloud Search インデックス登録キュー内のアイテムのステータスをポーリングし、未変更のアイテムを処理する方法を示しています。
未変更アイテムであるか確認するには、変更の可能性を示すアイテムのステータスとその他のメタデータを調べます。この例では、アイテムが変更されたかどうかを確認するために、メタデータであるハッシュを使用しています。
アイテムへのアクセス許可を設定する
リポジトリは、アイテムにアクセスできるユーザーまたはグループを識別するためにアクセス制御リスト(ACL)を使用します。ACL は、アイテムにアクセスできるグループまたはユーザーの ID のリストです。
検索結果には、アイテムにアクセスできるユーザーだけが、そのアイテムを使用する ACL を複製する必要があります。アイテムのインデックスを作成する際には、アイテムの ACL を含める必要があります。これにより、Google Cloud Search がアイテムへの適切なアクセスレベルを指定するために必要な情報が得られます。
Content Connector SDK は、リポジトリの ACL をモデル化するために必要な一連の ACL クラスやメソッドを潤沢に提供しているため、ほとんどのリポジトリに対応できます。アイテムをインデックス登録するときは、リポジトリ内の各アイテムの ACL を分析して、Google Cloud Search の対応する ACL を作成する必要があります。リポジトリの ACL で ACL の継承といったコンセプトが用いられている場合、その ACL をモデル化するのは厄介な作業になるかもしれません。Google Cloud Search の ACL の詳細は、Google Cloud Search の ACL を参照してください。
注: Cloud Search の Indexing API がサポートしているのは単一ドメインの ACL であって、クロスドメインの ACL ではありません。ACL を使用して各アイテムへのアクセスを設定するには、Acl.Builder
クラスを使用します。完全な走査のサンプルから得られる次のコード スニペットでは、検索を行うときにすべてのユーザーまたは「プリンシパル」(getCustomerPrincipal()
)をすべてのアイテムの「.setReaders()
」にすることができます。
リポジトリの ACL を適切にモデル化するには、ACL を理解する必要があります。たとえば、あるファイル システムのファイルをインデックス登録するとき、そのファイル システムである種の継承モデルが用いられているために、子フォルダが親フォルダからアクセス権を継承する場合があります。ACL の継承をモデル化するためには、Google Cloud Search の ACL で解説している追加情報が必要です。
アイテムのメタデータを設定する
メタデータは Item
オブジェクトに格納されます。Item
を作成するには、アイテムの一意の文字列 ID、アイテムタイプ、ACL、URL、およびバージョンが必要です。次のコード スニペットは、IndexingItemBuilder
ヘルパークラスを使用して、Item
を作成する方法を示しています。
インデックス登録可能なアイテムを作成する
アイテムのメタデータを設定したら、RepositoryDoc.Builder
を使用して実際のインデックス登録可能なアイテムを作成できます。次の例は、単一のインデックス登録可能なアイテムを作成する方法を示しています。
RepositoryDoc
は、実際の IndexingService.indexItem()
リクエストを実行する ApiOperation
の一種です。
また、RepositoryDoc.Builder
クラスの setRequestMode()
メソッドを使用して、インデックス登録リクエストを ASYNCHRONOUS
または SYNCHRONOUS
として識別することもできます。
ASYNCHRONOUS
- 非同期モードを使用すると、インデックス登録から提供までのレイテンシが長くなり、インデックス登録リクエストに大量のスループット割り当てが適用されます。非同期モードは、リポジトリ全体の初期インデックス(バックフィル)に推奨されます。
SYNCHRONOUS
- 同期モードにすると、インデックス登録からサービス提供までのレイテンシが短くなり、スループットの割り当てが制限されます。同期モードは、リポジトリの更新や変更をインデックス登録するケースで使うことをおすすめします。指定しない場合、リクエスト モードはデフォルトで
SYNCHRONOUS
になります。
次のステップ
必要に応じて次の手順を行います。
- (省略可)
close()
メソッドを実装して、シャットダウン前にリソースを解放します。 - (省略可)Content Connector SDK で ID コネクタを作成する。
テンプレート クラスを使用してグラフ走査コネクタを作成する
Cloud Search インデックス登録キューの目的は、リポジトリ内の各アイテムの ID(および必要に応じてハッシュ値)を保持することです。グラフ トラバーサル コネクタは、アイテム ID を Google Cloud Search インデックス登録キューに push し、インデックス登録のために一度に 1 つずつ取得します。Google Cloud Search はキューを維持管理し、キューの内容を比較することでアイテムのステータス(アイテムがリポジトリから削除済みかどうかなど)を確認します。Cloud Search インデックス登録キューの詳細については、Google Cloud Search インデックス登録キューをご覧ください。
インデックス登録の過程で、アイテムのコンテンツがデータ リポジトリからフェッチされ、すべての子アイテムの ID がキューに push されます。コネクタによる親 ID と子 ID の処理は、すべてのアイテムが処理されるまで再帰的に進行します。
Google ドキュメントの当該セクションのコード スニペットは、GraphTraversalSample サンプルからの抜粋です。
コネクタのエントリ ポイントを実装する
コネクタのエントリ ポイントは main()
メソッドです。このメソッドの主なタスクは、Application
クラスのインスタンスを作成し、その start()
メソッドを呼び出してコネクタを実行することです。
application.start()
を呼び出す前に、IndexingApplication.Builder
クラスを使用して ListingConnector
テンプレートをインスタンス化します。ListingConnector
は、メソッドを実装する Repository
オブジェクトを受け入れます。
次のスニペットは、ListingConnector
とそれに関連付けられた Repository
をインスタンス化する方法を示しています。
コネクタの main()
メソッドが Application.build
を呼び出した後、バックグラウンドで SDK が initConfig()
メソッドを呼び出します。initConfig()
メソッド:
Configuation.isInitialized()
メソッドを呼び出して、Configuration
が初期化されていないことを確認します。- Google 提供の Key-Value ペアを使用して
Configuration
オブジェクトを初期化します。各 Key-Value ペアは、Configuration
オブジェクト内のConfigValue
オブジェクトに格納されます。
Repository
インターフェースを実装する
Repository
オブジェクトの唯一の目的は、リポジトリ アイテムの走査とインデックス登録を行うことです。テンプレートを使用する場合は、Repository
インターフェース内の特定のメソッドをオーバーライドしてコンテンツ コネクタを作成する必要があります。オーバーライドするメソッドは、使用するテンプレートと走査戦略によって異なります。ListingConnector
では、次のメソッドをオーバーライドします。
init()
メソッド。データ リポジトリのセットアップと初期化を実行するには、init()
メソッドをオーバーライドします。getIds()
メソッド。リポジトリ内のすべてのレコードの ID とハッシュ値を取得するには、getIds()
メソッドをオーバーライドします。getDoc()
メソッド。インデックスの項目を追加、更新、変更、削除するには、getDoc()
メソッドをオーバーライドします。(省略可)
getChanges()
メソッド。リポジトリが変更検出をサポートしている場合は、getChanges()
メソッドをオーバーライドします。このメソッドは、(お客様の構成で定義した)スケジュール済みの増分走査ごとに 1 回呼び出され、変更されたアイテムを取得してインデックス登録します。(省略可)
close()
メソッド。リポジトリのクリーンアップを行う必要がある場合は、close()
メソッドをオーバーライドします。このメソッドは、コネクタのシャットダウン時に 1 回呼び出されます。
Repository
オブジェクトの各メソッドは、ある種の ApiOperation
オブジェクトを返します。ApiOperation
オブジェクトは、1 回または複数の IndexingService.indexItem()
呼び出しの形式でアクションを実行し、リポジトリの実際のインデックス登録を実行します。
カスタム構成パラメータを取得する
コネクタの構成を処理する一環として、Configuration
オブジェクトからカスタム パラメータを取得する必要があります。このタスクは通常、Repository
クラスの init()
メソッドで実行されます。
Configuration
クラスには、構成から異なるデータ型を取得するメソッドがいくつかあります。各メソッドは ConfigValue
オブジェクトを返します。次に、ConfigValue
オブジェクトの get()
メソッドを使用して、実際の値を取得します。次のスニペット(FullTraversalSample
)は、Configuration
オブジェクトから単一のカスタム整数値を取得する方法を示しています。
複数の値を含むパラメータを取得して解析するには、Configuration
クラスの型パーサーのいずれかを使用して、データを個別のチャンクに解析します。次のスニペットでは、チュートリアル コネクタから getMultiValue
メソッドを使用して、GitHub リポジトリ名のリストを取得します。
グラフ走査を実行する
getIds()
メソッドをオーバーライドして、リポジトリ内のすべてのレコードの ID とハッシュ値を取得します。getIds()
メソッドはチェックポイントを受け入れます。チェックポイントは、プロセスが中断された場合に特定のアイテムからインデックス登録を再開する目的で使用します。
次に、getDoc()
メソッドをオーバーライドして、Cloud Search インデックス登録キューの各項目を処理します。
アイテムの ID とハッシュ値を push する
getIds()
をオーバーライドして、アイテム ID とそれに関連するコンテンツ ハッシュ値をリポジトリから取得します。その後、ID とハッシュ値のペアをパッケージ化して、Cloud Search インデックス登録キューに対する push 操作リクエストを作成します。通常、ルート(または親)の ID が最初に push され、続いて子の ID が push されます。こうしてアイテムの階層全体が処理されます。
getIds()
メソッドは、インデックスに登録される最後のアイテムを表すチェックポイントを受け入れます。チェックポイントは、プロセスが中断された場合に特定のアイテムからインデックス登録を再開する目的で使用します。リポジトリ内のアイテムごとに、getIds()
メソッドで次の手順を実行します。
- 各アイテムの ID と関連ハッシュ値をリポジトリから取得する。
- 各 ID とハッシュ値のペアを
PushItems
にパッケージ化します。 - 各
PushItems
を、getIds()
メソッドから返されるイテレータに結合します。実際には、ApiOperation
オブジェクトの反復であるCheckpointCloseableIterable
が返されます。各オブジェクトは、RepositoryDoc
に対して実行された API リクエスト(アイテムをキューに push するなど)を表します。getIds()
次のコード スニペットは、各アイテム ID とハッシュ値を取得して PushItems
に挿入する方法を示しています。PushItems
は、アイテムを Cloud Search インデックス登録キューに push する ApiOperation
リクエストです。
次のコード スニペットは、PushItems.Builder
クラスを使用して、ID とハッシュ値を単一の push ApiOperation
にパッケージ化する方法を示しています。
アイテムは、Cloud Search インデックス登録キューに push 後、さらに処理されます。
各アイテムを取得して処理する
getDoc()
をオーバーライドして、Cloud Search インデックス登録キューの各項目を処理します。アイテムは、新規、変更、未変更にできます。また、ソース リポジトリに存在しなくなっている場合もあります。新規または変更済みの各アイテムを取得してインデックス登録します。ソース リポジトリにもう存在しないアイテムをインデックスから取り除きます。
getDoc()
メソッドは、Cloud Search インデックス登録キューのアイテムを受け入れます。キュー内のアイテムごとに、getDoc()
メソッドで次の操作を行います。
Cloud Search インデックス登録キュー内のアイテムの ID がリポジトリに存在するかどうかを確認し、存在しなければアイテムをインデックスから削除する。存在する場合は、次の手順に進む。
変更済みまたは新規のアイテムをインデックス登録する:
- アクセス許可を設定する。
- インデックス登録するアイテムのメタデータを設定する。
- メタデータとアイテムをインデックス可能な 1 つの
RepositoryDoc
にまとめます。 - 子の ID を Cloud Search インデックス登録キューに入れて処理を続ける。
RepositoryDoc
を返します。
削除対象のアイテムを処理する
次のコード スニペットは、アイテムがインデックスに存在するかどうか確認して存在しない場合に削除する方法を示しています。
アイテムへのアクセス許可を設定する
リポジトリは、アイテムにアクセスできるユーザーまたはグループを識別するためにアクセス制御リスト(ACL)を使用します。ACL は、アイテムにアクセスできるグループまたはユーザーの ID のリストです。
検索結果には、アイテムにアクセスできるユーザーだけが、そのアイテムを使用する ACL を複製する必要があります。アイテムのインデックスを作成する際には、アイテムの ACL を含める必要があります。これにより、Google Cloud Search がアイテムへの適切なアクセスレベルを指定するために必要な情報が得られます。
Content Connector SDK は、リポジトリの ACL をモデル化するために必要な一連の ACL クラスやメソッドを潤沢に提供しているため、ほとんどのリポジトリに対応できます。アイテムをインデックス登録するときは、リポジトリ内の各アイテムの ACL を分析して、Google Cloud Search の対応する ACL を作成する必要があります。リポジトリの ACL で ACL の継承といったコンセプトが用いられている場合、その ACL をモデル化するのは厄介な作業になるかもしれません。Google Cloud Search の ACL の詳細は、Google Cloud Search の ACL を参照してください。
注: Cloud Search の Indexing API がサポートしているのは単一ドメインの ACL であって、クロスドメインの ACL ではありません。ACL を使用して各アイテムへのアクセスを設定するには、Acl.Builder
クラスを使用します。完全な走査のサンプルから得られる次のコード スニペットでは、検索を行うときにすべてのユーザーまたは「プリンシパル」(getCustomerPrincipal()
)をすべてのアイテムの「.setReaders()
」にすることができます。
リポジトリの ACL を適切にモデル化するには、ACL を理解する必要があります。たとえば、あるファイル システムのファイルをインデックス登録するとき、そのファイル システムである種の継承モデルが用いられているために、子フォルダが親フォルダからアクセス権を継承する場合があります。ACL の継承をモデル化するためには、Google Cloud Search の ACL で解説している追加情報が必要です。
アイテムのメタデータを設定する
メタデータは Item
オブジェクトに格納されます。Item
を作成するには、アイテムの一意の文字列 ID、アイテムタイプ、ACL、URL、およびバージョンが必要です。次のコード スニペットは、IndexingItemBuilder
ヘルパークラスを使用して、Item
を作成する方法を示しています。
インデックス登録可能なアイテムを作成する
アイテムのメタデータを設定したら、RepositoryDoc.Builder
を使用して実際のインデックス登録可能なアイテムを作成できます。次の例は、単一のインデックス登録可能なアイテムを作成する方法を示しています。
RepositoryDoc
は、実際の IndexingService.indexItem()
リクエストを実行する ApiOperation
の一種です。
また、RepositoryDoc.Builder
クラスの setRequestMode()
メソッドを使用して、インデックス登録リクエストを ASYNCHRONOUS
または SYNCHRONOUS
として識別することもできます。
ASYNCHRONOUS
- 非同期モードを使用すると、インデックス登録から提供までのレイテンシが長くなり、インデックス登録リクエストに大量のスループット割り当てが適用されます。非同期モードは、リポジトリ全体の初期インデックス(バックフィル)に推奨されます。
SYNCHRONOUS
- 同期モードにすると、インデックス登録からサービス提供までのレイテンシが短くなり、スループットの割り当てが制限されます。同期モードは、リポジトリの更新や変更をインデックス登録するケースで使うことをおすすめします。指定しない場合、リクエスト モードはデフォルトで
SYNCHRONOUS
になります。
子の ID を Cloud Search インデックス登録キューに入れる
次のコード スニペットは、現在処理中の親アイテムの子の ID をキューに入れて処理する方法を示しています。これらの ID は、親アイテムのインデックス登録後に処理されます。
次のステップ
必要に応じて次の手順を行います。
- (省略可)
close()
メソッドを実装して、シャットダウン前にリソースを解放します。 - (省略可)Identity Connector SDK で ID コネクタを作成する。
REST API を使用してコンテンツ コネクタを作成する
以下のセクションでは、REST API を使用してコンテンツ コネクタを作成する方法を説明します。
使用する走査戦略を決める
コンテンツ コネクタの主な機能は、リポジトリを走査してそのデータをインデックス登録することです。お客様のリポジトリ内のデータの規模と配置に基づいて走査戦略を実装してください。よく使われる走査戦略は以下の 3 つです。
- フル トラバーサル戦略
リポジトリ全体をスキャンして、すべてのアイテムを無分別にインデックス登録する戦略です。フル走査は、リポジトリの規模が小さく、インデックス登録するたびに全体を走査してもオーバーヘッドを許容できる場合によく使われる戦略です。
フル走査戦略は、概ね静的で階層構造を持たないデータを含む小規模なリポジトリに向いています。変更検出が困難なリポジトリや変更検出機能をサポートしていないリポジトリで使用することもあります。
- 走査戦略を一覧表示する
すべての子ノードを含むリポジトリ全体をスキャンして各アイテムのステータスを確認した後、2 回目のパスで前回のインデックス登録以降に作成または更新されたアイテムのみをインデックス登録する戦略です。リスト走査戦略は、インデックスを更新するたびに全体を走査しなくてもよい場合に、既存のインデックスを増分更新するためによく使われる戦略です。
リスト走査戦略は、変更検出が困難なリポジトリや変更検出機能をサポートしていないリポジトリで、データが階層化されておらず、扱うデータセットが非常に大規模であるようなケースに向いています。
- グラフ トラバーサル
親ノード全体をスキャンして各アイテムのステータスを確認した後、次に、コネクタは 2 回目のパスを行います。ルートノード内のインデックス アイテムは、前回のインデックス作成以降に新規に作成されたか、更新されています。最後に、コネクタは子 ID を渡してから、新規のノードまたは更新された子ノードのアイテムをインデックスに登録します。コネクタは、該当するアイテムがすべて処理されるまで、すべての子ノードを再帰的にスキャンします。この種の走査は、通常、ID をすべてリストすることが現実的でない階層的なリポジトリに対して使われます。
グラフ走査戦略は、一連のディレクトリやウェブページのような階層的なデータに対してクロール操作でデータを収集するケースに向いています。
走査戦略を実装しアイテムをインデックス登録する
Cloud Search では、インデックス登録可能な要素はすべて「アイテム」と呼ばれます。アイテムとしては、ファイル、フォルダ、CSV ファイル内の行、データベース レコードなどがあります。
スキーマを登録した後、次の方法で所定のインデックスを完成できます。
(省略可)インデックス登録用に 100 KiB を超えるファイルをアップロードするには、
items.upload
を使用します。サイズが小さいファイルの場合は、items.index
を使用して inlineContent としてコンテンツを埋め込みます。(省略可)
media.upload
を使用してインデックス登録用のメディア ファイルをアップロードします。items.index
を使用してアイテムをインデックスに登録します。 たとえば、スキーマが映画スキーマのオブジェクト定義を使用している場合、1 つのアイテムのインデックス登録リクエストは次のようになります。{ "name": "datasource/<data_source_id>/items/titanic", "acl": { "readers": [ { "gsuitePrincipal": { "gsuiteDomain": true } } ] }, "metadata": { "title": "Titanic", "viewUrl": "http://www.imdb.com/title/tt2234155/?ref_=nv_sr_1", "objectType": "movie" }, "structuredData": { "object": { "properties": [ { "name": "movieTitle", "textValues": { "values": [ "Titanic" ] } }, { "name": "releaseDate", "dateValues": { "values": [ { "year": 1997, "month": 12, "day": 19 } ] } }, { "name": "actorName", "textValues": { "values": [ "Leonardo DiCaprio", "Kate Winslet", "Billy Zane" ] } }, { "name": "genre", "enumValues": { "values": [ "Drama", "Action" ] } }, { "name": "userRating", "integerValues": { "values": [ 8 ] } }, { "name": "mpaaRating", "textValues": { "values": [ "PG-13" ] } }, { "name": "duration", "textValues": { "values": [ "3 h 14 min" ] } } ] } }, "content": { "inlineContent": "A seventeen-year-old aristocrat falls in love with a kind but poor artist aboard the luxurious, ill-fated R.M.S. Titanic.", "contentFormat": "TEXT" }, "version": "01", "itemType": "CONTENT_ITEM" }
フル走査を実行するには、リポジトリ全体を定期的に繰り返しインデックス登録します。リストまたはグラフの走査を実行するには、リポジトリの変更を処理するコードを実装する必要があります。
リポジトリの変更を処理する
リポジトリ内の各アイテムを定期的に収集してインデックス登録することで完全な形のインデックスを作成できます。完全な形のインデックスの作成は、インデックスを最新状態に維持するには効果的ですが、リポジトリの規模が大きい場合や階層構造を持つ場合にコストがかかる可能性があります。
インデックス登録呼び出しを使用してリポジトリ全体を毎回繰り返しインデックス登録する代わりに、Google Cloud インデックス登録キューを変更追跡メカニズムとして使用し、変更されたアイテムだけをインデックス登録する方法もあります。items.push リクエストを使用して、アイテムをポーリングして、後でポーリングおよび更新できます。Google Cloud インデックス登録キューの詳細については、Google Cloud インデックス登録キューを参照してください。
Google Cloud Search API の詳細については、Cloud Search API をご覧ください。