このガイドは、コネクタのダウンロード、構成、実行、モニタリングを担当する Google Cloud Search CSV（Comma-Separated Values: カンマ区切り値）コネクタの管理者を対象としています。
このガイドでは、次の主要なタスクの手順について説明します。
- Cloud Search CSV コネクタ ソフトウェアをダウンロードします。
- 特定の CSV データソース用にコネクタを構成します。
- コネクタをデプロイして実行します。
このドキュメントで説明しているコンセプトを理解するには、Google Workspace、CSV ファイル、アクセス制御リスト（ACL）に関する基本的な知識が必要です。
Cloud Search CSV コネクタの概要
Cloud Search の CSV コネクタは、任意の CSV（カンマ区切り値）テキスト ファイルを受け取って処理を行います。CSV ファイルは表形式のデータを格納し、各行が 1 つのデータレコードを表します。
コネクタは、CSV ファイルから行を抽出し、Indexing API を使用して Cloud Search にインデックス登録します。インデックス登録が完了すると、Cloud Search クライアントまたは Query API を介して行を検索できるようになります。コネクタは、コンテンツに対するユーザー アクセスを制御する ACL もサポートしています。
コネクタは Linux または Windows にインストールできます。デプロイする前に、次のコンポーネントがそろっていることを確認してください。
- コネクタを実行するコンピュータに Java JRE 1.8 がインストールされている。
- 接続を確立するための Google Workspace 情報:
- Google Workspace の秘密鍵（サービス アカウント ID を含む）。
- Google Workspace データソース ID。
通常、これらの認証情報はドメインの Google Workspace 管理者から提供されます。
デプロイ手順を実行する
Cloud Search CSV コネクタをデプロイする手順は次のとおりです。
- コネクタ ソフトウェアをインストールする
- コネクタの構成を指定する
- 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
選択したバージョンをチェックアウトします。
$ git checkout tags/v1-0.0.3
コネクタをビルドします。
$ mvn package
コネクタを抽出してインストールします。
$ 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 ファイルの場所と定義。
- 一意 ID 列。
- 走査と ACL のオプション。
構成ファイルを作成するには:
- テキスト エディタを開き、ファイルに
connector-config.propertiesという名前を付けます。 - 構成パラメータを
key=valueペアとして追加します。各ペアは新しい行に記述します。構成ファイルの例については、構成ファイルの例をご覧ください。
追跡を簡素化するため、構成ファイルをコネクタと同じディレクトリに配置します。コマンドラインでファイルのパスを指定すれば、コネクタは指定のファイルを確実に認識します。指定しなかった場合、コネクタはローカル ディレクトリ内の connector-config.properties をデフォルトで使用します。コネクタを実行するをご覧ください。
3. Cloud Search データソースへのアクセスを構成する
構成ファイルでは、Cloud Search データソースにアクセスするためのパラメータを指定する必要があります。データソース ID、サービス アカウント ID、サービス アカウントの秘密鍵ファイルへのパスが必要です。
| 設定 | パラメータ |
| データソース ID | api.sourceId=1234567890abcdef
必須。Google Workspace 管理者がセットアップした、Cloud Search ソースの ID。 |
| サービス アカウントの秘密鍵へのパス | api.serviceAccountPrivateKeyFile=./PrivateKey.json
必須。コネクタへのアクセスに必要なサービス アカウント キー ファイル。 |
| ID ソースの ID | api.identitySourceId=x0987654321
外部のユーザーとグループを使用する場合は必須。Google Workspace 管理者が設定した ID ソースの ID。 |
4. CSV ファイルのパラメータを構成する
ファイルのパス、形式、エンコードを特定します。
| 設定 | パラメータ |
| CSV ファイルへのパス | csv.filePath=./movie_content.csv
必須。インデックス登録するファイルへのパス。 |
| ファイル形式 | csv.format=DEFAULT
ファイルの形式。使用できる値は、Apache Commons CSV CSVFormat クラスのものです。 形式の値には、 |
| ファイル形式の修飾子 | csv.format.withMethod=value
Cloud Search がファイルを処理する方法に対する変更。使用できるメソッドは、Apache Commons CSV CSVFormat クラスのものであり、単一の文字、文字列、ブール値を取るものです。 たとえば、区切り文字としてセミコロンを指定するには、 |
| ファイルのエンコード タイプ | csv.fileEncoding=UTF-8
使用する Java 文字セット。デフォルトはプラットフォームの文字セットです。 |
5. インデックス登録する列の名前と一意キーの列を指定する
構成ファイルに列情報を指定します。
| 設定 | パラメータ |
| インデックス登録する列 | csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...
CSV ファイルからインデックス登録する列の名前。デフォルトでは、CSV の最初の行がヘッダーとして使用されます。 |
| 一意キーの列 | csv.uniqueKeyColumns=movieId
一意の ID の生成に使用される列。デフォルトはレコードのハッシュコードです。 |
6. クリック可能な検索結果の URL に使用する列を指定する
検索結果のクリック可能な URL を有効にします。
| 設定 | パラメータ |
| 検索結果の URL 書式 | url.format=https://mymoviesite.com/movies/{0}
必須。表示 URL の作成に使用される形式。 |
| URL パラメータ | url.columns=movieId
必須。レコードの表示 URL の生成に用いられる値を含む CSV ファイルの列の名前。 |
| 検索結果から除外する URL パラメータ | url.columnsToEscape=movieId
省略可。表示 URL の生成から除外する URL の値を含む CSV ファイルの列の名前。 |
7. メタデータ、列書式、検索品質を指定する
構成ファイルにパラメータを追加して以下の情報を指定できます。
メタデータ構成パラメータ
これらのパラメータは、アイテム メタデータを設定するための列を記述します。
| 設定 | パラメータ |
| タイトル | 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 ファイルの列を解析する方法を指定します。
| 設定 | パラメータ |
| ヘッダーをスキップ | csv.skipHeaderRecord=true
最初の行は無視してください。デフォルトは false です。 |
| 多値列 | csv.multiValueColumns=genre,actors
複数の値を持つ列名。 |
| 多値列の区切り文字 | csv.multiValue.genre=;
多値列の区切り文字。デフォルトの区切り文字はカンマです。 |
検索品質
コネクタは、コンテンツ テンプレートを使用してレコードの書式を設定します。タイトル フィールドの優先度が最も高くなります。他のフィールドに優先度（高、中、低）を割り当てることができます。
| 設定 | パラメータ |
| コンテンツのタイトル |
contentTemplate.csv.title=movieTitle
コンテンツ タイトルは、検索品質が「最高」に区分されたフィールドです。 |
| コンテンツの項目の検索品質を「高」に区分します。 |
contentTemplate.csv.quality.high=actors
コンテンツのフィールドの検索品質を「高」に区分します。デフォルトは空の文字列です。 |
| 検索品質: 低 |
contentTemplate.csv.quality.low=genre
コンテンツのフィールドの検索品質を「低」に区分します。デフォルトは空の文字列です。 |
| 検索品質: 中 |
contentTemplate.csv.quality.medium=description
コンテンツのフィールドの検索品質を「中」に区分します。デフォルトは空の文字列です。 |
| 品質区分: 未指定 |
contentTemplate.csv.unmappedColumnsMode=IGNORE
検索品質が未指定のフィールドをどう扱うかを指定します。指定できる値は次のとおりです。
デフォルト値は APPEND です。 |
8. データ走査をスケジュールする
走査はコンテンツを発見するプロセスです。コネクタは CSV 行を走査し、Indexing API を使用してインデックス登録します。CSV コネクタはフル走査のみを実行します。
| 設定 | パラメータ |
| 走査間隔 | schedule.traversalIntervalSecs=7200
完全走査の間隔（秒単位）。デフォルトは 86400（1 日）です。 |
| 起動時の走査 | schedule.performTraversalOnStart=false
最初のフル走査は、待機しないでコネクタの起動時に実行します。デフォルトは |
9. ACL オプションを指定する
コネクタは ACL を使用してアクセスを制御します。リポジトリで ACL が提供されている場合は、アップロードします。それ以外の場合は、デフォルトの ACL を構成します。defaultAcl.mode を none 以外の値に設定します。
| 設定 | パラメータ |
| ACL モード | defaultAcl.mode=fallback
必須。コネクタはフォールバック モードのみをサポートしています。 |
| デフォルトの ACL 名 | defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1
省略可。デフォルトの ACL に使用されるコネクタの仮想コンテナ名をオーバーライドします。デフォルト値は |
| デフォルトのパブリック ACL | defaultAcl.public=true
リポジトリ全体をパブリック ドメイン アクセスに設定します。デフォルトは 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 | 各レコードに共通の ACL を定義するには、次のパラメータを設定します。
ユーザーとグループは、「 デフォルトのユーザーまたはグループは空文字列です。
|
スキーマ定義
構造化データクエリをサポートするには、データソースのスキーマを設定します。
たとえば、映画に関する次の情報を含む CSV ファイルがあるとします。
- movieId
- movieTitle（映画タイトル）
- description（説明）
- year（年）
- releaseDate（リリース日）
- actors（俳優） - カンマ区切りリストで複数を指定
- genre（ジャンル） - 多値
- 評価
この構造に基づいて、データソースに次のスキーマを定義できます。
{
"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
コネクタを実行する
コマンドラインからコネクタを実行するには:
$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config
デフォルトでは、コネクタのログは標準出力に書き出されます。logging.properties を指定して、出力先をファイルにすることができます。