データベース コネクタのデプロイ

警告: Cloud Search リファレンス コネクタは、独自のコネクタの作成に使用できるサンプルコードとして「現状のまま」提供されています。このサンプルコードは、概念実証や本番環境で使用する前に、かなりのカスタマイズとテストを行う必要があります。本番環境で使用する場合は、Cloud Search パートナーにサポートを受けることを強くおすすめします。適切な Cloud Search パートナーを探すには、Google アカウント マネージャーにお問い合わせください。

Google Cloud Search データベース コネクタを使用することで、組織のデータベースからデータを検出してインデックスに登録するように Google Cloud Search を設定できます。

重要な考慮事項

Cloud Search データベース コネクタは、インターネットとデータベースの両方にアクセスできる限り、Java アプリを実行できるほぼすべての環境にインストールして実行できます。

システム要件

システム要件
オペレーティング システム Windows または Linux
SQL データベース JDBC 4.0 以降に準拠したドライバを使用する任意の SQL データベース（以下を含む）。
  • MS SQL Server（2008、2012、2014、2016）
  • Oracle（11g、12c）
  • Google Cloud SQL
  • MySQL
ソフトウェア コネクタがデータベースへのアクセスに使用する JDBC ドライバ（別途ダウンロードしてインストール）

コネクタをデプロイする

次の手順では、コネクタをインストールして、指定されたデータベースをインデックスに登録し、結果を Cloud Search ユーザーに返すように構成する方法について説明します。

前提条件

Cloud Search データベース コネクタをデプロイする前に、次の情報を収集します。

ステップ 1: データベース コネクタ ソフトウェアをダウンロードしてビルドする

  1. GitHub からコネクタ リポジトリのクローンを作成します。 
    $ git clone https://github.com/google-cloudsearch/database-connector.git
$ cd database-connector
  2. 目的のコネクタのバージョンを確認します。
    $ git checkout tags/v1-0.0.3
  3. コネクタをビルドします。 
    $ mvn package
    コネクタのビルド時にテストをスキップするには、mvn package -DskipTests を使用します。
  4. コネクタの zip ファイルをローカルのインストール ディレクトリにコピーして解凍します。 
    $ cp target/google-cloudsearch-database-connector-v1-0.0.3.zip installation-dir
$ cd installation-dir
$ unzip google-cloudsearch-database-connector-v1-0.0.3.zip
$ cd google-cloudsearch-database-connector-v1-0.0.3

手順 2. データベース コネクタを構成する

  1. テキスト ファイルを作成し、connector-config.properties（デフォルト）などの名前を付けます。構成ファイルに .properties または .config 拡張子を付けて、ファイルをコネクタと同じディレクトリに置くことをおすすめします。別の名前またはパスを使用する場合は、コネクタの実行時にパスを指定する必要があります。
  2. パラメータを Key-Value ペアとしてファイルの内容に追加します。構成ファイルでは、データソース アクセス、データベース アクセス、データベース フル走査 SQL ステートメント、コンテンツ フィールドのタイトル、列定義のパラメータを指定する必要があります。オプションのパラメータを使用して、他のコネクタの動作を構成することもできます。次に例を示します。 
    # Required parameters for data source access
api.sourceId=1234567890abcdef
api.identitySourceId=0987654321lmnopq
api.serviceAccountPrivateKeyFile=./PrivateKey.json
#
# Required parameters for database access
db.url=jdbc:mysql://localhost:3306/mysql_test
db.user=root
db.password=passw0rd
#
# Required full traversal SQL statement parameter
db.allRecordsSql=select customer_id, first_name, last_name, phone, change_timestamp from address_book
#
# Required parameters for column definitions and URL format
db.allColumns=customer_id, first_name, last_name, phone, change_timestamp
db.uniqueKeyColumns=customer_id
url.columns=customer_id
#
# Required content field parameter
contentTemplate.db.title=customer_id
#
# Optional parameters to set ACLs to "entire domain" access
defaultAcl.mode=fallback
defaultAcl.public=true
#
# Optional parameters for schedule traversals
schedule.traversalIntervalSecs=36000
schedule.performTraversalOnStart=true
schedule.incrementalTraversalIntervalSecs=3600

    データベース固有のパラメータの詳細については、この記事の最後にある 構成パラメータのリファレンスをご覧ください。

    メタデータ構成、日時形式、ACL オプションなど、すべての Cloud Search コネクタに共通するパラメータについては、 Google 提供のコネクタ パラメータをご覧ください。

    必要に応じて、走査 SQL クエリ パラメータでスキーマ オブジェクトのプロパティを指定します。通常は、SQL ステートメントにエイリアスを追加できます。たとえば、映画のデータベースがあり、データソース スキーマに「ActorName」という名前のプロパティ定義が含まれている場合、SQL ステートメントの形式は SELECT …, last_name AS ActorName, … FROM … のようになります。

