このガイドは、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 にインデックス登録します。正常にインデックス登録されると、Cloud Search のクライアントまたは Cloud Search の Query API で CSV ファイルの個々の行を検索できます。CSV コネクタでは、ACL を使用して検索結果のコンテンツへのユーザーのアクセスを制御することもできます。
Google Cloud Search CSV コネクタは、Linux または Windows にインストールできます。Google Cloud Search CSV コネクタをデプロイする前に、以下の要件が満たされていることをご確認ください。
- Google Cloud Search CSV コネクタが稼働するコンピュータに Java JRE 1.8 がインストールされている
Google Cloud Search とデータソースの関係を確立するために必要な Google Workspace の情報:
- 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 をデフォルトのファイル名として使用します。コマンドラインで構成パスを指定する方法については、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 形式に設定できます。コネクタは、コネクタ実行の開始時にデータ フィールドを定義し、コンテンツ テンプレートを使用して各データレコードをフォーマットしてから、Cloud Search にアップロードします。
コンテンツ テンプレートは、検索における各フィールド値の重要度を定義します。タイトル フィールドは必須で、最も高い優先度として定義されます。コンテンツのその他のフィールドについては、検索品質の重要度を高、中、低の区分で示すことができます。特定の区分に属さないフィールドの優先度はデフォルトで低とされます。次の表に、これらのパラメータを示します。
| 設定 | パラメータ |
| コンテンツ タイトル | 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
- 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 を指定すると、ファイルにログを記録できます。