すべてのコネクタには、コネクタが使用するパラメータ（リポジトリの ID など）を含む構成ファイルが関連付けられています。パラメータは、api.sourceId=1234567890abcdef などの Key-Value ペアとして定義されます。
Google Cloud Search SDK には、さまざまなコネクタで使用される Google 提供の構成パラメータがいくつか含まれています。構成ファイルで定義する必要があるのは、Google 提供の構成パラメータのうちデータソース アクセス パラメータのみです。デフォルト値をオーバーライドする場合を除き、構成ファイルで Google 提供のパラメータを再定義する必要はありません。
このリファレンスでは、Google 提供の構成パラメータについて説明します。
構成ファイルの例
次の例は、パラメータの Key-Value ペアを含む ID 構成ファイルを示しています。
# # Configuration file sample # api.sourceId=1234567890abcdef api.identitySourceId=0987654321lmnopq api.serviceAccountPrivateKeyFile= ./PrivateKey.json # # Traversal schedules # schedule.traversalIntervalSecs=7200 schedule.incrementalTraversalIntervalSecs=600 # # Default ACLs # defaultAcl.mode=fallback defaultAcl.public=true
よく設定されるパラメータ
このセクションでは、よく設定される必須の構成パラメータとオプションを一覧で示します。オプションのパラメータの値を変更しない場合、コネクタは SDK によって提供されるデフォルト値を使用します。
データソース アクセス
次の表に、構成ファイルに指定する必要があるすべてのパラメータを示します。使用するパラメータは、構築するコネクタのタイプ（コンテンツ コネクタまたは ID コネクタ）によって異なります。
| 設定 | パラメータ |
|---|---|
| データソースの ID | api.sourceId=1234567890abcdef
このパラメータは、リポジトリの場所を特定するためにコネクタで必要です。この値は、検索対象のデータソースを追加したときに取得されます。このパラメータは、コネクタ構成ファイルに含める必要があります。 |
| ID ソースの ID | api.identitySourceId=0987654321lmnopq
このパラメータは、外部 ID ソースの場所を識別するために ID コネクタで必要です。この値は、Cloud Search でユーザー ID をマッピングしたときに取得しました。このパラメータは、すべての ID コネクタ構成ファイルに含める必要があります。 |
| サービス アカウントの秘密鍵ファイル | api.serviceAccountPrivateKeyFile=./PrivateKey.json
このパラメータには、リポジトリへのアクセスに必要な秘密鍵が含まれています。この値は、Google Cloud Search REST API へのアクセスを構成したときに取得しました。このパラメータは、すべての構成ファイルに含める必要があります。 |
| サービス アカウント ID | api.serviceAccountId=123abcdef4567890
このパラメータには、サービス アカウント ID を指定します。デフォルトの空の文字列値は、構成ファイルで秘密鍵ファイル パラメータが指定されている場合にのみ使用できます。秘密鍵ファイルが JSON キーでない場合、このパラメータは必須です。 |
| Google Workspace アカウント ID | api.customerId=123abcdef4567890
このパラメータでは、企業の Google Workspace アカウントのアカウント ID を指定します。この値は、Cloud Search でユーザー ID をマッピングしたときに取得しました。このパラメータは、ID コネクタを使用してユーザーを同期するときに必要です。 |
| ルート URL | api.rootUrl=baseURLPath
このパラメータでは、インデックス登録サービスのベース URL パスを指定します。 このパラメータのデフォルト値は、 |
走査スケジュール
スケジュール関連のパラメータでは、コネクタの走査間隔（頻度）を指定します。
| 設定 | パラメータ |
|---|---|
| コネクタの起動時にフル走査 | schedule.performTraversalOnStart=true|false
コネクタは、最初の間隔が期限切れになるのを待たずに、コネクタの起動時にフル走査を実行します。デフォルト値は |
| 一定間隔後のフル走査 | schedule.traversalIntervalSecs=intervalInSeconds
コネクタは、指定された間隔後にフル走査を実行します。走査の間隔は秒単位で指定します。デフォルト値は |
| 1 回の移動後に終了 | connector.runOnce=true|false
コネクタはフル走査を 1 回実行した後、終了します。このパラメータは、フル走査戦略を使用する場合にのみ |
| 一定間隔後の増分走査 | schedule.incrementalTraversalIntervalSecs=intervalInSeconds
指定した間隔が経過すると、コネクタは増分走査を実行します。走査から次の走査までの時間間隔を秒単位で指定します。デフォルト値は |
| スケジュール設定されたアンケートのキュー間隔 | schedule.pollQueueIntervalSecs=interval_in_seconds
スケジュールされたアンケート キューの間隔（秒単位）。これはリスティング走査コネクタでのみ使用されます。デフォルト値は |
アクセス制御リスト
コネクタは ACL を使用してアイテムへのアクセスを制御します。複数のパラメータを使用すると、ACL を使用してインデックス付きレコードへのユーザー アクセスを保護できます。
リポジトリに個々のアイテムに関連付けられた個別の ACL 情報がある場合は、すべての ACL 情報をアップロードして、Cloud Search 内のアイテム アクセスを制御します。リポジトリで ACL 情報が部分的で提供されるか、まったく提供されない場合は、SDK からコネクタに提供される次のパラメータでデフォルトの ACL 情報を指定できます。
| 設定 | パラメータ |
|---|---|
| ACL モード | defaultAcl.mode=mode
デフォルト ACL を適用するタイミングを決定します。有効な値は次のとおりです。
デフォルトのモードは |
| デフォルトのパブリック ACL | defaultAcl.public=true|false
リポジトリ全体に使用されるデフォルトの ACL は、パブリック ドメイン アクセスに設定されています。デフォルト値は |
| 一般的な ACL グループ リーダー | defaultAcl.readers.groups=google:group1@mydomain.com,
group2 |
| 一般的な ACL リーダー | defaultAcl.readers.users=user1, user2,
google:user3@mydomain.com |
| 一般的な ACL 拒否グループ リーダー | defaultAcl.denied.groups=group3 |
| 一般的な ACL 拒否リーダー | defaultAcl.denied.users=user4, user5 |
| ドメイン全体のアクセス | すべてのインデックス付きレコードがドメイン内のすべてのユーザーが一般公開されるように指定するには、次の両方のパラメータに値を設定します。
|
| 共通定義 ACL | データ リポジトリのレコードごとに 1 つの ACL を指定するには、次のパラメータ値をすべて設定します。
|
メタデータ構成パラメータ
アイテムのメタデータの一部は構成可能です。コネクタでは、インデックス登録時に構成可能なメタデータ フィールドを設定できます。コネクタがフィールドを設定しない場合、構成ファイル内のパラメータを使用してフィールドが設定されます。
構成ファイルには、.field サフィックスで示される一連の名前付きメタデータ構成パラメータがあります（itemMetadata.title.field=movieTitle など）。これらのパラメータの値が存在する場合は、メタデータ フィールドの構成に使用されます。名前付きメタデータ パラメータの値が存在しない場合、メタデータは .defaultValue 接尾辞の付いたパラメータを使用して構成されます。
次の表に、メタデータ構成パラメータを示します。
| 設定 | パラメータ |
| Title | itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=
アイテムのタイトル。 title.field が値に設定されていない場合は、title.defaultValue の値が使用されます。 |
| ソース リポジトリの URL | itemMetadata.sourceRepositoryUrl.field=url
itemMetadata.sourceRepositoryUrl.defaultValue=https://www.imdb.com/title/tt0031381/
検索結果で使用されるアイテムの URL。リポジトリが CSV ファイルで、アイテムごとに URL が 1 つしかない場合など、リポジトリ全体の URL を保持するように defaultValue を設定するだけで済みます。sourceRepositoryUrl.field が値に設定されていない場合は、sourceRepositoryUrl.defaultValue の値が使用されます。 |
| コンテナ名 | itemMetadata.containerName.field=containerName
itemMetadata.containerName.defaultValue=myDefaultContainerName
アイテムのコンテナ名（ファイル システムのディレクトリ名やフォルダ名など）。 containerName.field が値に設定されていない場合は、containerName.defaultValue の値が使用されます。 |
| オブジェクト タイプ | itemMetadata.objectType.field=typeitemMetadata.objectType.defaultValue=
コネクタで使用されるオブジェクト タイプ（スキーマで定義されている）。このプロパティが指定されていない場合、コネクタは構造化データをインデックスに登録しません。 objectType.field が値に設定されていない場合は、objectType.defaultValue の値が使用されます。 |
| 作成日時 | itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17
ドキュメント作成時のタイムスタンプ。 createTime.field が値に設定されていない場合は、createTime.defaultValue の値が使用されます。 |
| 更新日時 | itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17
アイテムの最終変更タイムスタンプ。 updateTime.field が値に設定されていない場合は、updateTime.defaultValue の値が使用されます。 |
| コンテンツの言語 | itemMetadata.contentLanguage.field=languageCode
itemMetadata.contentLanguage.defaultValue=
インデックスに登録するドキュメントのコンテンツ言語。 contentLanguage.field が値に設定されていない場合は、contentLanguage.defaultValue の値が使用されます。 |
| MIME タイプ | itemMetadata.mimeType.field=mimeType
itemMetadata.mimeType.defaultValue=
ソース リポジトリにある ItemContent.content の元の MIME タイプ。最大文字数は 256 文字です。 mimeType.field が値に設定されていない場合は、mimeType.defaultValue の値が使用されます。 |
| 検索品質メタデータ | itemMetadata.searchQualityMetadata.quality.field=quality
itemMetadata.searchQualityMetadata.quality.defaultValue=
商品アイテムの品質の指標で、検索の品質に影響します。値は 0.0（最低品質）～ 1.0（最高品質）の範囲で指定してください。デフォルト値は 0.0 です。 quality.field が値に設定されていない場合は、quality.defaultValue の値が使用されます。 |
| ハッシュ | itemMetadata.hash.field=hash
itemMetadata.hash.defaultValue=f0fda58630310a6dd91a7d8f0a4ceda2
API 呼び出し元が提供するハッシュ化値。これを items.push メソッドと併用すると、変更済み状態を計算できます。最大文字数は 2,048 文字です。hash.field が値に設定されていない場合は、hash.defaultValue の値が使用されます。 |
日時書式
日時書式は、期待される書式をメタデータ属性で指定するものです。構成ファイルにこのパラメータが含まれていない場合は、デフォルト値が使用されます。次の表に、このパラメータを示します。
| 設定 | パラメータ |
| 追加の日時書式 | structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
追加の java.time.format.DateTimeFormatter パターンをセミコロンで区切ったリスト。このパターンは、メタデータまたはスキーマ内の日付フィールドや日時フィールドの文字列値を解析する際に使用されます。デフォルト値は空のリストですが、RFC 3339 と RFC 1123 の形式は常にサポートされています。 |
構造化データ
Cloud Search Indexing API は、Cloud Search でデータのインデックス登録と表示をカスタマイズするために使用できるスキーマ サービスを提供します。ローカル リポジトリ スキーマを使用している場合は、構造化データのローカル スキーマ名を指定する必要があります。
| 設定 | パラメータ |
|---|---|
| ローカル スキーマ名 | structuredData.localSchema=mySchemaName
スキーマ名がデータソースから読み取られ、リポジトリの構造化データに使用されます。 デフォルトは空の文字列です。 |
コンテンツと検索の品質
レコードまたはフィールドベースのコンテンツを含むリポジトリ（CRM、CVS、データベースなど）の場合、SDK ではデータ フィールドの自動 HTML フォーマットが可能になります。コネクタはコネクタの実行の開始時にデータ フィールドを定義します。次に、各データレコードを Cloud Search にアップロードする前に、コンテンツ テンプレートを使用して各データレコードをフォーマットします。
コンテンツ テンプレートでは、検索における各フィールド値の重要度を定義します。HTML の <title> フィールドは必須であり、最も高い優先度として定義されています。検索品質の重要度は、他のすべてのコンテンツ フィールド（高、中、低）に指定できます。特定のカテゴリで定義されていないコンテンツ フィールドの優先度はデフォルトで低になります。
| 設定 | パラメータ |
|---|---|
| コンテンツの HTML タイトル | contentTemplate.templateName.title=myTitleField
コンテンツの HTML タイトルと最高検索品質フィールド。このパラメータは、HTML コンテンツ テンプレートを使用している場合にのみ必要です。デフォルト値は空の文字列です。 |
| コンテンツ フィールドの検索品質が高い | contentTemplate.templateName.quality.high=hField1,hField2
検索の優先度が高いコンテンツ フィールドです。デフォルトは空の文字列です。 |
| コンテンツ フィールドの検索品質: 中 | contentTemplate.templateName.quality.medium=mField1,mField2
検索優先度が中程度のコンテンツ フィールド。デフォルトは空の文字列です。 |
| コンテンツ フィールドの検索品質が低い | contentTemplate.templateName.quality.low=lField1,lField2
検索の優先度が低いコンテンツ フィールドです。デフォルトは空の文字列です。 |
| 未指定のコンテンツ フィールド | contentTemplate.templateName.unmappedColumnsMode=value
未指定のフィールドに対するコネクタでの処理方法。有効な値は次のとおりです。
|
| HTML テンプレートにフィールド名を含める | contentTemplate.templateName.includeFieldName=true|false
HTML テンプレートにフィールド データとともにフィールド名を含めるかどうかを指定します。デフォルトは |
あまり一般的でないパラメータの設定
このセクションに記載されているパラメータを設定する必要はほとんどありません。パラメータのデフォルトは、最適なパフォーマンスが得られるように設定されています。リポジトリ内に特定の要件がなければ、これらのパラメータをデフォルト値とは異なる値に設定することはおすすめしません。
プロキシの構成
この SDK では、送信接続にプロキシを使用するようにコネクタを設定できます。
transport.proxy.hostname パラメータと transport.proxy.port パラメータは、プロキシ経由の転送を有効にするために必要です。プロキシが認証を必要とする場合や、HTTP ではなく SOCKS プロトコルを介して動作する場合は、他のパラメータが必要になることがあります。transport.proxy.hostname が設定されていない場合、SDK はプロキシを使用しません。
| 設定 | パラメータ |
|---|---|
| ホスト名 | transport.proxy.hostname=hostname
プロキシ サーバーのホスト名。プロキシを使用する場合、このパラメータは必須です。 |
| ポート | transport.proxy.port=port
プロキシ サーバーのポート番号。プロキシを使用する場合、このパラメータは必須です。 |
| プロキシの種類 | transport.proxy.type=type
プロキシのタイプ。有効な値は次のとおりです。
デフォルト値は |
| ユーザー名 | transport.proxy.username=username
プロキシ認証トークンの作成時に使用するユーザー名。このパラメータはオプションであり、プロキシで認証が必要な場合にのみ設定する必要があります。 |
| パスワード | transport.proxy.password=password
プロキシ認証トークンの作成時に使用するパスワード。このパラメータはオプションであり、プロキシで認証が必要な場合にのみ設定する必要があります。 |
トラバーサー
SDK を使用すると、複数の個別の走査を指定して、データ リポジトリの並列走査を行うことができます。SDK テンプレート コネクタはこの機能を使用します。
| 設定 | パラメータ |
|---|---|
| スレッドプール サイズ | traverse.threadPoolSize=size
並列処理を可能にするためにコネクタが作成するスレッドの数。1 つのイテレータはオペレーションを順次取得しますが（通常は RepositoryDoc オブジェクト）、API はこの数のスレッドを使用して処理を並列に呼び出します。 デフォルト値は |
| パーティション サイズ | traverse.partitionSize=batchSize
追加の デフォルト値は |
トラバーサー ポーリング リクエスト
Cloud Search インデックス登録キューの中核は、存在することがわかっている各アイテムのエントリを含む優先キューです。リスティング コネクタは、Indexing API からアイテムをポーリングするようリクエストできます。ポーリング リクエストは、インデックス登録キューから優先度が最も高いエントリを取得します。
SDK リスティング コネクタ テンプレートでは、次のパラメータを使用してポーリング パラメータを定義します。
| 設定 | パラメータ |
|---|---|
| リポジトリ トラバーサー | repository.traversers=t1, t2, t3, ...
1 つ以上の個別の走査を作成します。t1、t2、t3、... は、それぞれの一意の名前です。各名前付き走査には、 |
| ポーリングされるキュー | traverser.pollRequest.queue=mySpecialQueue
この走査がポーリングするキュー名。デフォルトは空の文字列です（「default」を意味します）。 |
traverser.t1.pollRequest.queue=mySpecialQueue
複数の走査がある場合は、走査ごとにアイテムのステータスを設定します（t1 は特定の走査を表します）。 |
|
| ポーリングの動作 | traverser.pollRequest.limit=maxItems
ポーリング リクエストから返されるアイテムの最大数。デフォルト値は |
traverser.t1.pollRequest.limit=limit
複数の走査がある場合は、走査ごとにアイテムのステータスを設定します（t1 は特定の走査を表します）。 |
|
| アイテムのステータス | traverser.pollRequest.statuses=statuses
この走査がポーリングする特定のアイテムのステータス。statuses には、 |
traverser.t1.pollRequest.statuses=statusesForThisTraverser
複数の走査がある場合は、走査ごとにアイテムのステータスを設定します（t1 は特定の走査を表します）。 | |
| ホスト負荷 | traverser.hostload=threads
ポーリングに使用できるアクティブな並列スレッドの最大数。デフォルト値は |
traverser.t1.hostload=threadsForThisTraverser
複数の走査がある場合は、走査ごとにアイテムのステータスを設定します（t1 は特定の走査を表します）。 |
|
| タイムアウト | traverser.timeout=timeout
この走査ポーリングの試行を中断するためのタイムアウト値。 デフォルト値は |
traverser.t1.timeout=timeoutForThisTraverser
複数の走査がある場合は、走査ごとにアイテムのステータスを設定します（t1 は特定の走査を表します）。 |
|
traverser.timeunit=timeoutUunit
タイムアウトの単位。有効な値は |
|
traverser.t1.timeunit=timeoutUnit
複数の走査がある場合は、走査ごとにアイテムのステータスを設定します（t1 は特定の走査を表します）。 |
ほとんどの場合、SDK リスティング コネクタ テンプレートを使用するコネクタに必要なのは、ポーリングで必要なパラメータ セット 1 つのみです。走査アルゴリズムで異なるキューを使用してアイテム処理を分離する必要がある場合は、複数のポーリング条件の定義が必要になることがあります。
この場合、複数のポーリング パラメータ セットを定義できます。まず、repository.traversers を使用してパラメータ セットの名前を指定します。定義されたトラバーサー名ごとに、上記の表のパラメータを含む構成ファイルを指定します。t1 はトラバーサー名に置き換えます。これにより、定義された走査ごとにポーリング パラメータのセットが作成されます。
チェックポイント
チェックポイントは、増分走査の状態を追跡するのに役立ちます。
| 設定 | パラメータ |
|---|---|
| チェックポイント ディレクトリ | connector.checkpointDirectory=/path/to/checkpoint
増分チェックポイントとフル走査チェックポイントに使用するローカル ディレクトリへのパスを指定します。 |
コンテンツのアップロード
コンテンツのサイズが指定されたしきい値を超えていなければ、アイテムのコンテンツがアイテムと一緒に Cloud Search にアップロードされます。コンテンツのサイズがしきい値を超える場合、コンテンツはアイテムのメタデータや構造化データとは別にアップロードされます。
| 設定 | パラメータ |
|---|---|
| コンテンツのしきい値 | api.contentUploadThresholdBytes=bytes
コンテンツのしきい値。アイテムと一緒に「インライン」でアップロードするか、別のアップロードでアップロードするかを決定します。 デフォルト値は |
コンテナ
完全なコネクタ テンプレートでは、データベース内で削除されたレコードを検出するために、データソースの一時的なキュー切り替えというコンセプトを含むアルゴリズムを使用します。つまり、フル走査のたびに、取得されたレコード（新しいキューに格納）によって、以前の走査でインデックス登録された、古いキューにある既存の Cloud Search レコードがすべて置き換えられます。
| 設定 | パラメータ |
|---|---|
| コンテナの名前タグ | traverse.queueTag=instance
コネクタの複数のインスタンスを互いに干渉することなく、共通のデータ リポジトリ（異なるデータ リポジトリまたは共通のデータ リポジトリの別々の部分）をインデックス登録するには、コネクタの実行ごとに一意のコンテナ名タグを割り当てます。一意の名前タグにより、コネクタ インスタンスが別のレコードを削除できないようにします。 名前タグは、フル走査コネクタの切り替えキュー ID に追加されます。 |
| 削除の検出を無効にする | traverse.useQueues=true|false
コネクタが削除検出にキュー切り替えロジックを使用するかどうかを示します。 デフォルト値は 注: この構成パラメータを適用できるのは、 |
バッチポリシー
SDK は、次のアクションを実行できるバッチポリシーをサポートしています。
- バッチ リクエスト
- バッチキュー内のリクエスト数を指定する
- 同時実行バッチを管理する
- バッチ リクエストをフラッシュする
SDK はコネクタのリクエストをバッチ処理し、アップロード時のスループットを高速化します。リクエストのバッチをアップロードする SDK トリガーは、リクエスト数またはタイムアウトのいずれか早いほうで行われます。たとえば、バッチサイズに達しずにバッチ遅延時間が終了した場合、または遅延時間内にアイテム数がバッチサイズ数に達した場合は、一括アップロードがトリガーされます。
| 設定 | パラメータ |
|---|---|
| バッチ リクエスト | batch.batchSize
リクエストをバッチ処理する。デフォルト値は |
| バッチキュー内のリクエストの数 | batch.maxQueueLength=maxQueueLength
バッチキュー内の実行リクエストの最大数。デフォルト値は |
| バッチの同時実行 | batch.maxActiveBatches=maxActiveBatches
同時に実行可能なバッチの数。
デフォルト値は |
| バッチ リクエストを自動的にフラッシュする | batch.maxBatchDelaySeconds=maxBatchDelay
バッチ リクエストが自動的にフラッシュされるまでの待機時間（秒）。デフォルト値は |
| シャットダウン時にバッチ リクエストをフラッシュする | batch.flushOnShutdown=true|false
サービスのシャットダウン中にバッチ リクエストをフラッシュします。デフォルト値は |
例外ハンドラ
例外ハンドラのパラメータにより、走査で例外が発生した後の処理方法が決まります。
| 設定 | パラメータ |
|---|---|
| エラーが発生した場合のトラバーサー命令 | traverse.exceptionHandler=exceptions
例外がスローされた後のトラバーサーの処理方法。有効な値は次のとおりです。
|
| 例外間の待機時間 | abortExceptionHander.backoffMilliSeconds=backoff
検出されたハンドラ例外の間で待機するバックオフ時間（ミリ秒）。通常、リポジトリを移動するときに使用されます。デフォルト値は |