ステップ 3: データベース コネクタを実行する

次の例では、必要なコンポーネントが Linux システムのローカル ディレクトリにあることを前提としています。

コマンドラインからコネクタを実行するには、次のコマンドを入力します。

java \
   -cp "google-cloudsearch-database-connector-v1-0.0.3.jar:mysql-connector-java-5.1.41-bin.jar" \
   com.google.enterprise.cloudsearch.database.DatabaseFullTraversalConnector \
   [-Dconfig=mysql.config]

ここで

  • google-cloud-search-database-connector-v1-0.0.3.jar は、データベース コネクタの .jar ファイルです。
  • mysql-connector-java-5.1.41-bin.jar は、データベースへのアクセスに使用される JDBC ドライバです。
  • mysql.config はカスタム名の構成ファイルです。コネクタが構成ファイルを認識できるようにするには、コマンドラインでそのパスを指定します。それ以外の場合、コネクタはローカル ディレクトリ内の connector-config.properties をデフォルトのファイル名として使用します。

コネクタは、検出されると構成エラーを報告します。一部のエラーは、コネクタの初期化時に報告されます。たとえば、データベース列がレコード コンテンツの一部として定義されているにもかかわらず（db.allColumns で）、その列がデータベースの走査 SQL クエリ（db.allRecordsSql 内）で使用されていない場合などです。その他のエラー（無効な SQL ステートメントなど）は、コネクタが最初の走査でデータベースにアクセスしようとした場合にのみ検出され、報告されます。

構成パラメータのリファレンス

データソースのアクセス パラメータ

設定 パラメータ
データソース ID api.sourceId = source-ID

必須。Google Workspace 管理者が設定した Cloud Search ソース ID。
ID ソースの ID api.identitySourceId = identity-source-ID

ACL に外部のユーザーとグループを使用するために必要です。Google Workspace 管理者が設定した Cloud Search ID ソースの ID。
サービス アカウント api.serviceAccountPrivateKeyFile = path-to-private-key

必須。Google Workspace 管理者が作成した Cloud Search サービス アカウント キー ファイルのパス。

データベース アクセス パラメータ

設定 パラメータ
データベースの URL db.url = database-URL

必須。アクセスされるデータベースのフルパス（jdbc:mysql://127.0.0.1/dbname など）。
データベースのユーザー名とパスワード db.user = username
db.password = password

必須。コネクタがデータベースへのアクセスに使用する有効なユーザー名とパスワード。このデータベース ユーザーには、読み取り対象のデータベースの関連レコードに対する読み取りアクセス権が必要です。
JDBC ドライバ db.driverClass = oracle.jdbc.OracleDriver

JDBC 4.0 ドライバがクラスパスでまだ指定されていない場合にのみ、必須です。

走査 SQL クエリ パラメータ

コネクタは、構成ファイルの SQL SELECT クエリを使用してデータベース レコードを走査します。フル走査クエリを構成する必要があります。増分走査のクエリはオプションです。

フル走査では、インデックス登録用に構成されたすべてのデータベース レコードが読み取られます。新しいレコードを Cloud Search でインデックスに登録し、既存のすべてのレコードをインデックスに再登録するには、フル走査が必要です。

