このガイドは、Google Cloud Search の CSV（Comma-Separated Values: カンマ区切り値）コネクタの管理者、つまり CSV コネクタのダウンロード、構成、実行、モニタリングを担当するすべての人を対象としています。
このガイドでは、CSV コネクタのデプロイ関連の主要なタスクを実行する手順を説明しています:
- Google Cloud Search CSV コネクタ ソフトウェアをダウンロードする
- コネクタを特定の CSV データソースに合わせて構成する
- コネクタをデプロイして稼働させる
このドキュメントのコンセプトを理解するには、 Google Workspace、CSV ファイル、アクセス制御リスト（ACL）の基礎を学びます。
Google Cloud Search CSV コネクタの概要
Cloud Search CSV コネクタは、任意のカンマ区切り値（CSV）テキストに対応しています。 表示されます。CSV ファイルには表形式のデータが格納されます。ファイルの各行には、 記録します。
Google Cloud Search CSV コネクタは、CSV ファイルの各行を抽出し、Cloud Search の Indexing API を介して Cloud Search にインデックス登録します。インデックス登録が成功すると、CSV ファイルの各行を Cloud Search のクライアントまたは Cloud Search の Query API から検索できるようになります。CSV コネクタは、検索結果の内容に対するユーザーのアクセスを ACL で制御することにも対応しています。
Google Cloud Search CSV コネクタは、Linux または Windows にインストールできます。Google Cloud Search CSV コネクタをデプロイする前に、以下の要件が満たされていることをご確認ください。
- Google Cloud Search CSV コネクタが稼働するコンピュータに Java JRE 1.8 がインストールされている
組織間の関係を確立するために必要な Google Workspace の情報 Google Cloud Search とデータソース:
- Google Workspace の秘密鍵 （サービス アカウント ID を含む）
- Google Workspace データソース ID
通常、ドメインの Google Workspace 管理者は 認証情報を取得できます。
デプロイ手順
Google Cloud Search CSV コネクタをデプロイする手順は次のとおりです。
- Google Cloud Search CSV コネクタ ソフトウェアをインストールする
- CSV コネクタの構成を指定する
- Google Cloud Search データソースへのアクセスを構成する
- CSV ファイルへのアクセスを構成する
- インデックス登録する列名、一意のキー列、日時列を指定する
- クリック可能な検索結果の URL で使用する列を指定する
- メタデータ情報と列の形式を指定する
- データ トラバーサルをスケジュールする
- アクセス制御リスト（ACL）オプションを指定する
1. SDK をインストールする
ローカルの Maven リポジトリに SDK をインストールします。
GitHub から SDK リポジトリのクローンを作成します。
$ git clone https://github.com/google-cloudsearch/connector-sdk.git $ cd connector-sdk/csv
希望するバージョンの SDK をチェックアウトします。
$ git checkout tags/v1-0.0.3コネクタをビルドします。
$ mvn packageコネクタ zip ファイルをローカルのインストール ディレクトリにコピーします。
$ cp target/google-cloudsearch-csv-connector-v1-0.0.3.zip installation-dir $ cd installation-dir $ unzip google-cloudsearch-csv-connector-v1-0.0.3.zip $ cd google-cloudsearch-csv-connector-v1-0.0.3
2. CSV コネクタの構成を指定する
コネクタ管理者は、CSV コネクタの動作と コネクタの構成ファイルでパラメータを定義する属性。 構成可能なパラメータには次のものがあります。
- データソースへのアクセス
- CSV ファイルの場所
- CSV の列の定義
- 一意 ID を定義する列
- 走査のオプション
- データアクセスを制限する ACL のオプション
コネクタが所定の CSV ファイルにアクセスして関連コンテンツをインデックス登録できるようにするために、まずコネクタの構成ファイルを作成する必要があります。
構成ファイルを作成するには:
- 適当なテキスト エディタを開き、構成ファイルに名前を付けます。
ファイルの内容に key=value ペアを追加します。 できます。 - 構成ファイルに名前を付けて保存します。
構成ファイルの名前は、connector-config.propertiesであるため、追加のコマンドライン パラメータはありません。 必要ありません
コマンドラインで構成ファイルのパスを指定できるので、標準のファイルの場所は必要ありません。ただし、構成ファイルを常にコネクタと同じディレクトリに置いて、コネクタを簡単に追跡して動かせるようにしてください。
コマンドラインで構成ファイルのパスを指定すれば、コネクタは指定の構成ファイルを確実に認識します。それ以外の場合、コネクタは
connector-config.properties を、ローカル ディレクトリ
ファイル名を変更します。Google Cloud コンソールでの構成パスの指定については、
Cloud Search CSV コネクタを実行するをご覧ください。
3. Google Cloud Search データソースへのアクセスを構成する
構成ファイルでは、Cloud Search データソースにアクセスするために必要なパラメータを最初に指定する必要があります。次の表をご覧ください。Cloud Search へのコネクタのアクセスを構成するには、通常、データソースの ID、サービス アカウントの ID、サービス アカウントの秘密鍵ファイルへのパスが必要です。データソースをセットアップする手順は、サードパーティのデータソースを管理するを参照してください。
| 設定 | パラメータ |
| データソースの ID | api.sourceId=1234567890abcdef
必須。Google Workspace 管理者がセットアップした Google Cloud Search ソース ID（サードパーティのデータソースを管理するを参照）。 |
| サービス アカウントの秘密鍵ファイルへのパス | api.serviceAccountPrivateKeyFile=./PrivateKey.json
必須。Google Cloud Search CSV コネクタへのアクセスに必要な Google Cloud Search サービス アカウントの鍵ファイル。 |
| ID ソースの ID | api.identitySourceId=x0987654321
外部のユーザーとグループを使用する場合は必須。Google Workspace 管理者が設定した Google Cloud Search ID ソースの ID。 |
4. CSV ファイルのパラメータを構成する
コネクタが CSV ファイルを走査してインデックス登録するデータを抽出できるようにするために、ファイルのパスを指定してください。ファイル形式とファイル エンコードの種類を指定することもできます。 次のパラメータを追加して、構成ファイルで CSV ファイルのプロパティを指定します。
| 設定 | パラメータ |
| CSV ファイルのパス | csv.filePath=./movie_content.csv
必須。アクセスしてインデックス登録する内容を抽出する CSV ファイルへのパス。 |
| ファイル形式 | csv.format=DEFAULT
ファイルの形式。使用できる値は、Apache Commons CSV CSVFormat クラスのものです。 形式の値には、 |
| ファイル形式の修飾子 | csv.format.withMethod=value
Cloud Search がファイルを処理する方法に対する変更。使用できるメソッドは、Apache Commons CSV CSVFormat クラスのものであり、単一の文字、文字列、ブール値を取るものです。 たとえば、区切り文字としてセミコロンを指定するには、 |
| ファイルのエンコード タイプ | csv.fileEncoding=UTF-8
Cloud Search がファイルを読み取るときに使用する Java 文字セット。指定しない場合 Cloud Search では、プラットフォームのデフォルトの文字セットが使用されます。 |
5. インデックス登録する列の名前と一意キーの列を指定する
コネクタが CSV ファイルにアクセスしてインデックス登録できるようにするために、構成ファイル内で列の定義に関する情報を指定してください。もし 構成ファイルに列名を指定するパラメータが含まれていません。 インデックス付けと一意のキー列に対するサポートは、デフォルト値が使用されます。
| 設定 | パラメータ |
| インデックス登録する列 | csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...
CSV ファイルからインデックス登録する列の名前。 |
| 一意キーの列 | csv.uniqueKeyColumns=movieId
各レコードの一意の ID の生成に使用される値を含む CSV 列。指定しない場合、CSV レコードのハッシュを一意のキーとして使用します。デフォルト値はレコードのハッシュコードです。 |
6. クリック可能な検索結果の URL に使用する列を指定する
Google Cloud Search による検索ではクリック可能な URL（それぞれの結果を表示する）から成る検索結果ページが返されます。この機能を有効化するには、次の表に示すパラメータを構成ファイルに追加してください。
| 設定 | パラメータ |
| 検索結果の URL 書式 | url.format=https://mymoviesite.com/movies/{0}
必須。CSV コンテンツの表示 URL の書式。 |
| 検索結果の URL パラメータ。 | url.columns=movieId
必須。レコードの表示 URL の生成に用いられる値を含む CSV ファイルの列の名前。 |
| 検索結果から除外する URL パラメータ | url.columnsToEscape=movieId
省略可。表示 URL の生成から除外する URL の値を含む CSV ファイルの列の名前。 |
7. メタデータ情報、列書式、検索品質を指定する
構成ファイルにパラメータを追加して以下の情報を指定できます。
メタデータ構成パラメータ
メタデータ構成パラメータは、アイテム メタデータの入力に使用される CSV ファイルの列を設定するものです。構成ファイルにこれらのパラメータが含まれていない場合は、デフォルト値が用いられます。次の表に、これらのパラメータを示します。
| 設定 | パラメータ |
| タイトル | itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind
ドキュメント タイトルに対応する値を含むメタデータ属性。デフォルト値は空文字列です。 |
| URL | itemMetadata.sourceRepositoryUrl.field=url
itemMetadata.sourceRepositoryUrl.defaultValue=https://www.imdb.com/title/tt0031381/ 検索結果のドキュメント URL の値を含むメタデータ属性。 |
| 作成タイムスタンプ | itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17
ドキュメント作成タイムスタンプの値を含むメタデータ属性。 |
| 最終更新時刻 | itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17
ドキュメントの最終変更タイムスタンプの値を含むメタデータ属性。 |
| ドキュメント言語 | itemMetadata.contentLanguage.field=languageCode
itemMetadata.contentLanguage.defaultValue=en-US
インデックス登録するドキュメントのコンテンツ言語。 |
| スキーマ オブジェクト タイプ | itemMetadata.objectType.field=typeitemMetadata.objectType.defaultValue=movie
コネクタで使用されるオブジェクト タイプ（ スキーマ。 このプロパティを指定しないと、コネクタは構造化データをインデックス登録しません。 |
日時書式
日時書式は、期待される書式をメタデータ属性で指定するものです。構成ファイルにこのパラメータが含まれていないと、デフォルト値が用いられます。次の表に、このパラメータを示します。
| 設定 | パラメータ |
| 追加の日時書式 | structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
追加の java.time.format.DateTimeFormatter パターンのセミコロンで区切られたリスト。これらのパターンは、メタデータまたはスキーマ内の日付や日時の項目の文字列値を解析するときに使用されます。デフォルト値は空のリストですが、RFC 3339 と RFC 1123 の形式は常にサポートされています。 |
列書式
列書式は、検索可能なコンテンツの一部と考えられる、列に関する情報を指定するものです。構成ファイルにこれらのパラメータが含まれていない場合は、デフォルト値が用いられます。次の表に、これらのパラメータを示します。
| 設定 | パラメータ |
| ヘッダーをスキップ | csv.skipHeaderRecord=true
ブール値。CSV ファイルのヘッダー レコード（最初の行）を無視します。 |
| 多値列 | csv.multiValueColumns=genre,actors
多値に対応する、CSV ファイルの列の名前。デフォルト値は空文字列です。 |
| 多値列の区切り文字 | csv.multiValue.genre=;
多値列の区切り文字。デフォルトの区切り文字はカンマです。 |
検索品質
Cloud Search CSV コネクタを使用すると、データ フィールドの HTML 書式設定を自動的に行うことができます。 コネクタは、コネクタ実行の開始時にデータ フィールドを定義します。 アップロードする前にコンテンツ テンプレートを使用して各データレコードをフォーマットする おすすめします
コンテンツ テンプレートでは、検索における各フィールド値の重要度を定義します。 title フィールドは必須で、最も高い優先度として定義されます。コンテンツのその他のフィールドについては、検索品質の重要度を高、中、低の区分で示すことができます。特定の区分に属さないフィールドの優先度はデフォルトで低とされます。次の表に、これらのパラメータを示します。
| 設定 | パラメータ |
| コンテンツ タイトル | contentTemplate.csv.title=movieTitle
コンテンツ タイトルは検索品質が最も高い項目です。 |
| 検索品質: 高 | contentTemplate.csv.quality.high=actors
検索品質の値が高いコンテンツ フィールド。デフォルトは空の文字列です。 |
| 検索品質: 低 | contentTemplate.csv.quality.low=genre
検索品質の値が低いコンテンツ フィールド。デフォルトは空の文字列です。 |
| 検索品質: 中 | contentTemplate.csv.quality.medium=description
コンテンツ フィールドに検索品質の値が「中」に設定されている。デフォルトは空の文字列です。 |
| 品質区分: 未指定 | contentTemplate.csv.unmappedColumnsMode=IGNORE
コネクタが未指定のコンテンツ フィールドを処理する方法。指定できる値は次のとおりです。
|
8. データ走査をスケジュールする
コネクタがデータソース（この場合は CSV ファイル）からコンテンツを発見するプロセスを走査と呼びます。CSV コネクタは、稼働すると、CSV ファイルのすべての行を走査し、Indexing API を介して各行を Cloud Search にインデックス登録します。
フル走査ではファイルのすべての列がインデックス登録されます。増分走査では直前の増分走査以降に追加または変更された列のみがインデックス登録されます。CSV コネクタはフル走査のみを実行し、増分走査は実行しません。
スケジュール関連のパラメータはコネクタの走査実行間隔（頻度）を決定します。構成ファイルでスケジュール関連のパラメータを指定しないと、デフォルト値が用いられます。次の表に、これらのパラメータを示します。
| 設定 | パラメータ |
| 一定時間経過後にフル走査 | schedule.traversalIntervalSecs=7200
コネクタは、指定された時間が経過するとフル走査を実行します。走査から次の走査までの時間間隔を秒単位で指定します。デフォルト値は 86,400（1 日の秒数）です。 |
| 起動時にフル走査 | schedule.performTraversalOnStart=false
コネクタは、最初の間隔が期限切れになるのを待たずに、コネクタの起動時にフル走査を実行します。デフォルト値は true です。 |
9. アクセス制御リスト（ACL）のオプションを指定する
Google Cloud Search CSV コネクタは ACL によるアクセス許可をサポートしており、それで検索結果内の CSV ファイルのコンテンツへのアクセスを制御します。インデックス登録されたレコードへのユーザー アクセスを保護するために複数の ACL オプションを使用できます。
お客様のリポジトリにある個々の ACL 情報が各ドキュメントと関連付けられている場合は、Cloud Search 内のドキュメント アクセスを制御するために ACL 情報をすべてアップロードしてください。リポジトリが ACL 情報を提供していないか提供が一部に限られる場合は、以下のパラメータ（SDK からコネクタに提供されるパラメータ）でデフォルトの ACL 情報を提供すればよいでしょう。
コネクタは、構成ファイル内で有効化されるデフォルトの ACL に依存します。宛先
デフォルトの ACL を有効にして、defaultAcl.mode を none 以外のモードに設定し、
defaultAcl.* で設定する
| 設定 | パラメータ |
| ACL モード | defaultAcl.mode=fallback
必須。CSV コネクタはデフォルトの ACL 機能に依存します。コネクタはフォールバック モードのみをサポートしています。 |
| デフォルトの ACL 名 | defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1
省略可。デフォルトの ACL をセットアップするためにコネクタが使用している仮想コンテナの名前をオーバーライドできます。デフォルト値は "DEFAULT_ACL_VIRTUAL_CONTAINER" です。複数のコネクタが同じデータソース内のコンテンツをインデックスに登録している場合は、この値をオーバーライドできます。 |
| デフォルトのパブリック ACL | defaultAcl.public=true
リポジトリ全体に使用されるデフォルトの ACL はパブリック ドメイン アクセスに設定されています。デフォルト値は false です。 |
| 共通の ACL グループ リーダー | defaultAcl.readers.groups=google:group1, group2 |
| 共通の ACL リーダー | defaultAcl.readers.users=user1, user2, google:user3 |
| 共通の ACL 拒否グループ リーダー | defaultAcl.denied.groups=group3 |
| 共通の ACL 拒否リーダー | defaultAcl.denied.users=user4, user5 |
| ドメイン全体のアクセス | インデックスに登録されたすべてのレコードをドメイン内のすべてのユーザーがアクセスできるように指定するには、次の両方のオプションに値を設定します。
|
| 共通の拒否 ACL | データ リポジトリのレコードごとに 1 つの ACL を指定するには、次のパラメータ値をすべて設定します。
|
スキーマ定義
Cloud Search では、構造化コンテンツと非構造化コンテンツのインデックス登録と提供が可能です。 データに対する構造化データのクエリをサポートするには、以下を行う必要があります。 データソースのスキーマを設定します。
CSV コネクタが定義されると、定義されたスキーマを参照してインデックス登録リクエストを作成できます。 説明のために、次の内容を含む CSV ファイルを例に 考えてみましょう ご覧ください。
入力 CSV ファイルの内容が次のとおりだと仮定します。
- movieId（映画 ID）
- movieTitle（映画タイトル）
- description（説明）
- year（年）
- releaseDate（リリース日）
- actors（俳優） - カンマ区切りリストで複数を指定
- genre（ジャンル） - 多値
- ratings（評価）
上記のデータ構造に基づいてデータソースのスキーマを定義すれば、そのデータを CSV ファイルからインデックス登録できます。
{
"objectDefinitions": [
{
"name": "movie",
"propertyDefinitions": [
{
"name": "actors",
"isReturnable": true,
"isRepeatable": true,
"isFacetable": true,
"textPropertyOptions": {
"operatorOptions": {
"operatorName": "actor"
}
}
},
{
"name": "releaseDate",
"isReturnable": true,
"isRepeatable": false,
"isFacetable": false,
"datePropertyOptions": {
"operatorOptions": {
"operatorName": "released",
"lessThanOperatorName": "releasedbefore",
"greaterThanOperatorName": "releasedafter"
}
}
},
{
"name": "movieTitle",
"isReturnable": true,
"isRepeatable": false,
"isFacetable": false,
"textPropertyOptions": {
"retrievalImportance": {
"importance": "HIGHEST"
},
"operatorOptions": {
"operatorName": "title"
}
}
},
{
"name": "genre",
"isReturnable": true,
"isRepeatable": true,
"isFacetable": true,
"enumPropertyOptions": {
"operatorOptions": {
"operatorName": "genre"
},
"possibleValues": [
{
"stringValue": "Action"
},
{
"stringValue": "Documentary"
},
{
"stringValue": "Drama"
},
{
"stringValue": "Crime"
},
{
"stringValue": "Sci-fi"
}
]
}
},
{
"name": "userRating",
"isReturnable": true,
"isRepeatable": false,
"isFacetable": true,
"integerPropertyOptions": {
"orderedRanking": "ASCENDING",
"maximumValue": "10",
"operatorOptions": {
"operatorName": "score",
"lessThanOperatorName": "scorebelow",
"greaterThanOperatorName": "scoreabove"
}
}
}
]
}
]
}
例: 構成ファイル
次の構成ファイルの例は、key=value パラメータのペアを示しています。
サンプルコネクタの動作を定義します。
# data source access
api.sourceId=1234567890abcd
api.serviceAccountPrivateKeyFile=./PrivateKey.json
# CSV data structure
csv.filePath=./movie_content.csv
csv.csvColumns=movieId,movieTitle,description,releaseYear,genre,actors,ratings,releaseDate
csv.skipHeaderRecord=true
url.format=https://mymoviesite.com/movies/{0}
url.columns=movieId
csv.datetimeFormat.releaseDate=yyyy-mm-dd
csv.multiValueColumns=genre,actors
csv.multiValue.genre=;
contentTemplate.csv.title=movieTitle
# metadata structured data and content
itemMetadata.title.field=movieTitle
itemMetadata.createTime.field=releaseDate
itemMetadata.contentLanguage.defaultValue=en-US
itemMetadata.objectType.defaultValue=movie
contentTemplate.csv.quality.medium=description
contentTemplate.csv.unmappedColumnsMode=IGNORE
#ACLs
defaultAcl.mode=fallback
defaultAcl.public=true
各パラメータの詳細は、構成パラメータのリファレンスを参照してください。
Cloud Search CSV コネクタを稼働させる
コマンドラインからコネクタを実行するには、次のコマンドを入力します。
$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config
デフォルトでは、コネクタのログは標準出力に書き出されます。ファイルにログを記録できます。
logging.properties を指定します。