データベース コネクタをデプロイする

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

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

重要な考慮事項

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

システム要件

システム要件
OS 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 クエリ間の変更を追跡します。

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

最初の増分走査では、コネクタの開始時刻が使用されます。最初の増分走査の後に、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 > ?
  • エイリアス
    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 > ?
    を使用して個々の ACL を適用する増分トラバーサル クエリ
  • 現在の時刻ではなく、データベースのタイムスタンプを使用する増分走査クエリ:
    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
  • ビュー URL に置き換えられている単一の列の値をビュー 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 列とともに使用できます。