CSV コネクタをデプロイする

このガイドは、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 コネクタをデプロイする手順は次のとおりです。

1. Google Cloud Search CSV コネクタ ソフトウェアをインストールする
2. CSV コネクタの構成を指定する
3. Google Cloud Search データソースへのアクセスを構成する
4. CSV ファイル アクセスを構成する
5. インデックス登録する列の名前、一意キーの列、日時の列を指定する
6. クリック可能な検索結果の URL に使用する列を指定する
7. メタデータ情報、列書式を指定する
8. データ走査をスケジュールする
9. アクセス制御リスト（ACL）のオプションを指定する

1. SDK をインストールする

ローカルの Maven リポジトリに SDK をインストールします。

1. GitHub から SDK リポジトリのクローンを作成します。

   $ git clone https://github.com/google-cloudsearch/connector-sdk.git
   $ cd connector-sdk/csv

2. 希望するバージョンの SDK をチェックアウトします。

   $ git checkout tags/v1-0.0.3

3. コネクタをビルドします。

   $ mvn package

4. コネクタ 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 ファイルにアクセスして関連コンテンツをインデックス登録できるようにするために、まずコネクタの構成ファイルを作成する必要があります。

構成ファイルを作成するには:

1. 適当なテキスト エディタを開き、構成ファイルに名前を付けます。
   ファイルに key=value ペアを追加します（次のセクションの説明を参照）。
2. 構成ファイルに名前を付けて保存します。
   Google は構成ファイルの名前を connector-config.properties とするよう推奨しています。これで、追加のコマンドライン パラメータを指定しなくてもコネクタが実行されます。

コマンドラインで構成ファイルのパスを指定できるので、標準のファイルの場所は必要ありません。ただし、構成ファイルを常にコネクタと同じディレクトリに置いて、コネクタを簡単に追跡して動かせるようにしてください。

コマンドラインで構成ファイルのパスを指定すれば、コネクタは指定の構成ファイルを確実に認識します。指定しなかった場合、コネクタはローカル ディレクトリ内の connector-config.properties をデフォルトのファイル名として使用します。コマンドラインで構成パスを指定する方法については、Cloud Search CSV コネクタを稼働させるをご覧ください。

3. Google Cloud Search データソースへのアクセスを構成する

構成ファイルでは、Cloud Search データソースにアクセスするために必要なパラメータを最初に指定する必要があります。次の表をご覧ください。Cloud Search へのコネクタのアクセスを構成するには、通常、データソースの ID、サービス アカウントの ID、サービス アカウントの秘密鍵ファイルへのパスが必要です。データソースをセットアップする手順は、サードパーティのデータソースを管理するを参照してください。

4. CSV ファイルのパラメータを構成する

コネクタが CSV ファイルを走査してインデックス登録するデータを抽出できるようにするために、ファイルのパスを指定してください。また、ファイル形式とファイル エンコードのタイプを指定することもできます。以下のパラメータを追加して、構成ファイルで CSV ファイルのプロパティを指定します。

5. インデックス登録する列の名前と一意キーの列を指定する

コネクタが CSV ファイルにアクセスしてインデックス登録できるようにするために、構成ファイル内で列の定義に関する情報を指定してください。インデックス登録する列の名前と一意キーの列を構成ファイル内のパラメータで指定しなかった場合は、デフォルト値が使用されます。

6. クリック可能な検索結果の URL に使用する列を指定する

Google Cloud Search による検索ではクリック可能な URL（それぞれの結果を表示する）から成る検索結果ページが返されます。この機能を有効化するには、次の表に示すパラメータを構成ファイルに追加してください。

7. メタデータ情報、列書式、検索品質を指定する

構成ファイルにパラメータを追加して以下の情報を指定できます。

• メタデータ構成パラメータ
• 列の形式
• 検索の精度

メタデータ構成パラメータ

メタデータ構成パラメータは、アイテム メタデータの入力に使用される CSV ファイルの列を設定するものです。構成ファイルにこれらのパラメータが含まれていない場合は、デフォルト値が用いられます。次の表に、これらのパラメータを示します。

日時書式

日時書式は、期待される書式をメタデータ属性で指定するものです。構成ファイルにこのパラメータが含まれていないと、デフォルト値が用いられます。次の表に、このパラメータを示します。

列書式

列書式は、検索可能なコンテンツの一部と考えられる、列に関する情報を指定するものです。構成ファイルにこれらのパラメータが含まれていない場合は、デフォルト値が用いられます。次の表に、これらのパラメータを示します。

検索品質

Cloud Search CSV コネクタはデータ項目の HTML 書式設定を自動化できます。コネクタはコネクタ実行の最初の段階でデータ フィールドを定義し、コンテンツ テンプレートに基づいて各データレコードを書式設定してから Cloud Search にアップロードします。

コンテンツ テンプレートは、検索時の各項目の値の重要度を定義します。タイトル フィールドは必須のフィールドであり、最高の優先度を持つものとされます。コンテンツのその他のフィールドについては、検索品質の重要度を高、中、低の区分で示すことができます。特定の区分に属さないフィールドの優先度はデフォルトで低とされます。次の表に、これらのパラメータを示します。

8. データ走査をスケジュールする

コネクタがデータソース（この場合は CSV ファイル）からコンテンツを発見するプロセスを走査と呼びます。CSV コネクタは、稼働すると、CSV ファイルのすべての行を走査し、Indexing API を介して各行を Cloud Search にインデックス登録します。

フル走査ではファイルのすべての列がインデックス登録されます。増分走査では直前の増分走査以降に追加または変更された列のみがインデックス登録されます。CSV コネクタはフル走査のみを実行し、増分走査は実行しません。

スケジュール関連のパラメータはコネクタの走査実行間隔（頻度）を決定します。構成ファイルでスケジュール関連のパラメータを指定しないと、デフォルト値が用いられます。次の表に、これらのパラメータを示します。

9. アクセス制御リスト（ACL）のオプションを指定する

Google Cloud Search CSV コネクタは ACL によるアクセス許可をサポートしており、それで検索結果内の CSV ファイルのコンテンツへのアクセスを制御します。インデックス登録されたレコードへのユーザー アクセスを保護するために複数の ACL オプションを使用できます。

お客様のリポジトリにある個々の ACL 情報が各ドキュメントと関連付けられている場合は、Cloud Search 内のドキュメント アクセスを制御するために ACL 情報をすべてアップロードしてください。リポジトリが ACL 情報を提供していないか提供が一部に限られる場合は、以下のパラメータ（SDK からコネクタに提供されるパラメータ）でデフォルトの ACL 情報を提供すればよいでしょう。

コネクタは、構成ファイル内で有効化されるデフォルトの ACL に依存します。デフォルトの ACL を有効にするには、defaultAcl.mode を none 以外のモードに設定し、defaultAcl.* で構成します。

スキーマ定義

Cloud Search は、構造化データと非構造化データの両方のコンテンツのインデックス登録と提供を可能にします。お客様のデータで構造化データクエリをサポートするには、データソースに対してスキーマをセットアップする必要があります。

セットアップ後、CSV コネクタは定義済みのスキーマを参照してインデックス登録リクエストを作成できます。具体的な例として、映画に関する情報を含む CSV ファイルを考えてみましょう。

入力 CSV ファイルの内容が次のとおりだと仮定します。

1. movieId（映画 ID）
2. movieTitle（映画タイトル）
3. description（説明）
4. year（年）
5. releaseDate（リリース日）
6. actors（俳優） - カンマ区切りリストで複数を指定
7. genre（ジャンル） - 多値
8. 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 を指定して、出力先をファイルにすることができます。