| Oracle® Fusion Middleware Oracle GoldenGate for Big Dataの統合 リリース12.3.1.1 E89944-01 |
|
 前 |
 次 |
この章では、Elasticsearchハンドラについて説明し、その機能を理解できるように例を示します。
トピック:
Elasticsearchは、拡張性の高い、オープン・ソースのフルテキスト検索および分析エンジンです。Elasticsearchを使用すると、大量のデータをすばやく、ほぼリアルタイムで保存、検索および分析できます。通常、複雑な検索機能を備えたアプリケーションを駆動する基盤となるエンジンやテクノロジとして使用されます。
Elasticsearchハンドラでは、Elasticsearch Javaクライアントを使用してElasticsearchノードに接続し、データを受信します。詳細は、次に示すElasticsearchのWebサイトを参照してください。
トピック:
Elasticsearchハンドラのプロパティgg.handler.name.versionは、Elasticsearchクラスタのバージョンに従って設定する必要があります。ElasticsearchハンドラはJavaのTransportクライアントを使用し、そのバージョンは、クラスタ内のノードと同じメジャー・バージョン(2.xまたは5.xなど)である必要があります。新しい機能はサポートされない可能性はありますが、Elasticsearchハンドラは、マイナー・バージョン(2.3.xなど)の異なるクラスタにも接続できます。
Elasticsearchのインデックスは、類似した特性を持つドキュメントの集まりです。インデックスは小文字でのみ作成できます。Elasticsearchのタイプは、インデックス内の論理グループです。インデックスまたはタイプ内のすべてのドキュメントは、同じ番号およびタイプのフィールドを持つ必要があります。
Elasticsearchハンドラでは、ソース証跡スキーマをソース証跡表名と連結してインデックスが構築されます。ソース証跡の3つの部分からなる表名の場合、インデックスはソース・カタログ、スキーマおよび表名を連結して構成されます。
Elasticsearchハンドラでは、ソース表名がElasticsearchのタイプにマッピングされます。タイプ名は大文字と小文字を区別します。
表3-1 Elasticsearchのマッピング
| ソース証跡 | Elasticsearchのインデックス | Elasticsearchのタイプ |
|---|---|---|
|
|
|
|
|
|
Elasticsearchクラスタにまだインデックスが存在しない場合は、Elasticsearchハンドラがデータを受信すると(ソース証跡でのINSERTまたはUPDATE操作)、新しいインデックスが作成されます。
Elasticsearchのドキュメントは、インデックス付けのできる情報の基本単位です。インデックスまたはタイプ内に、必要な数のドキュメントを格納できます。各ドキュメントには_idフィールドに基づく一意の識別子があります。
Elasticsearchハンドラでは、ソース証跡の主キー列の値がドキュメント識別子としてマッピングされます。
Elasticsearchのドキュメント識別子はソース表の主キー列の値に基づいて作成されます。ドキュメント識別子は変更できません。Elasticsearchハンドラでは、DELETEに続いてINSERTを実行することによってソース主キーの更新操作が処理されます。INSERTの実行中、新しいドキュメントのフィールドが必要なフィールド数よりも少ないことがあります。ソース表内のすべてのフィールドをINSERT操作に含めるには、更新操作用にデータ全体のビフォア・イメージをキャプチャするように証跡のExtractを有効にするか、GETBEFORECOLSを使用して必要な列のビフォア・イメージを書き込みます。
Elasticsearchでは次のデータ型がサポートされています。
32ビット整数
64ビット整数
Double
Date
String
Binary
ソース証跡の3つの部分からなる表名の場合、インデックスはソース・カタログ、スキーマおよび表名を連結して構成されます。
Elasticsearchハンドラでは、ソース表名がElasticsearchのタイプにマッピングされます。タイプ名は大文字と小文字を区別します。
表3-2 Elasticsearchの操作
| 操作 | 説明 |
|---|---|
|
Elasticsearchハンドラでは、インデックスが存在しない場合、新規インデックスが作成されて新規ドキュメントが挿入されます。 |
|
Elasticsearchのインデックスやドキュメントが存在する場合は、そのドキュメントが更新されます。Elasticsearchのインデックスやドキュメントが存在しない場合は、新規インデックスが作成され、 |
|
Elasticsearchのインデックスやドキュメントが存在する場合は、そのドキュメントが削除されます。Elasticsearchのインデックスやドキュメントが存在しない場合は、フィールドがゼロの新規インデックスが作成されます。 |
注意:
TRUNCATE操作はサポートされていません。Elasticsearchクラスタが正しく設定され、そのクラスタが稼働していることを確認する必要があります(https://www.elastic.co/guide/en/elasticsearch/reference/current/_installation.htmlを参照)。また、Kibanaを使用して設定を確認することもできます。
クラスパスの設定
プロパティgg.classpathには、Javaのトランスポート・クライアントに必要なすべてのjarが含まれている必要があります。必要なクライアントJARファイルのバージョン別リストは、「Elasticsearchハンドラ・クライアント依存性」を参照してください。
Default location of 2.X JARs: Elasticsearch_Home/lib/* Elasticsearch_Home/plugins/shield/*
Default location of 5.X JARs: Elasticsearch_Home/lib/* Elasticsearch_Home/plugins/x-pack/* Elasticsearch_Home/modules/transport-netty3/* Elasticsearch_Home/modules/transport-netty4/* Elasticsearch_Home/modules/reindex/*
パス内のワイルドカード(*)は、(*)のワイルドカード文字により、そのディレクトリ内のすべてのJARファイルを関連するクラスパスに含めることができます。*.jarは使用しないでください
正しく構成されたクラスパスの例を次に示します。
gg.classpath=Elasticsearch_Home/lib/*
トピック:
Elasticsearchハンドラの構成可能な値は次のとおりです。これらのプロパティは、Javaアダプタ・プロパティ・ファイルにあります(Replicatプロパティ・ファイルにはありません)。
表3-3 Elasticsearchハンドラの構成プロパティ
| プロパティ | 必須/オプション | 有効な値 | デフォルト | 説明 |
|---|---|---|---|---|
gg.handlerlist |
必須 |
名前(任意の名前) |
なし |
使用するハンドラのリスト。 |
gg.handler.name.type |
必須 |
elasticsearch |
なし |
使用するハンドラのタイプ。たとえば、Elasticsearch、Kafka、Flume、HDFSなどです。 |
gg.handler.name.ServerAddressList |
オプション |
|
|
Elasticsearchクラスタに接続するノードの連絡ポイントのカンマ区切りのリスト。 |
gg.handler.name.clientSettingsFile |
必須 |
トランスポート・クライアントのプロパティ・ファイル。 |
なし |
Elasticsearchハンドラで使用されるElasticsearchトランスポート・クライアントのプロパティを保持するクラスパスのファイル名。 |
gg.handler.name.version |
オプション |
|
|
Elasticsearchハンドラで使用されるトランスポート・クライアントのバージョンで、これはElasticsearchクラスタとの互換性が必要です。 |
gg.handler.name.bulkWrite |
オプション |
|
|
このプロパティが |
gg.handler.name.numberAsString |
オプション |
|
|
このプロパティが |
gg.handler.elasticsearch.upsert |
オプション |
|
|
このプロパティが |
例3-1 サンプルのハンドラ・プロパティ・ファイル:
2.x Elasticsearchクラスタの場合:
gg.handlerlist=elasticsearch gg.handler.elasticsearch.type=elasticsearch gg.handler.elasticsearch.ServerAddressList=localhost:9300 gg.handler.elasticsearch.clientSettingsFile=client.properties gg.handler.elasticsearch.version=2.x gg.classpath=/path/to/elastic/lib/*
2.x Elasticsearchクラスタ(Shieldあり)の場合:
gg.handlerlist=elasticsearch gg.handler.elasticsearch.type=elasticsearch gg.handler.elasticsearch.ServerAddressList=localhost:9300 gg.handler.elasticsearch.clientSettingsFile=client.properties gg.handler.elasticsearch.version=2.x gg.classpath=/path/to/elastic/lib/*:/path/to/elastic/plugins/shield/*
5.x Elasticsearchクラスタの場合:
gg.handlerlist=elasticsearch gg.handler.elasticsearch.type=elasticsearch gg.handler.elasticsearch.ServerAddressList=localhost:9300 gg.handler.elasticsearch.clientSettingsFile=client.properties gg.handler.elasticsearch.version=5.x gg.classpath=/path/to/elastic/lib/*:/path/to/elastic/modules/transport-netty4/*:/path/to/elastic/modules/reindex/*
5.x Elasticsearchクラスタ(x-packあり)の場合:
gg.handlerlist=elasticsearch gg.handler.elasticsearch.type=elasticsearch gg.handler.elasticsearch.ServerAddressList=localhost:9300 gg.handler.elasticsearch.clientSettingsFile=client.properties gg.handler.elasticsearch.version=5.x gg.classpath=/path/to/elastic/lib/*:/path/to/elastic/plugins/x-pack/*:/path/to/elastic/modules/transport-netty4/*:/path/to/elastic/modules/reindex/*
サンプルのReplicat構成およびJavaアダプタのプロパティ・ファイルは、次のディレクトリにあります。
GoldenGate_install_directory/AdapterExamples/big-data/elasticsearchElasticsearchハンドラは、JavaのTransportクライアントを使用してElasticsearchクラスタとやりとりします。Elasticsearchクラスタには、shieldやx-packのような追加のプラグインがあり、追加の構成が必要な場合があります。
gg.handler.name.clientSettingsFileプロパティは、Elasticsearchクラスタのバージョンに基づく追加のクライアント設定のあるファイルを指している必要があります。Elasticsearchハンドラは、Javaクラスパスを使用してクライアント設定ファイルの検索とロードを試みます。Javaクラスパスには、プロパティ・ファイルのあるディレクトリが含まれている必要があります。
Elasticsearch 2.x(プラグインなし)のクライアント・プロパティ・ファイル:
cluster.name=Elasticsearch_cluster_name
Shieldプラグインを使用するElasticsearch 2.Xのクライアント・プロパティ・ファイル:
cluster.name=Elasticsearch_cluster_name shield.user=shield_username:shield_password
Shieldプラグインは、SSLやIPフィルタリングなどの追加機能もサポートしています。プロパティはclient.propertiesファイルで設定できます(https://www.elastic.co/guide/en/elasticsearch/client/java-api/2.4/transport-client.htmlおよびhttps://www.elastic.co/guide/en/shield/current/_using_elasticsearch_java_clients_with_shield.htmlを参照)。
X-Packプラグインを使用するElasticsearch 5.xのclient.propertiesファイル:
cluster.name=Elasticsearch_cluster_name xpack.security.user=x-pack_username:x-pack-password
X-Packプラグインも追加の機能をサポートしています。プロパティはclient.propertiesファイルで設定できます(https://www.elastic.co/guide/en/elasticsearch/client/java-api/5.1/transport-client.htmlおよびhttps://www.elastic.co/guide/en/x-pack/current/java-clients.htmlを参照)。
Elasticsearchハンドラのgg.handler.name.bulkWriteプロパティは、Elasticsearchクラスタにソース証跡レコードをプッシュする際に、一度に1つずつ行うか、または一括書込みAPIを使用して一括で行うかを判断するために使用されます。このプロパティがtrueの場合、ソース証跡の操作は、一般的なReplicatパラメータ・ファイルのMAXTRANSOPSパラメータによってサイズを制御されるバッチでElasticsearchクラスタにプッシュされます。一括書込みAPIを使用するとパフォーマンスが向上します。
Elasticsearchは、ノード内で管理されるスレッド・プールのメモリー消費量を改善するために、異なるスレッド・プールを使用します。また、これらのプールの多くにはそれに関連付けられたキューも存在し、保留中のリクエストは廃棄されずに保持されます。
一括操作の場合、デフォルトのキュー・サイズは50(バージョン5.2)および200(バージョン5.3)です。
一括APIのエラーを回避するには、ReplicatのMAXTRANSOPSサイズを一括スレッドのプール・キュー・サイズの最小値と一致するように設定する必要があります。thread_pool.bulk.queue_size構成プロパティはelasticsearch.yamlファイルで変更できます。
Elasticsearchバージョン2.xでは、基本認証、SSLおよびIPフィルタリングを提供するShieldプラグインがサポートされています。Elasticsearch 5.xのX-Packプラグインにも同様の機能があります。追加のトランスポート・クライアントの設定は、gg.handler.name.clientSettingsFileプロパティを使用してElasticsearchハンドラで構成できます。
Elasticsearchハンドラはソース証跡内のDDLレコードには反応しません。新規ソース表のデータ操作レコードにより、Elasticsearchクラスタでインデックスまたはタイプの自動作成が行われます。
Elasticsearchハンドラでは、パフォーマンスを向上させるために操作モードが使用されます。gg.handler.name.modeプロパティはハンドラでは使用されません。
この項では、様々な問題のトラブルシューティングに役立つ情報を示します。
トピック:
最も一般的な初期エラーは、必要なすべてのクライアント・ライブラリを含めるクラスパスが正しくないことす。log4jログ・ファイルにClassNotFound例外が作成されます。
また、gg.classpath変数に表記上の誤りがある場合、クラスパス解決エラーの原因となる可能性があります。
Elasticsearchのトランスポート・クライアント・ライブラリには、Oracle GoldenGate for Big Data製品は付属していません。クライアント・ライブラリを正しく解決するには、Javaアダプタのプロパティ・ファイルでgg.classpathプロパティを正しく構成する必要があります(「Elasticsearchハンドラの設定および実行」を参照)。
Elasticsearchクラスタのメジャー・バージョン番号と一致させるには、Elasticsearchハンドラのgg.handler.name.versionプロパティを2.xまたは5.xに設定する必要があります。
バージョン構成に誤りがあると、次のエラーが発生することがあります。
Error: NoNodeAvailableException[None of the configured nodes are available:] ERROR 2017-01-30 22:35:07,240 [main] Unable to establish connection. Check handler properties and client settings configuration. java.lang.IllegalArgumentException: unknown setting [shield.user]
必要なすべてのプラグインがインストールされていることを確認し、削除されたすべての設定に関するドキュメントの変更点を確認します。
この例外を解決するには:
ERROR 2017-01-30 22:33:10,058 [main] Unable to establish connection. Check handler properties and client settings configuration.
gg.handler.name.clientSettingsFile構成プロパティに、Elasticsearchトランスポート・クライアントの設定ファイル名が正しく設定されていることを確認します。gg.classpath変数に正しいファイル名へのパスが含まれ、プロパティ・ファイルへのパスの最後にアスタリスク(*)のワイルドカードが含まれていないことを確認します。
このエラーは、ElasticsearchハンドラがElasticsearchクラスタに接続できない場合に発生します。
Error: NoNodeAvailableException[None of the configured nodes are available:]
この問題をデバッグするには、次の手順を実行します。
Elasticsearchのサーバー・プロセスが実行中であることを確認します。
クライアント・プロパティ構成ファイルで、cluster.nameプロパティを確認します。
クライアント・プロパティ・ファイルで、x-PackまたはShieldプラグインの認証の資格証明を確認します。
gg.handler.name.ServerAddressListハンドラ・プロパティを確認します。
TRUNCATE操作Elasticsearchハンドラがソース証跡でTRUNCATE操作を検出すると、次のエラーが発生します。
oracle.goldengate.util.GGException: Elasticsearch Handler does not support the operation: TRUNCATE
この例外エラー・メッセージは、RAeplicatプロセスが異常終了する前にハンドラのログ・ファイルに書き込まれます。Replicatのパラメータ・ファイルからGETTRUNCATESパラメータを削除すると、このエラーが解決します。
ハンドラが一括API(bulkWrite=true)を使用して操作を処理しているときに、次のエラーが発生することがあります。
Elasticsearchが操作を処理するためのリソースが不足している可能性があります。MAXTRANSOPSを使用してReplicatのバッチ・サイズを制限し、Elasticsearchの構成パラメータthread_pool.bulk.queue_sizeの値と一致させることができます。
注意:
Elasticsearchのパラメータthread_pool.bulk.queue_sizeの変更は、Elasticsearchノードの再起動後にのみ有効です。接続に成功すると、ハンドラのログ・ファイルに次のログ・メッセージが表示されます。
2.x Elasticsearchクラスタへの接続:
INFO 2017-01-31 01:43:38,814 [main] **BEGIN Elasticsearch client settings**
INFO 2017-01-31 01:43:38,860 [main] key[cluster.name] value[elasticsearch-user1-myhost]
INFO 2017-01-31 01:43:38,860 [main] key[request.headers.X-Found-Cluster] value[elasticsearch-user1-myhost]
INFO 2017-01-31 01:43:38,860 [main] key[shield.user] value[es_admin:user1]
INFO 2017-01-31 01:43:39,715 [main] Connecting to Server[myhost.us.example.com] Port[9300]
INFO 2017-01-31 01:43:39,715 [main] Client node name: Smith
INFO 2017-01-31 01:43:39,715 [main] Connected nodes: [{node-myhost}{vqtHikpGQP-IXieHsgqXjw}{10.196.38.196}{198.51.100.1:9300}]
INFO 2017-01-31 01:43:39,715 [main] Filtered nodes: []
INFO 2017-01-31 01:43:39,715 [main] **END Elasticsearch client settings**
5.x Elasticsearchクラスタへの接続:
INFO [main] (Elasticsearch5DOTX.java:38) - **BEGIN Elasticsearch client settings**
INFO [main] (Elasticsearch5DOTX.java:39) - {xpack.security.user=user1:user1_kibana, cluster.name=elasticsearch-user1-myhost, request.headers.X-Found-Cluster=elasticsearch-user1-myhost}
INFO [main] (Elasticsearch5DOTX.java:52) - Connecting to Server[myhost.us.example.com] Port[9300]
INFO [main] (Elasticsearch5DOTX.java:64) - Client node name: _client_
INFO [main] (Elasticsearch5DOTX.java:65) - Connected nodes: [{node-myhost}{w9N25BrOSZeGsnUsogFn1A}{bIiIultVRjm0Ze57I3KChg}{myhost}{198.51.100.1:9300}]
INFO [main] (Elasticsearch5DOTX.java:66) - Filtered nodes: []
INFO [main] (Elasticsearch5DOTX.java:68) - **END Elasticsearch client settings**
Elasticsearch: 非常に大きな数を入力しようとしています
非常に大きな数値は、Elasticsearchのドキュメントでは不正確な値になります。たとえば、9223372036854775807、-9223372036854775808。これは、Elasticsearchサーバーの問題であり、Elasticsearchハンドラの制限ではありません。
この問題の回避策は、gg.handler.name.numberAsString=trueプロパティを使用してすべての数値を文字列として収集することです。
Elasticsearch: インデックスの問題
類似した列名で異なる列データ型を持つ複数の表がある場合、Elasticsearchハンドラでは同じインデックスにデータを入力できません。
証跡内のcatalog/schema/tablenameは、大文字と小文字を区別することがありますが、インデックス名は常に小文字です。
