すべてのコネクタには、リポジトリの 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 を指定するには、次のパラメータ値をすべて設定します。
|
メタデータ構成パラメータ
アイテムのメタデータの一部は構成可能です。コネクタは、インデックス登録時に構成可能なメタデータ フィールドを設定できます。コネクタでフィールドが設定されていない場合は、構成ファイル内のパラメータを使用してフィールドが設定されます。
構成ファイルには、itemMetadata.title.field=movieTitle のように、.field 接尾辞で示される一連の名前付きメタデータ構成パラメータがあります。これらのパラメータの値がある場合は、それを使用してメタデータ フィールドを構成します。名前付きメタデータ パラメータの値がない場合は、.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。リポジトリ全体の URL を保持するように defaultValue を設定するだけで済みます。たとえば、担当者が CSV ファイルであり、すべてのアイテムに 1 つの URL しかない場合などです。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 Listing Connector テンプレートで次のパラメータを使用します。
| 設定 | パラメータ |
|---|---|
| リポジトリ走査 | 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
コネクタの複数のインスタンスを並行して実行し、互いに干渉することなく、共通のデータ リポジトリ（異なるデータ リポジトリか、共通のデータ リポジトリの別の部分にあるか）をインデックスに登録するには、コネクタの実行ごとに一意のコンテナ名タグを割り当てます。一意の名前タグを使用すると、コネクタ インスタンスが別のレコードを削除することはできません。 この名タグは、Full Traversal Connector の切り替えキュー ID に追加されます。 |
| 削除の検出を無効にする | traverse.useQueues=true|false
コネクタが削除検出にキュー切り替えロジックを使用するかどうかを示します。 デフォルト値は 注: この構成パラメータは、 |
バッチポリシー
SDK は、次のアクションを実行できるようにするバッチポリシーをサポートしています。
- バッチ リクエスト
- バッチキュー内のリクエスト数を指定する
- バッチの同時実行を管理する
- バッチ リクエストをフラッシュする
SDK はアップロードのスループットを高めるために、コネクタのリクエストをバッチ処理します。リクエストのバッチをアップロードする SDK トリガーは、リクエスト数またはタイムアウトのいずれか早い方になります。たとえば、バッチサイズに達しずにバッチ遅延時間が経過した場合や、遅延時間が経過する前にバッチサイズ アイテム数に達した場合は、一括アップロードがトリガーされます。
| 設定 | パラメータ |
|---|---|
| バッチ リクエスト | batch.batchSize
リクエストを一括処理します。デフォルト値は |
| バッチキュー内のリクエストの数 | batch.maxQueueLength=maxQueueLength
実行のバッチキュー内のリクエストの最大数。デフォルト値は |
| バッチの同時実行 | batch.maxActiveBatches=maxActiveBatches
同時に実行可能なバッチの数。デフォルト値は |
| 一括リクエストを自動的にフラッシュする | batch.maxBatchDelaySeconds=maxBatchDelay
一括リクエストが自動的にフラッシュされるまでの待機時間（秒）。デフォルト値は |
| シャットダウン時にバッチ リクエストをフラッシュする | batch.flushOnShutdown=true|false
サービスのシャットダウン中にバッチ リクエストをフラッシュします。デフォルト値は |
例外ハンドラ
例外ハンドラ パラメータは、例外が発生した後に走査が続行するかどうかを決定します。
| 設定 | パラメータ |
|---|---|
| エラーが発生した場合の Traverser 命令 | traverse.exceptionHandler=exceptions
例外がスローされた後の走査の進め方。有効な値は次のとおりです。
|
| 例外間の待機時間 | abortExceptionHander.backoffMilliSeconds=backoff
検出されたハンドラ例外間の待機時間（ミリ秒単位）。通常はリポジトリを走査する際に使用されます。デフォルト値は |