警告: Cloud Search リファレンス コネクタは、独自のコネクタの作成に使用できるサンプルコードとして「現状のまま」提供されています。このサンプルコードは、概念実証や本番環境で使用する前に、かなりのカスタマイズとテストを行う必要があります。本番環境で使用する場合は、Cloud Search パートナーにサポートを受けることを強くおすすめします。適切な Cloud Search パートナーを探すには、Google アカウント マネージャーにお問い合わせください。 |
Google Cloud Search データベース コネクタを使用することで、組織のデータベースからデータを検出してインデックスに登録するように Google Cloud Search を設定できます。
重要な考慮事項
Cloud Search データベース コネクタは、インターネットとデータベースの両方にアクセスできる限り、Java アプリを実行できるほぼすべての環境にインストールして実行できます。
システム要件
システム要件 | |
---|---|
オペレーティング システム | Windows または Linux |
SQL データベース | JDBC 4.0 以降に準拠したドライバを使用する任意の SQL データベース(以下を含む)。
|
ソフトウェア | コネクタがデータベースへのアクセスに使用する JDBC ドライバ(別途ダウンロードしてインストール) |
コネクタをデプロイする
次の手順では、コネクタをインストールして、指定されたデータベースをインデックスに登録し、結果を Cloud Search ユーザーに返すように構成する方法について説明します。
前提条件
Cloud Search データベース コネクタをデプロイする前に、次の情報を収集します。
- Google Workspace の秘密鍵。サービス アカウント ID も含まれます。秘密鍵を取得する方法については、 Google Cloud Search REST API へのアクセスを構成するをご覧ください。
- Google Workspace データソース ID。データソース ID を取得する方法については、検索するデータソースを追加するをご覧ください。
ステップ 1: データベース コネクタ ソフトウェアをダウンロードしてビルドする
- GitHub からコネクタ リポジトリのクローンを作成します。
$ git clone https://github.com/google-cloudsearch/database-connector.git $ cd database-connector
- 目的のコネクタのバージョンを確認します。
$ git checkout tags/v1-0.0.3
- コネクタをビルドします。
$ mvn package
コネクタのビルド時にテストをスキップするには、mvn package -DskipTests
を使用します。 - コネクタの 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. データベース コネクタを構成する
- テキスト ファイルを作成し、
connector-config.properties
(デフォルト)などの名前を付けます。構成ファイルに.properties
または.config
拡張子を付けて、ファイルをコネクタと同じディレクトリに置くことをおすすめします。別の名前またはパスを使用する場合は、コネクタの実行時にパスを指定する必要があります。 - パラメータを 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
必須。アクセスされるデータベースのフルパス( |
データベースのユーザー名とパスワード | 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}
次のいずれかの値を指定できます。
|
増分走査クエリ | db.incrementalUpdateSql = SELECT column-1[, column-2,...] FROM database-name WHERE last_update_time > ?
増分走査をスケジュールする場合は必須です。 クエリ内の「?」はタイムスタンプ値の必須のプレースホルダです。コネクタはタイムスタンプを使用して、増分走査の SQL クエリ間の変更を追跡します。 最終更新時刻のデータベース タイムスタンプ列を追跡するには、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 > ?
- エイリアスを使用して個々の 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...]
コンテンツ列( |
コンテンツ データの列 | db.contentColumns = column-1[, column-2...]
データベース内のコンテンツ列を指定します。これらは検索可能なドキュメント コンテンツとしてフォーマットされ、Cloud Search にアップロードされます。 値を指定しない場合、デフォルトは「*」で、すべての列がコンテンツに使用されることを示します。 |
Blob 列 | db.blobColumn = column-name
コンテンツ列の組み合わせの代わりに、ドキュメント コンテンツに使用する単一の blob 列の名前を指定します。 blob 列が指定されている場合、コンテンツ列も定義されていると、エラーとみなされます。ただし、メタデータと構造化データの列定義は blob 列とともに使用できます。 |