増分走査では、新しく変更されたデータベース レコードとデータベースへの最近のエントリのみを読み取り、インデックスに再登録します。増分走査は、フル走査よりも効率的です。増分走査を使用するには、変更されたレコードを示すタイムスタンプ フィールドがデータベースに含まれている必要があります。

コネクタは、 走査スケジュールのパラメータで定義されたスケジュールに従って、これらの走査を実行します。

設定 パラメータ
完全な走査クエリ db.allRecordsSql = SELECT column-1[, column-2,...] FROM database-name

必須。クエリはすべてのフル走査で実行されます。

コネクタが任意の容量（コンテンツ、一意の ID、ACL）で使用するすべての列名が、このクエリに含まれている必要があります。コネクタは、起動時に予備検証を行ってエラーや欠落を検出します。このため、一般的な「SELECT * FROM ...」クエリは使用しないでください。
フル走査のページネーション db.allRecordsSql.pagination = {none | offset}

次のいずれかの値を指定できます。

  • none: ページ分割を使用しません。
  • offset: 行オフセットによるページ分割を使用します。

    オフセットによるページ分割を使用するには、SQL クエリで、行オフセットに対応するプレースホルダ疑問符（?）が 0 から始まる必要があります。結果が返されなくなるまで、フル走査ごとにクエリが繰り返し実行されます。
増分走査クエリ db.incrementalUpdateSql = SELECT column-1[, column-2,...] FROM database-name WHERE last_update_time > ?

増分走査をスケジュールする場合は必須です。

クエリ内の「?」はタイムスタンプ値の必須のプレースホルダです。コネクタはタイムスタンプを使用して、増分走査の SQL クエリ間の変更を追跡します。

最終更新時刻のデータベース タイムスタンプ列を追跡するには、SQL ステートメントに timestamp_column エイリアスを追加します。それ以外の場合は、コネクタ走査の現在のタイムスタンプを使用します。

最初の増分走査では、コネクタの開始時間が使用されます。最初の増分走査の後、Cloud Search はコネクタの再起動時に以前の増分走査のタイムスタンプにアクセスできるようにタイムスタンプを保存します。
データベースのタイムゾーン db.timestamp.timezone = America/Los_Angeles

データベースのタイムスタンプに使用するタイムゾーンを指定します。新しいレコードの追加や新しく変更されたデータベース レコードを識別するために使用されるデータベースのタイムスタンプ。デフォルトは、コネクタが実行されているローカル タイムゾーンです。

走査 SQL クエリの例

  • インデックス登録のために従業員データベース内のすべての対象レコードを読み取る基本的なフル走査クエリ。 
    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee
  • オフセットによりページネーションを指定し、フル走査を複数のクエリに分割します。

    SQL Server 2012 または Oracle 12c（標準 SQL 2008 構文）の場合:

    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee \
    ORDER BY customer_id OFFSET ? ROWS FETCH FIRST 1000 ROWS ONLY
db.allRecordsSql.pagination = offset

    MySQL または Google Cloud SQL の場合:

    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee \
    ORDER BY customer_id LIMIT 1000 OFFSET ?
db.allRecordsSql.pagination = offset
  • エイリアスを使用して個別の ACL を適用する完全な走査クエリ: 
    db.allRecordsSql = SELECT customer_id, first_name, last_name,  employee_id, interesting_field, last_update_time, \
     permitted_readers AS readers_users, \
     denied_readers AS denied_users, \
     permitted_groups AS readers_groups, \
     denied_groups AS denied_groups \
     FROM employee
  • 基本的な増分走査クエリ: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time \
     FROM employee \
     WHERE last_update_time > ?
  • エイリアスを使用して個々の ACL を適用する増分走査クエリ: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time, \
     permitted_readers AS readers_users, \
     denied_readers AS denied_users, \
     permitted_groups AS readers_groups, \
     denied_groups AS denied_groups \
     FROM employee \
     WHERE last_update_time > ?
  • 現在の時刻ではなくデータベースのタイムスタンプを使用する増分走査クエリ: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, \
     last_update_time AS timestamp_column \
     FROM employee \
     WHERE last_update_time > ?

