このガイドは、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 ファイルは表形式のデータを格納し、ファイルの各行が 1 つのデータレコードを表します。
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 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 ファイルの場所
- CSV の列の定義
- 一意 ID を定義する列
- 走査のオプション
- データアクセスを制限する ACL のオプション
コネクタが所定の CSV ファイルにアクセスして関連コンテンツをインデックス登録できるようにするために、まずコネクタの構成ファイルを作成する必要があります。
構成ファイルを作成するには:
- 適当なテキスト エディタを開き、構成ファイルに名前を付けます。
ファイルに key=value ペアを追加します（次のセクションの説明を参照）。 - 構成ファイルに名前を付けて保存します。
Google は構成ファイルの名前を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（映画 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 を指定して、出力先をファイルにすることができます。