列定義のパラメータ

次のパラメータは、走査ステートメントで各レコードを一意に識別するために使用する列を指定します。

設定 パラメータ
すべての列 db.allColumns = column-1, column-2, ...column-N

必須。データベースにアクセスするときに SQL クエリで必要なすべての列を指定します。このパラメータで定義した列は、クエリで明示的に参照する必要があります。他のすべての列定義パラメータは、この列セットと比較されます。

例:

db.allColumns = customer_id, first_name, last_name, phone, change_timestamp
一意キーの列 db.uniqueKeyColumns = column-1[, column-2]

必須。一意の値を含む単一のデータベース列、または値をまとめて一意の ID を定義する列の組み合わせを指定します。

Cloud Search では、すべての検索可能なドキュメントにデータソース内で一意の識別子があることが必要です。列の値から、データベース レコードごとに一意の ID を定義できる必要があります。別々のデータベースで複数のコネクタを実行し、共通のデータセットにインデックス登録する場合は、すべてのドキュメントで一意の ID を指定してください。

例:

db.uniqueKeyColumns = customer_id
# or
db.uniqueKeyColumns = last_name, first_name
URL リンク列 url.columns = column-1[, column-2]

必須。クリック可能な検索結果に使用される URL に使用される列の有効な定義済みの名前を 1 つ以上指定します。関連する URL が各データベース レコードに関連付けられていないデータベースの場合は、すべてのレコードに静的リンクを使用できます。

ただし、列の値が各レコードの有効なリンクを定義する場合は、表示 URL の列と形式の構成値を指定する必要があります。
URL 形式 url.format = https://www.example.com/{0}

表示 URL の形式を定義します。番号付きのパラメータは、db.columns で指定された列をゼロから順に参照します。

指定しない場合のデフォルトは「{0}」です。

次の表に例を示します。
URL のパーセントでエンコードされた列 url.columnsToEscape = column-1[, column-2]

形式が設定された URL 文字列に挿入する前に値がパーセントでエンコードされる、db.columns の列を指定します。

URL の列の例

走査クエリで使用する列と表示 URL の形式を指定するには:

  • データベース レコード値を使用しない静的 URL を使用するには: 
    url.format = https://www.example.com
  • 表示 URL である単一の列の値を使用するには: 
    url.format = {0}
url.columns = customer_id
  • 位置 {0} の表示 URL に代入される単一の列の値を使用するには: 
    url.format = https://www.example.com/customer/id={0}
url.columns = customer_id
url.columnsToEscape = customer_id
  • 複数の列の値を使用して表示 URL を作成する場合（列は順序に依存します）: 
    url.format = {1}/customer={0}
url.columns = customer_id, linked_url
url.columnsToEscape = customer_id

コンテンツの項目

コンテンツ オプションを使用して、検索可能なコンテンツの一部にするレコード値を定義します。

設定 パラメータ
最高品質の検索列 contentTemplate.db.title = column-name

必須。検索インデックスと結果の優先順位付けのための最高品質の列。
検索における列の優先順位付け contentTemplate.db.quality.high = column-1[, column-2...]
contentTemplate.db.quality.medium = column-1[, column-2...]
contentTemplate.db.quality.low = column-1[, column-2...]

コンテンツ列（contentTemplate.db.title で設定した列を除く）を高、中、低検索品質のフィールドとして指定します。未指定の列は、デフォルトで「低」に設定されます。
コンテンツ データの列 db.contentColumns = column-1[, column-2...]

データベース内のコンテンツ列を指定します。これらは検索可能なドキュメント コンテンツとしてフォーマットされ、Cloud Search にアップロードされます。

値を指定しない場合、デフォルトは「*」で、すべての列がコンテンツに使用されることを示します。
Blob 列 db.blobColumn = column-name

コンテンツ列の組み合わせの代わりに、ドキュメント コンテンツに使用する単一の blob 列の名前を指定します。

blob 列が指定されている場合、コンテンツ列も定義されていると、エラーとみなされます。ただし、メタデータと構造化データの列定義は blob 列とともに使用できます。