8.2.31 追加の詳細

• コマンド・イベント・ハンドラ
  この章では、コマンド・イベント・ハンドラの使用方法について説明します。コマンド・イベント・ハンドラは、外部プログラムまたはスクリプトを同期的に実行するためのインタフェースを提供します。
• HDFSイベント・ハンドラ
  HDFSイベント・ハンドラを使用して、ファイル・ライター・ハンドラによって生成されたファイルをHDFSにロードします。
• メタ列のキーワード
  
• メタデータ・プロバイダ
  メタデータ・プロバイダは、Replicatパラメータ・ファイルを使用してソースからターゲットに複製できます。
• プラガブル・フォーマッタ
  プラガブル・フォーマッタを使用して、Oracle GoldenGate証跡ファイルからの操作を、フォーマット済のメッセージに変換します。このメッセージは、GG for DAAハンドラのいずれかを使用してOracle GoldenGate for Distributed Applications and Analytics (GG for DAA)ターゲットに送信できます。
• ステージングおよびマージによるデータ・ウェアハウス・レプリケーション
  通常データ・ウェアハウス・ターゲットはMassively Parallel Processing (MPP)をサポートしています。1回のデータ操作言語(DML)操作のコストがバッチDMLの実行コストに匹敵します。
• テンプレートのキーワード
  
• Velocity依存性
  Oracle GoldenGate for Big Dataリリース21.1.0.0.0から、Velocity jarファイルがパッケージから削除されました。

8.2.31.1 コマンド・イベント・ハンドラ

この章では、コマンド・イベント・ハンドラの使用方法について説明します。コマンド・イベント・ハンドラは、外部プログラムまたはスクリプトを同期的に実行するためのインタフェースを提供します。

• 概要 - コマンド・イベント・ハンドラ
  コマンド・イベント・ハンドラの目的は、指定された外部プログラムまたはスクリプトを実行することで、ファイル・ライター・ハンドラによって生成されたデータ・ファイルを各ターゲットにロードすることです。
• コマンド・イベント・ハンドラの構成
  ファイル・ライター・ハンドラのプロパティ・ファイルを使用して、コマンド・イベント・ハンドラの操作を構成できます。
• コマンド引数テンプレート文字列の使用
  コマンド引数テンプレート文字列は、実行時に動的に解決されるキーワードで構成されます。コマンド引数テンプレート文字列は、commandArgumentTemplateプロパティに指定されている順序と同じ順序で引数としてスクリプトに渡されます。

8.2.31.1.1 概要 - コマンド・イベント・ハンドラ

コマンド・イベント・ハンドラの目的は、指定された外部プログラムまたはスクリプトを実行することで、ファイル・ライター・ハンドラによって生成されたデータ・ファイルを各ターゲットにロードすることです。

8.2.31.1.2 コマンド・イベント・ハンドラの構成

ファイル・ライター・ハンドラのプロパティ・ファイルを使用して、コマンド・イベント・ハンドラの操作を構成できます。

コマンド・イベント・ハンドラは、ファイル・ライター・ハンドラと組み合せてのみ機能します。

コマンド・イベント・ハンドラの選択を有効にするには、まずgg.eventhandler.name.type=commandおよびその他のコマンド・イベント・プロパティを次のように指定してハンドラ・タイプを構成する必要があります。

表8-36 コマンド・イベント・ハンドラの構成プロパティ

プロパティ	必須/オプション	有効な値	デフォルト	説明
gg.eventhandler.name.type	必須	command	なし	Replicatで使用するコマンド・イベント・ハンドラを選択します
gg.eventhandler.name.command	必須	実行する外部プログラムまたはスクリプトの有効なパス。	なし	コマンド・イベント・ハンドラによって実行されるスクリプトまたは外部プログラム。
gg.eventhandler.name.cmdWaitMilli	オプション	ミリ秒を表す整数値。	無期限	コマンド・イベント・ハンドラは、スクリプトまたは外部プログラムでコールされたコマンドが完了するまで待機します。コマンド・イベント・ハンドラが、構成されたタイムアウト期間内にコマンドを完了できなかった場合、処理は異常終了します。
gg.eventhandler.name.multithreaded	オプション	true | false	true	trueの場合、スクリプトまたは外部プログラムに構成されているコマンドはマルチスレッド方式で実行されます。falseの場合は、単一スレッドで実行されます。
gg.eventhandler.name.commandArgumentTemplate	オプション	「コマンド引数テンプレート文字列の使用」を参照してください。	なし	コマンド・イベント・ハンドラでは、スクリプトまたは外部プログラムの実行時に入力引数としてコマンド引数テンプレート文字列を使用します。有効な引数文字列のリストについては、「コマンド引数テンプレート文字列の使用」を参照してください。

サンプル構成

gg.eventhandler.command.type=command

gg.eventhandler.command.command=<path of the script to be executed>

#gg.eventhandler.command.cmdWaitMilli=10000

gg.eventhandler.command.multithreaded=true

gg.eventhandler.command.commandArgumentTemplate=${tablename},${datafilename},${countoperations}

8.2.31.1.3 コマンド引数テンプレート文字列の使用

コマンド引数テンプレート文字列は、実行時に動的に解決されるキーワードで構成されます。コマンド引数テンプレート文字列は、commandArgumentTemplateプロパティに指定されている順序と同じ順序で引数としてスクリプトに渡されます。

コマンド引数テンプレート文字列として使用される有効なトークンは、UUID、TableName、DataFileName、DataFileDir、DataFileDirandName、Offset、Format、CountOperations、CountInserts、CountUpdates、CountDeletesおよびCountTruncatesです。テンプレート文字列が無効な場合は異常終了します。

サポートされているテンプレート文字列

${uuid}

ファイル・ライター・ハンドラは、生成されたファイルの状態を内部的に追跡するためにUUIDを割り当てます。UUIDの有用性は、トラブルシューティングのシナリオに限られることがあります。

${tableName}

個々のソース表名。たとえば、MYTABLEです。

${dataFileName}

生成されるデータ・ファイルの名前。

${dataFileDirandName}

完全パス、ファイル名およびファイル拡張子を指定したソース・ファイル名。

${offset}

データ・ファイルのオフセット(またはバイト単位のサイズ)。

${format}

ファイルの形式。たとえば、delimitedtext | json | json_row | xml | avro_row | avro_op | avro_row_ocf | avro_op_ocfです

${countOperations}

データ・ファイル内の操作の合計数。名前変更か、イベント・ハンドラで使用する必要があります。それ以外の場合、何も書き込まれていないため、ゼロ(0)になります。たとえば、1024です。

${countInserts}

データ・ファイル内の挿入操作の合計数。名前変更か、イベント・ハンドラで使用する必要があります。それ以外の場合、何も書き込まれていないため、ゼロ(0)になります。たとえば、125です。

${countUpdates}

データ・ファイル内の更新操作の合計数。名前変更か、イベント・ハンドラで使用する必要があります。それ以外の場合、何も書き込まれていないため、ゼロ(0)になります。たとえば、265です。

${countDeletes}

データ・ファイル内の削除操作の合計数。名前変更か、イベント・ハンドラで使用する必要があります。それ以外の場合、何も書き込まれていないため、ゼロ(0)になります。たとえば、11です。

${countTruncates}

データ・ファイル内の切捨て操作の合計数。名前変更か、イベント・ハンドラで使用する必要があります。それ以外の場合、何もまだ書き込まれていないため、ゼロ(0)になります。たとえば、5です。

ノート:

スクリプトまたはコマンドが正常に実行されると、コマンド・イベント・ハンドラは「コマンドは正常に終了しました。」という文および実行されたコマンドの文とともにメッセージを記録します。コマンドの実行時にエラーが発生した場合、コマンド・イベント・ハンドラはReplicatプロセスを異常終了させ、エラー・メッセージをログに記録します。

8.2.31.2 HDFSイベント・ハンドラ

HDFSイベント・ハンドラを使用して、ファイル・ライター・ハンドラによって生成されたファイルをHDFSにロードします。

このトピックでは、HDFSイベント・ハンドラの使用方法について説明します。「フラット・ファイル」を参照してください。

• 機能の詳細
  

8.2.31.2.1 機能の詳細

• ハンドラの構成
  
• HDFSイベント・ハンドラの構成
  

8.2.31.2.1.1 ハンドラの構成

HDFSイベント・ハンドラは、データ・ファイルをHDFSにアップロードできます。次の追加の構成ステップが必要です。

HDFSイベント・ハンドラの依存性と考慮事項は、HDFSハンドラと同じです。「HDFSのその他の考慮事項」を参照してください。

gg.classpathにHDFSクライアント・ライブラリが含まれていることを確認します。

HDFS core-site.xmlファイルを含むディレクトリがgg.classpathにあることを確認します。これは、core-site.xmlファイルを実行時に読み取ることができ、HDFSへの接続情報を解決できるようにしています。たとえば:

gg.classpath=/{HDFSinstallDirectory}/etc/hadoop

HDFSクラスタ上でKerberos認証が有効化されている場合は、パスワードを実行時に解決できるように、Kerberosプリンシパルとkeytabファイルの場所を構成する必要があります。

gg.eventHandler.name.kerberosPrincipal=principal
gg.eventHandler.name.kerberosKeytabFile=pathToTheKeytabFile

8.2.31.2.1.2 HDFSイベント・ハンドラの構成

プロパティ・ファイルを使用して、HDFSハンドラの操作を構成します。これらのプロパティは、Javaアダプタ・プロパティ・ファイルにあります(Replicatプロパティ・ファイルにはありません)

HDFSイベント・ハンドラの選択を有効にするには、まずgg.eventhandler.name.type=hdfsおよびその他のHDFSイベント・プロパティを次のように指定してハンドラ・タイプを構成する必要があります。

表8-37 HDFSイベント・ハンドラの構成プロパティ

プロパティ	必須/オプション	有効な値	デフォルト	説明
gg.eventhandler.name.type	必須	hdfs	なし	使用するHDFSイベント・ハンドラを選択します。
gg.eventhandler.name.pathMappingTemplate	必須	データ・ファイルを書き込むHDFSのパスを動的に生成するために使用される、解決可能なキーワードと定数を含む文字列。	なし	定数とインタレースされたキーワードを使用して、一意のパス名を実行時に動的に生成します。パス名は、通常、/ogg/data/${groupName}/${fullyQualifiedTableName}の形式に従います。テンプレート・キーワードを参照してください。
gg.eventhandler.name.fileNameMappingTemplate	オプション	実行時にHDFSファイル名を動的に生成するために使用される、解決可能なキーワードと定数を含む文字列。	なし	定数とともにインタレースされるキーワードを使用して、一意のファイル名を実行時に動的に生成します。設定しない場合、アップストリームのファイル名が使用されます。テンプレート・キーワードを参照してください。
gg.eventhandler.name.finalizeAction	オプション	none | delete	none	ファイナライズ・アクションでのファイル・ライター・ハンドラの動作を示します。 none データ・ファイルをそのままにします(アクティブな書込み接尾辞を削除します。「アクティブな書込み接尾辞について」を参照)。 delete データ・ファイルを削除します(データ・ファイルが別の形式に変換されていたり、サード・パーティ・アプリケーションにロードされている場合)。
gg.eventhandler.name.kerberosPrincipal	オプション	Kerberosプリンシパル名。	なし	HDFS Kerberos認証が有効になっている場合は、Kerberosプリンシパルに設定します。
gg.eventhandler.name.keberosKeytabFile	オプション	Kerberos keytabファイルのパス。	なし	HDFS Kerberos認証が有効になっている場合は、Kerberos keytabファイルのパスに設定します。
gg.eventhandler.name.eventHandler	オプション	子イベント・ハンドラを相互参照する一意の文字列識別子。	イベント・ハンドラは構成されない。	イベント・ハンドラを相互参照する一意の文字列識別子。イベント・ハンドラは、ファイル・ロール・イベントで呼び出されます。イベント・ハンドラは、S3へのファイルのロード、ParquetまたはORC形式への変換、HDFSへのファイルのロードなどのファイル・ロール・イベントのアクションを実行できます。

8.2.31.3 メタ列のキーワード

この付録では、メタ列のキーワードについて説明します。

メタ列機能を使用すると、生成された出力メッセージに表示するメタデータ・フィールドを選択できます。メタ列構文の形式は次のとおりです。

${keyword[fieldName].argument}

キーワードは、メタ列構文に基づいて固定されます。オプションで、大カッコの間にフィールド名を指定できます。フィールド名を指定しない場合は、デフォルトのフィールド名が使用されます。

キーワードはカンマで区切られます。メタ列の構成の例を次に示します。

gg.handler.filewriter.format.metaColumnsTemplate=${objectname[table]},${optype[op_type]},${timestamp[op_ts]},${currenttimestamp[current_ts]},${position[pos]}

一部のメタ列のキーワードには引数が必要になる場合があります。たとえば、特定のトークン値が解決されるか、特定の環境変数値が解決される場合に必要です。

${alltokens}

マップとして提供される操作のすべてのトークンで、トークン・キーはマップ内のキーでトークン値はマップ値です。

${token}

特定のOracle GoldenGateトークンの値。トークン・キーは、ピリオド(.)演算子を使用してトークンの後に続ける必要があります。たとえば:

${token.MYTOKEN}

${sys}

システム環境変数。変数名は、ピリオド(.)演算子を使用してsysの後に続ける必要があります。

${sys.MYVAR}

Oracle GoldenGate環境変数。変数名は、ピリオド(.)演算子を使用してenvの後に続ける必要があります。

${env}

Oracle GoldenGate環境変数。変数名は、ピリオド(.)演算子を使用してenvの後に続ける必要があります。たとえば:

${env.someVariable}

${javaprop}

Java JVM変数。変数名は、ピリオド(.)演算子を使用してjavapropの後に続ける必要があります。たとえば:

${javaprop.MYVAR}

${optype}

操作タイプ。これは通常、挿入の場合はI、更新の場合はU、削除の場合はD、切捨ての場合はTです。

${position}

レコードの位置。これは、ソース証跡ファイル内のレコードの場所です。20文字の文字列です。最初の10文字は、証跡ファイルの順序番号です。最後の10文字は、証跡ファイル内のレコードのオフセットまたはrbaです。

${timestamp}

レコードのタイムスタンプ。

${catalog}

カタログ名。

${schema}

スキーマ名。

${table}

表名。

${objectname}

完全修飾の表名。

${csn}

ソースのコミット順序番号

${xid}

ソース・トランザクションID。

${currenttimestamp}

現在のタイムスタンプ。

${currenttimestampiso8601}

ISO 8601形式の現在のタイムスタンプ。

${opseqno}

トランザクション内のレコード順序番号。

${timestampmicro}

レコードのタイムスタンプ(マイクロ秒/エポック後)。

${currenttimestampmicro}

現在のタイムスタンプ(マイクロ秒/エポック後)。

${txind}

ソース証跡ファイルのトランザクション・インジケータです。トランザクションの値は、最初の操作の場合はB、中間の操作の場合はM、最後の操作の場合はE、操作1つのみの場合はWです。フィルタリング操作または調整適用を使用すると、このフィールドの有用性が無効になります。

${primarykeycolumns}

主キー列名のリストを含むフィールドを挿入する場合に使用します。

${primarykeys}

主キー値間がアンダースコア(_)で区切られている主キー列値のリストをフィールドを注入するために使用します。

使用方法: ${primarykeys[fieldName]}

例: ${primarykeys[JMSXGroupID]}

${static}

静的値を含むフィールドを出力に挿入する場合に使用します。必要な値は引数です。必要な値がabcである場合の構文は、${static.abc}または${static[FieldName].abc}です。

${seqno}

指定された操作に対し、ソース証跡ファイルの順序番号を含むフィールドを挿入するために使用します。

${rba}

指定された操作に対し、ソース証跡ファイル内の操作のrba (オフセット)を含むフィールドを挿入するために使用します。

${metadatachanged}

ソース表定義のメタデータ変更後の最初の操作でtrueに設定されるブール・フィールド。

${groupname}

値がReplicatプロセスのグループ名である文字列フィールド。グループ名は、ggsciまたはOracle GoldenGate Microservices UIで参照されるため、実質的にReplicatプロセス名です。

${positionnumber}

数値として表された位置。

${seqnonumber}

数値として表された証跡順序番号。

${rbanumber}

数値として表された証跡RBA。

${opseqno}

数値として表された操作順序番号。

8.2.31.4 メタデータ・プロバイダ

メタデータ・プロバイダは、Replicatパラメータ・ファイルを使用してソースからターゲットに複製できます。

この章では、メタデータ・プロバイダの使用方法について説明します。

• メタデータ・プロバイダについて
  
• Avroメタデータ・プロバイダ
  Avroメタデータ・プロバイダは、Avroスキーマ・ファイルから表メタデータを取得する際に使用します。COLMAPを使用してReplicatでマップされる表ごとに、Avroスキーマからメタデータが取得されます。取得されたメタデータは、Replicatによって列マッピングに使用されます。
• Java Database Connectivityメタデータ・プロバイダ
  
• Hiveメタデータ・プロバイダ
  Hiveメタデータ・プロバイダは、Hiveメタストアから表メタデータを取得する際に使用します。メタデータは、Replicatプロパティ・ファイルでマップされているターゲット表ごとに、COLMAPパラメータを使用して、Hiveから取得されます。取得されるターゲット・メタデータは、列マッピング機能のためにReplicatで使用されます。
• Google BigQueryメタデータ・プロバイダ
  Googleメタデータ・プロバイダは、Google Query Jobを使用して、Google BigQuery表からメタデータ・スキーマ情報をキャプチャします。BigQueryがメタデータをフェッチするために、ターゲット上にすでに表が作成されている必要があります。

8.2.31.4.1 メタデータ・プロバイダについて

メタデータ・プロバイダは、ハンドラがReplicatプロセスで実行されるように構成されている場合にのみ機能します。

Replicatプロセスは、Replicat構成ファイルの構文を使用して、ソース表からターゲット表に、およびソース列からターゲット列にマッピングします。ソース・メタデータ定義は、Oracle GoldenGate証跡ファイルに含まれています(または、12.2以降のリリースのOracle GoldenGateではソース定義ファイルによって)。レプリケーション・ターゲットがデータベースの場合、Replicatプロセスはターゲット・メタデータ定義をターゲット・データベースから取得します。しかしながら、これは一般的に、Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)アプリケーションにデータをプッシュするときやJava配信中には問題となります。通常、GG for DAAアプリケーションではターゲット・メタデータは提供されないため、Replicatのマッピングは不可能です。この短所に対処するのが、メタデータ・プロバイダです。メタデータ・プロバイダを使用すると、AvroまたはHiveを使用してターゲット・メタデータを定義でき、ソース表からターゲット表へ、およびソース列からターゲット列へのReplicatマッピングが可能になります。

メタデータ・プロバイダの使用はオプションであり、有効にするにはJavaアダプタ・プロパティ・ファイルでgg.mdp.typeプロパティを指定します。ソースのOracle GoldenGate証跡ファイルに含まれるメタデータを出力に利用できる場合、メタデータ・プロバイダは使用しないでください。メタデータ・プロバイダは、次の場合に使用する必要があります。

• ソース表名を、一致しないターゲット表名にマップする必要があります。

• ソース列名を、一致しないターゲット列名にマップする必要があります。

• ソース証跡ファイルの特定の列を含め、それ以外の列を除外する必要があります。

Replicatマッピングの制限は、Replicat構成ファイルに定義されているマッピングが静的であるということです。Oracle GoldenGateには、ソースとしてOracleデータベースを使用するとき、DDL伝播の機能があります。メタデータ・プロバイダとReplicatマッピングを使用する際には、スキーマ展開の適切な処理が問題になることがあります。スキーマ展開のユースケースを考慮したうえで、必要な変更のためにメタデータ・プロバイダとReplicatマッピング構文をどのように更新するかを計画します。

COLMAPを使用してReplicatでマップされる表ごとに、構成されたメタデータ・プロバイダからメタデータが取得され、そのメタデータがReplicatによって列マッピングに使用されます。

HiveおよびAvroのメタデータ・プロバイダのみがサポートされているため、いずれか一方を選択して、メタデータ・プロバイダ実装で使用する必要があります。

シナリオ - いつメタデータ・プロバイダを使用するか

1. 次のシナリオでは、メタデータ・プロバイダの構成は必要ありません。

   GGというソース・スキーマが、GGADPというターゲット・スキーマにマップされるマッピング。*

   GG.TCUSTMERというスキーマが、GGADP.TCUSTMER_NEWという表名にマップされるスキーマと表名のマッピング

   MAP GG.*, TARGET GGADP.*;
   (OR)
   MAP GG.TCUSTMER, TARGET GG_ADP.TCUSTMER_NEW;
   

2. 次のシナリオでは、メタデータ・プロバイダの構成が必要です。

   ソース列名がターゲット列名と一致しないマッピング。たとえば、ソース列CUST_CODEは、ターゲット列CUST_CODE_NEWにマップされます。

   MAP GG.TCUSTMER, TARGET GG_ADP.TCUSTMER_NEW, COLMAP(USEDEFAULTS, CUST_CODE_NEW=CUST_CODE, CITY2=CITY);
   

8.2.31.4.2 Avroメタデータ・プロバイダ

Avroメタデータ・プロバイダは、Avroスキーマ・ファイルから表メタデータを取得する際に使用します。COLMAPを使用してReplicatでマップされる表ごとに、Avroスキーマからメタデータが取得されます。取得されたメタデータは、Replicatによって列マッピングに使用されます。

• 詳細な機能
  
• 実行時の前提条件
  
• クラスパス構成
  
• Avroメタデータ・プロバイダの構成
  
• サンプル構成の確認
  
• メタデータ変更イベント
  
• 制限事項
  
• トラブルシューティング
  

8.2.31.4.2.1 詳細な機能

Avroメタデータ・プロバイダは、Avroスキーマ定義ファイルを使用してメタデータを使用します。AvroスキーマはJSONを使用して定義されます。process_name. prmファイルでマップされる表ごとに、対応するAvroスキーマ定義ファイルを作成する必要があります。

Avroメタデータ・プロバイダ・スキーマ定義の構文

{"namespace": "[$catalogname.]$schemaname",
"type": "record",
"name": "$tablename",
"fields": [
     {"name": "$col1", "type": "$datatype"},
     {"name": "$col2 ",  "type": "$datatype ", "primary_key":true}, 
     {"name": "$col3", "type": "$datatype ", "primary_key":true}, 
     {"name": "$col4", "type": ["$datatype","null"]}   
   ]
}
 
namespace            - name of catalog/schema being mapped
name                 - name of the table being mapped
fields.name          - array of column names
fields.type          - datatype of the column
fields.primary_key   - indicates the column is part of primary key.

Representing nullable and not nullable columns:

"type":"$datatype" - indicates the column is not nullable, where "$datatype" is the actual datatype.
"type": ["$datatype","null"] - indicates the column is nullable, where "$datatype" is the actual datatype

Avroメタデータ・プロバイダによってアクセスされるスキーマ・ファイルの名前は、次の形式にする必要があります。

[$catalogname.]$schemaname.$tablename.mdp.avsc
 
$catalogname    - name of the catalog if exists
$schemaname   - name of the schema
$tablename        - name of the table
.mdp.avsc           -  constant, which should be appended always

サポートされているAvroプリミティブ・データ型

• boolean
• bytes
• double
• float
• int
• long
• string

https://avro.apache.org/docs/1.7.5/spec.html#schema_primitiveを参照してください。

サポートされているAvro論理データ型

• decimal
• timestamp

小数論理型のAvroの例

{"name":"DECIMALFIELD","type": 
{"type":"bytes","logicalType":"decimal","precision":15,"scale":5}}

タイムスタンプ論理型の例

{"name":"TIMESTAMPFIELD","type": 
{"type":"long","logicalType":"timestamp-micros"}}

8.2.31.4.2.2 実行時の前提条件

Replicatプロセスを開始する前に、Replicatのパラメータ・ファイルでマップされるすべての表のAvroスキーマ定義を作成します。

8.2.31.4.2.3 クラスパス構成

Avroメタデータ・プロバイダに、追加のクラスパス設定は必要ありません。

8.2.31.4.2.4 Avroメタデータ・プロバイダの構成

プロパティ	必須/オプション	有効な値	デフォルト	説明
gg.mdp.type	必須	avro	-	Avroメタデータ・プロバイダを選択します
gg.mdp.schemaFilesPath	必須	例:/home/user/ggadp/avroschema/	-	Avroスキーマ・ファイルのディレクトリのパス
gg.mdp.charset	オプション	有効な文字セット	UTF-8	文字データ型で列の文字セットを指定します。ソース・データを証跡ファイルから正しいターゲット文字セットに変換する場合に使用します。
gg.mdp.nationalCharset	オプション	有効な文字セット	UTF-8	文字データ型で列の文字セットを指定します。ソース・データを証跡ファイルから正しいターゲット文字セットに変換する場合に使用します。 例: OracleデータベースでNCHARやNVARCHARなどの列の文字セットを指定する場合に使用します。

8.2.31.4.2.5 サンプル構成の確認

Avroメタデータ・プロバイダを構成する例を次に示します。次の表を含むソースを検討します。

TABLE GG.TCUSTMER {
     CUST_CODE VARCHAR(4) PRIMARY KEY,
     NAME VARCHAR(100),
     CITY VARCHAR(200),
     STATE VARCHAR(200)
}

この表は、ソースの(CUST_CODE (GG.TCUSTMER)をターゲットのCUST_CODE2 (GG_AVRO.TCUSTMER_AVRO)に、およびソースの列CITY(GG.TCUSTMER)をターゲットのCITY2 (GG_AVRO.TCUSTMER_AVRO)にマップします。したがって、process_name. prmファイルでのマッピングは、次のとおりです。

MAP GG.TCUSTMER, TARGET GG_AVRO.TCUSTMER_AVRO, COLMAP(USEDEFAULTS, CUST_CODE2=CUST_CODE, CITY2=CITY);
 

この例のマッピング定義は、次のとおりです。

• ソース・スキーマGGは、ターゲット・スキーマGG_AVROにマップされる。

• ソース列CUST_CODEは、ターゲット列CUST_CODE2にマップされる

• ソース列CITYは、ターゲット列CITY2にマップされる

• USEDEFAULTSには、列名の残りがソースとターゲットで同じことを指定します(NAME列とSTATE列)。

この例では、次のAvroスキーマ定義ファイルを使用します。

ファイル・パス: /home/ggadp/avromdpGG_AVRO.TCUSTMER_AVRO.mdp.avsc

{"namespace": "GG_AVRO",
"type": "record",
"name": "TCUSTMER_AVRO",
"fields": [
     {"name": "NAME", "type": "string"},
    {"name": "CUST_CODE2",  "type": "string", "primary_key":true},
     {"name": "CITY2", "type": "string"},
     {"name": "STATE", "type": ["string","null"]}
]
}

Javaアダプタ・プロパティ・ファイルの構成には、次の指定が含まれます。

gg.mdp.type = avro
gg.mdp.schemaFilesPath = /home/ggadp/avromdp

次のサンプル出力では、区切り文字としてセミコロンを使用する区切りテキスト・フォーマッタが使用されています。

I;GG_AVRO.TCUSTMER_AVRO;2013-06-02 22:14:36.000000;NAME;BG SOFTWARE CO;CUST_CODE2;WILL;CITY2;SEATTLE;STATE;WA

Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)では、サンプルのReplicat構成ファイル、サンプルのJavaアダプタ・プロパティ・ファイルおよびサンプルのAvroスキーマが次の場所に含まれています:

GoldenGate_install_directory/AdapterExamples/big-data/metadata_provider/avro

8.2.31.4.2.6 メタデータ変更イベント

DDLがソース・データベース表で変更された場合は、Avroスキーマ定義と、Replicat構成ファイルでのマッピングを変更する必要がある場合があります。また、メタデータ変更イベントがあった場合には、Replicatプロセスを停止または一時停止することもあります。Replicatプロセスを停止するには、Replicat構成ファイル(process_name. prm)に次の行を追加します。

DDL INCLUDE ALL, EVENTACTIONS (ABORT)

また、Replicatプロセスを一時停止するには、レプリケーション構成ファイルに次の行を追加します。

DDL INCLUDE ALL, EVENTACTIONS (SUSPEND)

8.2.31.4.2.7 制限事項

Avroのbyteデータ型は、主キーとして使用できません。

Replicat構成ファイルに定義されているソースからターゲットへのマッピングは静的です。Oracle GoldenGate 12.2以降では、Oracleデータベースがレプリケーション・ソースの場合に、DDL伝播とソース・スキーマ展開をサポートします。DDL伝播とソース・スキーマ展開を使用する場合、ソース・メタデータの変更をシームレスに処理できなくなります。

8.2.31.4.2.8 トラブルシューティング

このトピックでは、次の問題をトラブルシューティングする方法について説明します。

• 無効なスキーマ・ファイルの場所
  
• 無効なスキーマ・ファイル名
  
• スキーマ・ファイルでの無効なネームスペース
  
• スキーマ・ファイルでの無効な表名
  

8.2.31.4.2.8.1 無効なスキーマ・ファイルの場所

gg.mdp.schemaFilesPath構成プロパティで指定するAvroスキーマ・ファイル・ディレクトリは、有効なディレクトリである必要があります。パスが有効でない場合、次の例外が発生します。

oracle.goldengate.util.ConfigException: Error initializing Avro metadata provider
Specified schema location does not exist. {/path/to/schema/files/dir}

8.2.31.4.2.8.2 無効なスキーマ・ファイル名

process_name.prmファイルでマップされる表ごとに、gg.mdp.schemaFilesPathで指定されたディレクトリに対応するAvroスキーマ・ファイルを作成する必要があります。

たとえば、次のシナリオを考えてみます。

マッピング:

MAP GG.TCUSTMER, TARGET GG_AVRO.TCUSTMER_AVRO, COLMAP(USEDEFAULTS, cust_code2=cust_code, CITY2 = CITY);
 

プロパティ:

gg.mdp.schemaFilesPath=/home/usr/avro/

このシナリオでは、/home/usr/avro/ディレクトリにGG_AVRO.TCUSTMER_AVRO.mdp.avscというファイルを作成する必要があります。

/home/usr/avro/GG_AVRO.TCUSTMER_AVRO.mdp.avscファイルを作成しないと、次の例外が発生します。

java.io.FileNotFoundException: /home/usr/avro/GG_AVRO.TCUSTMER_AVRO.mdp.avsc

8.2.31.4.2.8.3 スキーマ・ファイルでの無効なネームスペース

Replicatマッピングで指定するターゲット・スキーマ名は、Avroスキーマ定義ファイルのネームスペースと同じである必要があります。

たとえば、次のシナリオを考えてみます。

マッピング:

MAP GG.TCUSTMER, TARGET GG_AVRO.TCUSTMER_AVRO, COLMAP(USEDEFAULTS, cust_code2 = cust_code, CITY2 = CITY);
 
Avro Schema Definition:
 
{
"namespace": "GG_AVRO",
..
}

このシナリオでは、Replicatが次の例外で異常終了します。

Unable to retrieve table matadata. Table : GG_AVRO.TCUSTMER_AVRO
Mapped [catalogname.]schemaname (GG_AVRO) does not match with the schema namespace {schema namespace}

8.2.31.4.2.8.4 スキーマ・ファイルでの無効な表名

Replicatマッピングで指定するターゲット表名は、Avroスキーマ定義ファイルでの名前と同じである必要があります。

たとえば、次のシナリオを考えてみます。

マッピング:

MAP GG.TCUSTMER, TARGET GG_AVRO.TCUSTMER_AVRO, COLMAP(USEDEFAULTS, cust_code2 = cust_code, CITY2 = CITY);

Avroスキーマ定義:

{
"namespace": "GG_AVRO",
"name": "TCUSTMER_AVRO",
..
}

このシナリオでは、Replicatマッピングで指定したターゲット表名がAvroスキーマ名と一致しない場合、REPLICATが次の例外で異常終了します。

Unable to retrieve table matadata. Table : GG_AVRO.TCUSTMER_AVRO
Mapped table name (TCUSTMER_AVRO) does not match with the schema table name {table name}

8.2.31.4.3 Java Database Connectivityメタデータ・プロバイダ

Java Database Connectivity (JDBC)メタデータ・プロバイダは、JDBC接続をサポートするターゲット・データベースから表メタデータを取得する際に使用し、データベース・スキーマがあります。JDBCメタデータ・プロバイダは、RDBMSであるターゲット・データベースの優先メタデータ・プロバイダとなりますが、他の様々な非RDBMSターゲットもJDBCドライバを提供します。

トピック:

• JDBCの詳細な機能
  
• Javaクラスパス
  
• JDBCメタデータ・プロバイダの構成
  
• サンプル構成の確認
  

8.2.31.4.3.1 JDBCの詳細な機能

JDBCメタデータ・プロバイダは、ターゲット・データベースとともに提供されるJDBCドライバを使用します。DBCドライバは、Replicatプロパティ・ファイルでマップされるターゲット表ごとに、メタデータを取得します。Replicatプロセスは、取得されたターゲット・メタデータを使用して列をマップします。

Replicatパラメータ・ファイルでREPERRORプロパティを構成すると、JDBCハンドラでこの機能を有効化できます。また、次のようにJDBCハンドラ・プロパティ・ファイルでRDBMS JDBCターゲットに固有のエラー・コードを定義する必要があります。

表8-38 JDBC REPERRORのコード

プロパティ	値	必須
gg.error.duplicateErrorCodes	重複エラーを示すエラー・コードのカンマ区切りの整数値	いいえ
gg.error.notFoundErrorCodes	Not Foundエラーを示すエラー・コードのカンマ区切りの整数値	いいえ
gg.error.deadlockErrorCodes	デッドロック・エラーを示すエラー・コードのカンマ区切りの整数値	いいえ

たとえば:

#ErrorCode
gg.error.duplicateErrorCodes=1062,1088,1092,1291,1330,1331,1332,1333
gg.error.notFoundErrorCodes=0
gg.error.deadlockErrorCodes=1213

様々なJDBCタイプをデータベース固有のSQLタイプにマップする方法を理解するには、https://docs.oracle.com/javase/6/docs/technotes/guides/jdbc/getstart/mapping.html#table1を参照してください。

8.2.31.4.3.2 Javaクラスパス

gg.classpathプロパティを使用して、JDBC Java Driverの場所をハンドラのクラスパスに含める必要があります。

たとえば、MySQLデータベースの構成は次のようになります。

gg.classpath= /path/to/jdbc/driver/jar/mysql-connector-java-5.1.39-bin.jar

8.2.31.4.3.3 JDBCメタデータ・プロバイダの構成

JDBCメタデータ・プロバイダの構成可能な値は次のとおりです。これらのプロパティは、Javaアダプタ・プロパティ・ファイルにあります(Replicatプロパティ・ファイルにはありません)

表8-39 JDBCメタデータ・プロバイダのプロパティ

プロパティ	必須/オプション	有効な値	デフォルト	説明
gg.mdp.type	必須	jdbc	なし	コマンド・プロンプトでjdbcと入力すると、JDBCメタデータ・プロバイダの使用がアクティブになります。
gg.mdp.ConnectionUrl	必須	jdbc:subprotocol:subname	なし	ターゲット・データベースのJDBC URL。
gg.mdp.DriverClassName	必須	JDBCドライバのJavaクラス名	なし	JDBCドライバの完全修飾のJavaクラス名。
gg.mdp.userName	オプション	有効なユーザー名の文字列。	なし	JDBC接続のユーザー名。または、ConnectionURLプロパティを使用してユーザー名を指定できます。
gg.mdp.password	オプション	有効なパスワードの文字列	なし	JDBC接続のパスワード。または、ConnectionURLプロパティを使用してパスワードを指定できます。

8.2.31.4.3.4 サンプル構成の確認

MySQLドライバの構成

gg.mdp.type=jdbc
gg.mdp.ConnectionUrl=jdbc:oracle:thin:@myhost:1521:orcl
gg.mdp.DriverClassName=oracle.jdbc.driver.OracleDriver
gg.mdp.UserName=username
gg.mdp.Password=password

Netezzaドライバの構成

gg.mdp.type=jdbc
gg.mdp.ConnectionUrl=jdbc:netezza://hostname:port/databaseName
gg.mdp.DriverClassName=org.netezza.Driver
gg.mdp.UserName=username
gg.mdp.Password=password

Oracle OCIドライバの構成

ggg.mdp.type=jdbc
gg.mdp.ConnectionUrl=jdbc:oracle:oci:@myhost:1521:orcl
gg.mdp.DriverClassName=oracle.jdbc.driver.OracleDriver
gg.mdp.UserName=username
gg.mdp.Password=password

Oracle Teradataドライバの構成

gg.mdp.type=jdbc
gg.mdp.ConnectionUrl=jdbc:teradata://10.111.11.111/USER=username,PASSWORD=password
gg.mdp.DriverClassName=com.teradata.jdbc.TeraDriver
gg.mdp.UserName=username
gg.mdp.Password=password

Oracle Thinドライバの構成

gg.mdp.type=jdbc
gg.mdp.ConnectionUrl=jdbc:mysql://localhost/databaseName?user=username&password=password
gg.mdp.DriverClassName=com.mysql.jdbc.Driver
gg.mdp.UserName=username
gg.mdp.Password=password

Redshiftドライバの構成

gg.mdp.type=jdbc
gg.mdp.ConnectionUrl=jdbc:redshift://hostname:port/databaseName
gg.mdp.DriverClassName=com.amazon.redshift.jdbc42.Driver
gg.mdp.UserName=username
gg.mdp.Password=password

8.2.31.4.4 Hiveメタデータ・プロバイダ

Hiveメタデータ・プロバイダは、Hiveメタストアから表メタデータを取得する際に使用します。メタデータは、Replicatプロパティ・ファイルでマップされているターゲット表ごとに、COLMAPパラメータを使用して、Hiveから取得されます。取得されるターゲット・メタデータは、列マッピング機能のためにReplicatで使用されます。

• 詳細な機能
  
• リモート・メタストア・データベースを使用するHiveの構成
  
• クラスパス構成
  
• Hiveメタデータ・プロバイダの構成プロパティ
  
• サンプル構成の確認
  
• セキュリティ
  
• メタデータ変更イベント
  
• 制限事項
  
• その他の考慮事項
  
• トラブルシューティング
  

8.2.31.4.4.1 詳細な機能

Hiveメタデータ・プロバイダは、Hive JDBCとHCatalogの両方のインタフェースを使用して、Hiveメタストアからメタデータを取得します。process_name.prmファイルでマップされる表ごとに、対応する表がHiveに作成されます。

デフォルトのHive構成では、埋込みのローカルのメタストアであるDerbyデータベースが起動します。Apache Derbyは、埋込みデータベースとして設計されているため、単一の接続のみ可能です。このDerbyデータベースの制限は、Hiveメタデータ・プロバイダを使用する場合は機能できないことを意味します。この制限を回避するには、リモート・メタストア・データベースを使用してHiveを構成する必要があります。リモート・メタストア・データベースを使用してHiveを構成する方法の詳細は、https://cwiki.apache.org/confluence/display/Hive/AdminManual+Metastore+Administrationを参照してください。

Hiveは、主キーのセマンティクスをサポートしていないため、Hiveメタストアから取得されるメタデータには、主キー定義が含まれません。Hiveメタデータ・プロバイダを使用する場合は、ReplicatのKEYCOLSパラメータを使用して主キーを定義します。

KEYCOLS

ターゲット・スキーマで主キーを定義するには、KEYCOLSパラメータを使用する必要があります。Oracle GoldenGate HBaseハンドラには、主キーが必要です。したがって、HBaseをターゲットとしてReplicatマッピングを使用する場合は、ターゲット・スキーマで主キーを設定する必要があります。

Avroフォーマッタの出力には、プライマリ列名を保持する配列フィールドがあります。AvroフォーマッタでReplicatマッピングを使用する場合は、KEYCOLSを使用して主キー列を指定することを検討してください。

KEYCOLSの構成例は、サンプル構成の確認を参照してください。

サポートされているHiveデータ型

• BIGINT

• BINARY

• BOOLEAN

• CHAR

• DATE

• DECIMAL

• DOUBLE

• FLOAT

• INT

• SMALLINT

• STRING

• TIMESTAMP

• TINYINT

• VARCHAR

https://cwiki.apache.org/confluence/display/Hive/LanguageManual+Typesを参照してください。

8.2.31.4.4.2 リモート・メタストア・データベースを使用するHiveの構成

リモートHiveメタストアの構成に使用できるサポート対象のデータベースのリストは、https://cwiki.apache.org/confluence/display/Hive/AdminManual+MetastoreAdmin#AdminManualMetastoreAdmin-SupportedBackendDatabasesforMetastoreにあります。

次の例では、MySQLデータベースがHive構成ファイル${HIVE_HOME}/conf/hive-site.xmlのプロパティを使用してHiveメタストアとして構成されることを示しています。

ノート:

ConnectionURLと、この例で使用しているドライバ・クラスは、MySQLに固有の値です。MySQL以外のデータベースを使用する場合は、構成に応じて値を変更します。

<property>
         <name>javax.jdo.option.ConnectionURL</name>	
         <value>jdbc:mysql://MYSQL_DB_IP:MYSQL_DB_PORT/DB_NAME?createDatabaseIfNotExist=false</value>
 </property>
 
 <property>
        <name>javax.jdo.option.ConnectionDriverName</name>
        <value>com.mysql.jdbc.Driver</value>
 </property>
 
 <property>
          <name>javax.jdo.option.ConnectionUserName</name>
     <value>MYSQL_CONNECTION_USERNAME</value>
 </property>
 
 <property>
         <name>javax.jdo.option.ConnectionPassword</name>
         <value>MYSQL_CONNECTION_PASSWORD</value>
 </property>

リモート・メタストア用にhive-site.xmlファイルで構成するパラメータのリストを確認するには、https://cwiki.apache.org/confluence/display/Hive/AdminManual+MetastoreAdmin#AdminManualMetastoreAdmin-RemoteMetastoreDatabaseを参照してください。

ノート:

HiveのクラスパスにMySQL JDBCコネクタJARを追加するには、次のステップを実行します。

1. HIVE_HOME/lib/ディレクトリ内。DB_NAMEは、MySQLで作成されるデータベースの有効な名前に置き換えてください。

2. Hiveサーバーを起動します:

   HIVE_HOME/bin/hiveserver2/bin/hiveserver2

3. Hiveリモート・メタストア・サーバーを起動します。

   HIVE_HOME/bin/hive --service metastore

8.2.31.4.4.3 クラスパス構成

Hiveメタデータ・プロバイダをHiveに接続するには、gg.classpath変数でhive-site.xmlファイルと、HiveおよびHDFSクライアントjarを構成する必要があります。クライアントJARは、Hiveメタデータ・プロバイダが接続するHiveのバージョンと一致する必要があります。

たとえば、hive-site.xmlファイルが/home/user/oggadp/dirprmディレクトリに作成される場合、gg.classpathエントリはgg.classpath=/home/user/oggadp/dirprm/です

1. 次のプロパティを含むhive-site.xmlファイルを作成します。

   <configuration>
   <!-- Mandatory Property --> 
   <property>
   <name>hive.metastore.uris</name>
   <value>thrift://HIVE_SERVER_HOST_IP:9083</value>
   <property>
    
   <!-- Optional Property. Default value is 5 -->
   <property>
   <name>hive.metastore.connect.retries</name>
   <value>3</value>
   </property>
    
   <!-- Optional Property. Default value is 1 -->
   <property>
   <name>hive.metastore.client.connect.retry.delay</name>
   <value>10</value>
   </property>
    
   <!-- Optional Property. Default value is 600 seconds -->
   <property>
   <name>hive.metastore.client.socket.timeout</name>
   <value>50</value>
   </property>
   
    </configuration>

2. デフォルトでは、次のディレクトリにHiveおよびHDFSクライアントjarが含まれています。

   HIVE_HOME/hcatalog/share/hcatalog/*
   HIVE_HOME/lib/*
   HIVE_HOME/hcatalog/share/webhcat/java-client/*
   HADOOP_HOME/share/hadoop/common/*
   HADOOP_HOME/share/hadoop/common/lib/*
   HADOOP_HOME/share/hadoop/mapreduce/*
   

   gg.classpathを、ステップ1で示したとおり正確に構成します。hive-site.xmlファイルのパスは、ワイルドカードが付加されていないパスにしてください。hive-site.xmlファイルのパスにワイルドカード(*)を含めると、配置されません。依存関係JARのパスには、そのディレクトリにあるJARファイルがすべて関連するクラスパスに含まれるように、ワイルドカード(*)を含める必要があります。*.jarは使用しないでください。

8.2.31.4.4.4 Hiveメタデータ・プロバイダの構成プロパティ

プロパティ	必須/オプション	有効な値	デフォルト	説明
gg.mdp.type	必須	hive	-	Hiveメタデータ・プロバイダを選択します
gg.mdp.connectionUrl	必須	Kerberos認証を使用せずにフォーマット: jdbc:hive2://HIVE_SERVER_IP:HIVE_JDBC_PORT/HIVE_DB Kerberos認証を使用してフォーマット: jdbc:hive2://HIVE_SERVER_IP:HIVE_JDBC_PORT/HIVE_DB; principal=user/[e-mail]	-	HiveサーバーのJDBC接続URL
gg.mdp.driverClassName	必須	org.apache.hive.jdbc.HiveDriver	-	完全修飾のHive JDBCドライバ・クラス名
gg.mdp.userName	オプション	有効なユーザー名	""	Hiveデータベースに接続するためのユーザー名。Kerberos認証を使用する場合、userNameプロパティは必要ありません。接続URLでは、connectionUrlプロパティの有効な値で指定されているKerberosプリンシパルを指定する必要があります。
gg.mdp.password	オプション	有効なパスワード	""	Hiveデータベースに接続するためのパスワード
gg.mdp.charset	オプション	有効な文字セット	UTF-8	文字データ型を含む列の文字セット。ソース・データを証跡ファイルから正しいターゲット文字セットに変換する場合に使用します。
gg.mdp.nationalCharset	オプション	有効な文字セット	UTF-8	各国語文字データ型を含む列の文字セット。ソース・データを証跡ファイルから正しいターゲット文字セットに変換する場合に使用します。 たとえば、このプロパティは、OracleデータベースでNCHARやNVARCHARなどの列の文字セットを指定できます。
gg.mdp.authType	オプション	Kerberos	なし	HiveへのKerberos認証を指定できます。
gg.mdp.kerberosKeytabFile	オプション(authType=kerberosの場合は必須)	Kerberosキータブ・ファイルの相対パスまたは絶対パス。	-	keytabファイルを使用すると、Hiveがパスワードにアクセスし、Kerberosセキュリティに対してkinit操作を実行できます。
gg.mdp.kerberosPrincipal	オプション(authType=kerberosの場合は必須)	有効なKerberosプリンシパル名(user/[e-mail])	-	Kerberos認証で用いるKerberosプリンシパル名。

8.2.31.4.4.5 サンプル構成の確認

Hiveメタデータ・プロバイダを構成する例を次に示します。次の表でソースを検討してください。

TABLE GG.TCUSTMER {
     CUST_CODE VARCHAR(4)   PRIMARY KEY,
     NAME VARCHAR(100),
     CITY VARCHAR(200),
     STATE VARCHAR(200)}

この例は、ソースの列CUST_CODE (GG.TCUSTMER)をターゲットのCUST_CODE2 (GG_HIVE.TCUSTMER_HIVE)に、ソースの列CITY (GG.TCUSTMER)をターゲットのCITY2 (GG_HIVE.TCUSTMER_HIVE)にマップします。

process_name. prmファイルのマッピング構成には、次の構成が含まれています。

MAP GG.TCUSTMER, TARGET GG_HIVE.TCUSTMER_HIVE, COLMAP(USEDEFAULTS, CUST_CODE2=CUST_CODE, CITY2=CITY) KEYCOLS(CUST_CODE2); 

この例の詳細は次のとおりです:

• ソース・スキーマGGは、ターゲット・スキーマGG_HIVEにマップされます。

• ソース列CUST_CODEは、ターゲット列CUST_CODE2にマップされます。

• ソース列CITYは、ターゲット列CITY2にマップされます。

• USEDEFAULTSには、列名の残りがソースとターゲットで同じであることを指定します(NAME列とSTATE列)。

• KEYCOLSには、CUST_CODE2を主キーとして扱う必要があることを指定します。

HiveのDDLでは主キーを指定できないため、KEYCOLSパラメータを使用して主キーを指定します。

ノート:

任意のスキーマ名を選択でき、gg_hive schema名には制限されません。Hiveスキーマは、既存のものでも新規作成してもかまいません。これには、Javaアダプタ・プロパティ・ファイルで接続URL (gg.mdp.connectionUrl)を、Replicat.prmファイルでマッピング構成を、それぞれ変更します。スキーマ名が変更されたら、接続URL (gg.mdp.connectionUrl)と、Replicat.prmファイルのマッピングを更新します。

Hiveにこの例のスキーマおよび表を作成するには、次のコマンドを使用します。Hiveにこの例のスキーマおよび表を作成するには、次のコマンドを使用します。Hive CLIを起動するには、次のコマンドを使用します。

HIVE_HOME/bin/hive

GG_HIVEスキーマをHiveに作成するには、次のコマンドを使用します。

hive> create schema gg_hive;
OK
Time taken: 0.02 seconds

TCUSTMER_HIVE表をGG_HIVEデータベースに作成するには、次のコマンドを使用します。

hive> CREATE EXTERNAL TABLE `TCUSTMER_HIVE`(
    >   "CUST_CODE2" VARCHAR(4),
    >   "NAME" VARCHAR(30),
    >   "CITY2" VARCHAR(20),
    >   "STATE" STRING);
OK
Time taken: 0.056 seconds

次のような方法で.propertiesファイルを構成します。

gg.mdp.type=hive
gg.mdp.connectionUrl=jdbc:hive2://HIVE_SERVER_IP:10000/gg_hive
gg.mdp.driverClassName=org.apache.hive.jdbc.HiveDriver

次のサンプル出力では、区切り文字としてカンマを使用する区切りテキスト・フォーマッタが使用されています。

I;GG_HIVE.TCUSTMER_HIVE;2015-10-07T04:50:47.519000;cust_code2;WILL;name;BG SOFTWARE CO;city2;SEATTLE;state;WA

サンプルのReplicat構成ファイル、Javaアダプタ・プロパティ・ファイル、およびHive表作成SQLスクリプトのサンプルは、インストール環境の次の場所に含まれています。

GoldenGate_install_directory/AdapterExamples/big-data/metadata_provider/hive

8.2.31.4.4.6 セキュリティ

Hiveサーバーは、Kerberos認証を使用して保護できます。Hiveサーバーの保護方法の詳細は、特定のHiveリリースのHiveのドキュメントを参照してください。Hiveメタデータ・プロバイダは、Kerberosで保護されたHiveサーバーに接続できます。

HDFS core-site.xmlファイルおよびhive-site.xmlファイルのパスは、ハンドラのクラスパスに存在することを確認してください。

core-site.xmlファイルの次のプロパティを有効にします。

<property>
<name>hadoop.security.authentication</name>
<value>kerberos</value> 
</property>
 
<property> 
<name>hadoop.security.authorization</name> 
<value>true</value> 
</property>

hive-site.xmlファイルの次のプロパティを有効にします。

<property>
<name>hive.metastore.sasl.enabled</name>
<value>true</value>
</property>
 
<property>
<name>hive.metastore.kerberos.keytab.file</name>
<value>/path/to/keytab</value> <!-- Change this value -->
</property>
 
<property>
<name>hive.metastore.kerberos.principal</name>
<value>Kerberos Principal</value> <!-- Change this value -->
</property>
 
<property>
   <name>hive.server2.authentication</name>
    <value>KERBEROS</value>
</property>
 
<property>
   <name>hive.server2.authentication.kerberos.principal</name>
    <value>Kerberos Principal</value> <!-- Change this value -->
</property>
 
<property>
    <name>hive.server2.authentication.kerberos.keytab</name>
    <value>/path/to/keytab</value> <!-- Change this value -->
</property>

8.2.31.4.4.7 メタデータ変更イベント

ソース・データベース表が変更された場合は、Hiveメタストアの表を手動で更新、変更または作成する必要があります。メタデータ変更イベントが発生した場合に、Replicatプロセスを終了または一時停止することもあります。Replicatプロセスを終了するには、Replicat構成ファイル(process_name. prm)に次の行を追加します。

DDL INCLUDE ALL, EVENTACTIONS (ABORT)

Replicatプロセスを一時停止するには、レプリケーション構成ファイルに次の行を追加します。

DDL INCLUDE ALL, EVENTACTIONS (SUSPEND)

8.2.31.4.4.8 制限事項

バイナリ・データ型の列は、主キーとして使用できません。

Replicat構成ファイルに定義されているソースからターゲットへのマッピングは静的です。Oracle GoldenGate 12.2以降のバージョンでは、Oracleデータベースがレプリケーション・ソースの場合に、DDL伝播とソース・スキーマ展開をサポートします。DDL伝播とソース・スキーマ展開を使用する場合、ソース・メタデータの変更をシームレスに処理できなくなります。

8.2.31.4.4.9 その他の考慮事項

特に一般的なのが、Javaクラスパスに関する問題です。Hiveメタデータ・プロバイダでは、特定のHiveおよびHDFSクライアント・ライブラリをクラスパスで解決する必要があります。

必要なクライアントJARディレクトリは、「クラスパス構成」にリストしてあります。HiveおよびHDFSクライアントJARは、Oracle GoldenGate for Big Dataに付属しません。クライアントJARは、Hiveメタデータ・プロバイダが接続するHiveのバージョンと同じバージョンである必要があります。

Hiveサーバーへの接続を確立するには、クラスパスにhive-site.xmlファイルが存在する必要があります。

8.2.31.4.4.10 トラブルシューティング

マップされたターゲット表がHiveに存在しない場合、Replicatプロセスは、「Table metadata resolution exception」で終了します。

たとえば、次のマッピングを考えてみます。

MAP GG.TCUSTMER, TARGET GG_HIVE.TCUSTMER_HIVE, COLMAP(USEDEFAULTS, CUST_CODE2=CUST_CODE, CITY2=CITY) KEYCOLS(CUST_CODE2);

このマッピングでは、TCUSTMER_HIVEという表を、HiveメタストアのスキーマGG_HIVEに作成する必要があります。この表がHiveに存在しない場合、次の例外が発生します。

ERROR [main) - Table Metadata Resolution Exception
Unable to retrieve table matadata. Table : GG_HIVE.TCUSTMER_HIVE
NoSuchObjectException(message:GG_HIVE.TCUSTMER_HIVE table not found)

8.2.31.4.5 Google BigQueryメタデータ・プロバイダ

Googleメタデータ・プロバイダは、Google Query Jobを使用して、Google BigQuery表からメタデータ・スキーマ情報をキャプチャします。BigQueryがメタデータをフェッチするために、ターゲット上にすでに表が作成されている必要があります。

Google BigQueryは主キーのセマンティクスをサポートしていないため、BigQuery表からキャプチャされるメタデータには主キー定義が含まれません。主キーは、Replicatマッピング文でKEYCOLS構文を使用して識別できます。KEYCOLSが存在しない場合は、ソース表のキー情報が使用されます。

• 認証
  
• サポートされているBigQueryデータ型
  
• パラメータ化されたBigQueryデータ型
  制約を追加するためにパラメータ化できるBigQueryデータ型は、STRING、BYTES、NUMERICおよびBIGNUMERICです。STRINGおよびBYTESデータ型は長さの制約、NUMERICおよびBIGNUMERICはスケールおよび精度の制約を設定できます。
• サポートされていないBigQueryデータ型
  
• Configuring BigQueryメタデータ・プロバイダの構成
  
• サンプル構成
  
• プロキシ設定
  
• クラスパス設定
  
• 制限事項
  

8.2.31.4.5.1 認証

Google BigQueryクラウド・サービス・アカウントは、MDPプロパティでファイルへのパスを設定するか、資格証明JSONの個々のキーをBigQuery MDPプロパティに設定することで、資格証明JSONファイルを使用して接続できます。サービス・アカウントの資格証明キーを構成するためのBigQueryメタデータ・プロバイダの個々のプロパティは、Oracleウォレットを使用して暗号化できます。

8.2.31.4.5.2 サポートされているBigQueryデータ型

次の表に、サポートされているGoogle BigQueryデータ型と、そのデフォルトのスケールおよび精度値を示します。

データ型	範囲	最大スケール	最高精度	最大バイト数
BOOL	TRUE|FALSE|NIL	該当なし	該当なし	1
INT64	[-2^64]から[+ 2^64 -1]	該当なし	該当なし	8
FLOAT64	該当なし	該当なし	なし	8
NUMERIC	最小: 9.9999999999999999999999999999999999999E+28 最大: 9.9999999999999999999999999999999999999E+28	9	38	64
BIG NUMERIC	最小: 5.78960446186580977117854925043439539266 34992332820282019728792003956564819968E+38 最大: 5.78960446186580977117854925043439539266 34992332820282019728792003956564819967E+38	38	77	255
STRING	制限なし	該当なし	該当なし	2147483647L
BYTES	制限なし	該当なし	該当なし	2147483647L
DATE	0001-01-01から9999-12-31	該当なし	該当なし	該当なし
TIME	00:00:00から23:59:59.999999	該当なし	該当なし	該当なし
TIMESTAMP	0001-01-01 00:00:00から9999-12-31 23:59:59.999999 UTC	該当なし	該当なし	該当なし

8.2.31.4.5.3 パラメータ化されたBigQueryデータ型

制約を追加するためにパラメータ化できるBigQueryデータ型は、STRING、BYTES、NUMERICおよびBIGNUMERICです。STRINGおよびBYTESデータ型は長さの制約、NUMERICおよびBIGNUMERICはスケールおよび精度の制約を設定できます。

1. STRING(L): Lは、許可されるUnicode文字の最大数です。
2. BYTES(L): Lは、許可される最大バイト数です。
3. NUMERIC(P[, S])またはBIGNUMERIC(P[, S]): Pは最大精度(合計桁数)で、Sは最大スケール(小数点以下の桁数)です。

パラメータ化されたデータ型は、BigQueryメタデータ・プロバイダでサポートされています。ユーザー定義精度、スケールまたは最大長のデータ型がある場合、メタデータ・プロバイダはそれらの値に基づいてデータを計算します。

8.2.31.4.5.4 サポートされていないBigQueryデータ型

次の表に、サポートされているGoogle BigQueryデータ型と、そのデフォルトのスケールおよび精度値を示します。

メタデータ・プロバイダでサポートされていないBigQueryデータ型は、GEOGRAPHY、JSON、ARRAY、INTERVAL、STRUCTなどの複合データ型です。メタデータ・プロバイダは、無効なデータ型例外が発生した場合、異常終了します。

8.2.31.4.5.5 Configuring BigQueryメタデータ・プロバイダの構成

次の表に、BigQueryメタデータ・プロバイダの構成プロパティを示します。

プロパティ	必須/オプション	有効な値	デフォルト	説明
gg.mdp.type	必須	bq	該当なし	BigQueryメタデータ・プロバイダを選択します
gg.mdp.credentialsFile	オプション	資格証明JSONファイルへのファイル・パス。	該当なし	Google BigQueryサービス・アカウントに接続するための資格証明JSONファイルへのパスを指定します。
gg.mdp.clientId	オプション	有効なBigQuery資格証明クライアントID	該当なし	Google BigQueryサービス・アカウントに接続するための資格証明ファイルのクライアントIDキーを指定します。
gg.mdp.clientEmail	オプション	有効なBigQuery資格証明クライアント電子メール	該当なし	Google BigQueryサービス・アカウントに接続するための資格証明ファイルのクライアント電子メール・キーを指定します。
gg.mdp.privateKeyId	オプション	有効なBigQuery資格証明秘密キーID	該当なし	Google BigQueryサービス・アカウントに接続するための資格証明ファイルの秘密キーIDを指定します。
gg.mdp.privateKey	オプション	有効なBigQuery資格証明秘密キー	該当なし	Google BigQueryサービス・アカウントに接続するための資格証明ファイルの秘密キーを指定します。
gg.mdp.projectId	オプション	一意のBigQueryプロジェクトID	該当なし	BigQueryの一意のプロジェクトID。
gg.mdp.connectionTimeout	オプション	時間(秒)	5	BigQuery接続の接続タイムアウト。
gg.mdp.readTimeout	オプション	時間(秒)	6	BigQuery接続からの読取りのタイムアウト。
gg.mdp.totalTimeout	オプション	時間(秒)	9	BigQuery接続の合計タイムアウト。
gg.mdp.retryCount	オプション	再試行の最大数	3	BigQueryに接続するための再試行の最大数。

資格証明JSONファイルへのパスを設定するプロパティまたは資格証明ファイル・キーを設定するプロパティのいずれかが、BigQueryにアクセスするためのGoogle Serviceアカウントへの接続に必須です。個々の資格証明パラメータを設定すると、Oracleウォレットを使用して暗号化できます。

8.2.31.4.5.6 サンプル構成

サンプル・プロパティ・ファイルの内容:

次に、メタデータ・プロバイダを構成するために、BigQueryハンドラ・プロパティ・ファイルまたはBigQueryイベント・ハンドラ・プロパティ・ファイルに、独自のプロパティとともに追加されるサンプル・プロパティを示します。

gg.mdp.type=bq
gg.mdp.credentialsFile=/path/to/credFile.json

サンプル・パラメータ・ファイル:

メタデータ・プロバイダを構成するためのパラメータ・ファイルに変更はありません。このサンプル・パラメータ・ファイルは、BigQueryイベント・ハンドラ・パラメータ・ファイルに似ています。

REPLICAT bqeh
TARGETDB LIBFILE libggjava.so SET property=dirprm/bqeh.props
MAP schema.tableName, TARGET schema.tableName;

8.2.31.4.5.7 プロキシ設定

プロキシ設定は、プロキシの背後からBigQueryサーバーにアクセスしようとするときにjava仮想マシン(JVM)引数として追加できます。たとえば、oracleプロキシ・サーバー接続の場合は、次のようにプロパティ・ファイルに追加できます。

jvm.bootoptions= -Dhttps.proxyHost=www-proxy.us.oracle.com -Dhttps.proxyPort=80 

8.2.31.4.5.8 クラスパス設定

BigQueryメタデータ・プロバイダの依存性は、Google BigQueryのステージングおよびマージ・イベント・ハンドラ依存性と同じです。BigQueryイベント・ハンドラのOracle GoldenGateクラスパスに追加された依存性は、BigQueryメタデータ・プロバイダの実行に十分であり、追加の依存性を構成する必要はありません。

8.2.31.4.5.9 制限事項

メタデータ・プロバイダでは、複合BigQueryデータ型はまだサポートされていません。サポートされていないデータ型が検出されると異常終了します。

BigQueryハンドラまたはイベント・ハンドラが表およびデータ領域を自動作成するように構成されている場合、メタデータ・プロバイダはメタデータをフェッチするために表が存在することを想定します。BigQueryハンドラおよびイベント・ハンドラの表およびデータ領域を自動作成する機能は、BigQueryメタデータ・プロバイダでは機能しません。メタデータ変更イベントは、Big Queryメタデータ・プロバイダではサポートされていません。メタデータの変更があった場合に、異常終了または一時停止するように構成できます。

8.2.31.5 プラガブル・フォーマッタ

プラガブル・フォーマッタを使用して、Oracle GoldenGate証跡ファイルからの操作を、フォーマット済のメッセージに変換します。このメッセージは、GG for DAAハンドラのいずれかを使用してOracle GoldenGate for Distributed Applications and Analytics (GG for DAA)ターゲットに送信できます。

この章では、プラガブル・フォーマッタの使用方法について説明します。

• 操作ベースと行ベースのフォーマットの使用
  Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)のフォーマッタには、操作ベースと行ベースのフォーマッタがあります。
• Avroフォーマッタの使用
  Apache Avroは、オープン・ソースのデータ・シリアライズ/デシリアライズ・フレームワークの1つです。シリアライズされたデータの柔軟性と簡潔さ、シリアライズ/デシリアライズのパフォーマンスの高さで知られています。Apache Avroは、Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)アプリケーションにおいて一般的に使用されています。
• 区切りテキスト・フォーマッタの使用
  
• JSONフォーマッタの使用
  
• 長さ区切り値フォーマッタの使用
  長さ区切り値(LDV)フォーマッタは、行ベースのフォーマッタの一種です。ソース証跡ファイルから、データベース操作の内容を、長さ区切り値出力としてフォーマットします。ソース証跡からの挿入、更新、削除または切捨ての各操作は、個々の長さ区切りメッセージにフォーマットされます。
• XMLフォーマッタの使用
  XMLフォーマッタは、ソース証跡ファイルの操作前イメージと操作後イメージのデータをXMLドキュメント形式の操作データにフォーマットします。XMLドキュメントの形式は、これまでのリリースのOracle GoldenGate Java AdapterにおけるXML形式と実質的に同じです。

8.2.31.5.1 操作ベースと行ベースのフォーマットの使用

Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)のフォーマッタには、操作ベースと行ベースのフォーマッタがあります。

操作ベースのフォーマッタとは、ソース・データベースの表データに対して発生する個々の挿入、更新および削除イベントです。新しい行はソース・データベースに追加されているところなので、挿入操作で提供されるのは変更後のデータ(またはイメージ)のみです。更新操作は、既存の行データがどのように変更されるかを示す、変更前と変更後の両方のデータを提供します。削除操作は、削除される行を識別するために、変更前のデータのみを提供します。操作ベースのフォーマッタは、ソース証跡ファイルに存在する操作をモデル化します。操作ベースのフォーマットには、変更前および変更後のイメージのフィールドが含まれます。

行ベースのフォーマッタは、操作データを適用した後に存在する行データをモデル化します。行ベースのフォーマッタには、データの1つのイメージのみが含まれます。次の各項では、操作ベースと行ベースのフォーマッタで表示されるデータの種類について説明します。

• 操作フォーマッタ
  
• 行フォーマッタ
  
• 表の行または列の値の状態
  

8.2.31.5.1.1 操作フォーマッタ

操作ベースのフォーマットをサポートするフォーマッタは、JSON、Avro操作、およびXMLです。操作ベース・フォーマッタの出力は、次のとおりです。

• 挿入操作: 操作前イメージのデータはnullです。操作後のイメージ・データが出力されます。

• 更新操作: 操作前イメージと操作後イメージの両方のデータが出力されます。

• 削除操作: 操作前イメージのデータが出力されます。操作後イメージのデータはnullです。

• 切捨て操作: 操作前イメージと操作後イメージの両方のデータがnullです。

8.2.31.5.1.2 行フォーマッタ

行ベースのフォーマットをサポートするフォーマッタは、区切りテキストとAvro行です。行ベースのフォーマッタは、次の操作について次の情報を出力します。

• 挿入操作: 操作後イメージのデータのみ。

• 更新操作: 操作後イメージのデータのみ。主キーの更新は特別なケースであり、各フォーマッタの項で説明します。

• 削除操作: 操作前イメージのデータのみ。

• 切捨て操作: 表名は示されますが、操作前イメージと操作後イメージの両方のデータがnullです。表の切捨てはDDL操作で、異なるデータベース実装はサポートしない場合があります。データベース実装については、Oracle GoldenGateのドキュメントを参照してください。

8.2.31.5.1.3 表の行または列の値の状態

RDBMSでは、特定の行と列の表データは2つの状態(データ値がある、データはnullである)のいずれかのみとなります。ただし、Oracle GoldenGateキャプチャ・プロセスによってデータがOracle GoldenGate証跡ファイルに転送される場合、データの状態は3つ(データ値がある、データはnullである、データがない)になります。

挿入操作の場合、データがnullかどうかに関係なく、操作後イメージにはすべての列値のデータが含まれます。一方、更新操作と削除操作に含まれるデータは、すべての列に完全なデータが含まれるとはかぎりません。更新操作のためにRDBMSにデータを複製する場合、ターゲット・データベースでデータを変更するために必要なのは、主キー値と変更された列の値のみです。また、ターゲット・データベースから行を削除するために必要となるのは、主キー値のみです。したがって、ソース・データベースに値が存在しても、その値がソース証跡ファイルに存在しない可能性があります。ソース証跡ファイルのデータには3つの状態があるので、プラガブル・フォーマッタも3つすべての状態でデータを表せる必要があります。

Oracle GoldenGate証跡ファイル内の行および列データによってOracle GoldenGate for Distributed Applications and Analytics (GG for DAA)統合は大きな影響を受けるため、必要なデータを理解することが重要です。一般的には、Oracle GoldenGate証跡ファイルで操作に含まれるデータを制御できます。Oracleデータベースの場合、このデータはサプリメンタル・ロギング・レベルによって制御されます。Oracle GoldenGate証跡ファイルに含まれる行と列の値を制御する方法を理解するには、ソース・データベース実装に関するOracle GoldenGateのドキュメントを参照してください。

8.2.31.5.2 Avroフォーマッタの使用

Apache Avroは、オープン・ソースのデータ・シリアライズ/デシリアライズ・フレームワークの1つです。シリアライズされたデータの柔軟性と簡潔さ、シリアライズ/デシリアライズのパフォーマンスの高さで知られています。Apache Avroは、Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)アプリケーションにおいて一般的に使用されています。

• Avro行フォーマッタ
  
• Avro操作フォーマッタ
  
• Avroオブジェクト・コンテナ・ファイル・フォーマッタ
  

8.2.31.5.2.1 Avro行フォーマッタ

Avro行フォーマッタは、ソース証跡ファイルの操作データを、Avroバイナリ配列形式のメッセージにフォーマットします。挿入、更新、削除および切捨ての各操作は、個々のAvroメッセージとしてフォーマットされます。ソース証跡ファイルには、操作データの操作前と操作後のイメージが含まれます。Avro行フォーマッタは、その操作前イメージと操作後イメージのデータを取得して、データをAvroバイナリ形式の操作データにフォーマットします。

Avro行フォーマッタは、ソース証跡ファイルの操作データから行データを表す形式に操作をフォーマットします。この形式は、Avroメッセージがデータ変更操作をモデル化するため、Avro操作フォーマッタの出力より簡潔です。

Avro行フォーマッタは、AvroデータをHDFSにストリーミングするときに適した選択肢です。Hiveは、HDFSのデータ・ファイルをAvro形式でサポートします。

この項の内容は次のとおりです。

• 操作メタデータのフォーマットの詳細
  生成されたAvroメッセージ内のメタ列フィールドの自動出力は、Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)リリース21.1以降では削除されています。メタ列フィールドは出力可能ですが、次のプロパティとして明示的に構成する必要があります: gg.handler.name.format.metaColumnsTemplate。
• 操作データのフォーマットの詳細
  
• Avro行メッセージの例
  
• Avroスキーマ
  Avroでは、スキーマの表現にJSONが使用されます。Avroスキーマは、生成されるAvroメッセージの形式を定義し、Avroメッセージのシリアライズとデシリアライズに必要です。
• Avro行の構成プロパティ
  
• サンプル構成の確認
  
• メタデータ変更イベント
  
• 特別な考慮事項
  

8.2.31.5.2.1.1 操作メタデータのフォーマットの詳細

生成されたAvroメッセージ内のメタ列フィールドの自動出力は、Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)リリース21.1以降では削除されています。メタ列フィールドは出力可能ですが、次のプロパティとして明示的に構成する必要があります: gg.handler.name.format.metaColumnsTemplate。

メタ列を出力するには、次のように構成します。

gg.handler.name.format.metaColumnsTemplate=${objectname[table]},${optype[op_type]},${timestamp[op_ts]},${currenttimestamp[current_ts]},${position[pos]}

主キー列およびトークンも含めるには、次のように構成します。

gg.handler.name.format.metaColumnsTemplate=${objectname[table]},${optype[op_type]},${timestamp[op_ts]},${currenttimestamp[current_ts]},${position[pos]},${primarykeycolumns[primary_keys]},${alltokens[tokens]}

詳細は、構成プロパティgg.handler.name.format.metaColumnsTemplateを参照してください。

表8-40 Avroフォーマッタのメタデータ

値	説明
table	完全修飾の表。形式: CATALOG_NAME.SCHEMA_NAME.TABLE_NAME
op_type	ソース証跡ファイルのデータベース操作のタイプ。デフォルト値は、挿入を表すI、更新を表すU、削除を表すD、および切捨てを表すTです。
op_ts	ソース証跡ファイルの操作のタイムスタンプ。このタイムスタンプはソース証跡から取得されるため、固定です。証跡ファイルを再生すると、同じ操作に対して同じタイムスタンプになります。
current_ts	フォーマッタが現在の操作レコードを処理した時刻。このタイムスタンプはISO-8601形式に従い、精度はミリ秒までです。証跡ファイルを再生しても、同じ操作に対して同じタイムスタンプにはなりません。
pos	連結された連番およびソース証跡ファイルのRBA番号。この証跡のポジションにより、操作からソース証跡ファイルをたどることができます。この連番は、ソース証跡ファイルの番号です。RBA番号は、証跡ファイルのオフセットです。
primary_keys	ソース表の主キーの列名を保持する配列変数。
tokens	ソース証跡ファイルからのトークン・キー値ペアを保持するマップ変数。

8.2.31.5.2.1.2 操作データのフォーマットの詳細

操作データは操作メタデータの後に続きます。このデータは、列名で識別される個々のフィールドとして表されます。

ソース証跡ファイルからの操作の列値は、列に値がある、列値がnullである、列値がないの3つの状態のいずれかです。Avro属性はこのうちの2つの状態(列に値がある、列値がnullである)のみをサポートします。列値がない状態は、null値と同様に処理されます。Avro行フォーマッタを使用する際には、ソース証跡ファイルのすべての列に対する完全イメージ・データを提供するために、Oracle GoldenGateキャプチャ・プロセスを構成することをお薦めします。

Avro行フォーマッタのデフォルト設定では、ソース証跡ファイルのデータ型を、対応するAvroデータ型にマップします。Avroでサポートされるデータ型は限定的であるため、ソース列はAvroのLONG、DOUBLE、FLOAT、BINARYまたはSTRINGデータ型にマップします。また、すべてのデータを文字列として処理するようにデータ型マッピングを構成することもできます。

8.2.31.5.2.1.3 Avro行メッセージの例

Avroメッセージはバイナリなので、人間が読める形式ではありません。次のサンプル・メッセージは、JSON形式のメッセージを示しています。

• 挿入メッセージの例
  
• 更新メッセージの例
  
• 削除メッセージの例
  
• 切捨てメッセージの例
  

8.2.31.5.2.1.3.1 挿入メッセージの例

{"table": "GG.TCUSTORD", 
"op_type": "I", 
"op_ts": "2013-06-02 22:14:36.000000", 
"current_ts": "2015-09-18T10:13:11.172000", 
"pos": "00000000000000001444", 
"primary_keys": ["CUST_CODE", "ORDER_DATE", "PRODUCT_CODE", "ORDER_ID"], 
"tokens": {"R": "AADPkvAAEAAEqL2AAA"}, 
"CUST_CODE": "WILL", 
"ORDER_DATE": "1994-09-30:15:33:00", 
"PRODUCT_CODE": "CAR", 
"ORDER_ID": "144", 
"PRODUCT_PRICE": 17520.0, 
"PRODUCT_AMOUNT": 3.0, 
"TRANSACTION_ID": "100"}

8.2.31.5.2.1.3.2 更新メッセージの例

{"table": "GG.TCUSTORD", 
"op_type": "U", 
"op_ts": "2013-06-02 22:14:41.000000", 
"current_ts": "2015-09-18T10:13:11.492000", 
"pos": "00000000000000002891", 
"primary_keys": ["CUST_CODE", "ORDER_DATE", "PRODUCT_CODE", "ORDER_ID"], "tokens":
 {"R": "AADPkvAAEAAEqLzAAA"}, 
"CUST_CODE": "BILL", 
"ORDER_DATE": "1995-12-31:15:00:00", 
"PRODUCT_CODE": "CAR", 
"ORDER_ID": "765", 
"PRODUCT_PRICE": 14000.0, 
"PRODUCT_AMOUNT": 3.0, 
"TRANSACTION_ID": "100"}

8.2.31.5.2.1.3.3 削除メッセージの例

{"table": "GG.TCUSTORD",
"op_type": "D", 
"op_ts": "2013-06-02 22:14:41.000000", 
"current_ts": "2015-09-18T10:13:11.512000", 
"pos": "00000000000000004338", 
"primary_keys": ["CUST_CODE", "ORDER_DATE", "PRODUCT_CODE", "ORDER_ID"], "tokens":
 {"L": "206080450", "6": "9.0.80330", "R": "AADPkvAAEAAEqLzAAC"}, "CUST_CODE":
 "DAVE", 
"ORDER_DATE": "1993-11-03:07:51:35", 
"PRODUCT_CODE": "PLANE", 
"ORDER_ID": "600", 
"PRODUCT_PRICE": null, 
"PRODUCT_AMOUNT": null, 
"TRANSACTION_ID": null}

8.2.31.5.2.1.3.4 切捨てメッセージの例

{"table": "GG.TCUSTORD", 
"op_type": "T", 
"op_ts": "2013-06-02 22:14:41.000000", 
"current_ts": "2015-09-18T10:13:11.514000", 
"pos": "00000000000000004515", 
"primary_keys": ["CUST_CODE", "ORDER_DATE", "PRODUCT_CODE", "ORDER_ID"], "tokens":
 {"R": "AADPkvAAEAAEqL2AAB"}, 
"CUST_CODE": null, 
"ORDER_DATE": null, 
"PRODUCT_CODE": null, 
"ORDER_ID": null, 
"PRODUCT_PRICE": null, 
"PRODUCT_AMOUNT": null, 
"TRANSACTION_ID": null}

8.2.31.5.2.1.4 Avroスキーマ

Avroは、スキーマの表現にJSONを使用します。Avroスキーマは、生成されるAvroメッセージの形式を定義し、Avroメッセージのシリアライズとデシリアライズに必要です。

スキーマは、最初に表に対する操作が発生した時点でジャストインタイム方式で生成されます。メタデータに変更があると、新しいスキーマが生成されます。生成されるAvroスキーマは表定義に固有であるため、処理された操作のために出現した表ごとに、個別のAvroスキーマが生成されます。デフォルトでは、AvroスキーマはGoldenGate_Home/dirdefディレクトリに書き込まれますが、書き込む場所は設定を変更できます。Avroスキーマのファイル名は、Fully_Qualified_Table_Name.avscという命名規則に従います。

前の項の参照例に示したAvro行フォーマッタのサンプルのAvroスキーマは、次のとおりです。

{
  "type" : "record",
  "name" : "TCUSTORD",
  "namespace" : "GG",
  "fields" : [ {
    "name" : "table",
    "type" : "string"
  }, {
    "name" : "op_type",
    "type" : "string"
  }, {
    "name" : "op_ts",
    "type" : "string"
  }, {
    "name" : "current_ts",
    "type" : "string"
  }, {
    "name" : "pos",
    "type" : "string"
  }, {
    "name" : "primary_keys",
    "type" : {
      "type" : "array",
      "items" : "string"
    }
  }, {
    "name" : "tokens",
    "type" : {
      "type" : "map",
      "values" : "string"
    },
    "default" : { }
  }, {
    "name" : "CUST_CODE",
    "type" : [ "null", "string" ],
    "default" : null
  }, {
    "name" : "ORDER_DATE",
    "type" : [ "null", "string" ],
    "default" : null
  }, {
    "name" : "PRODUCT_CODE",
    "type" : [ "null", "string" ],
    "default" : null
  }, {
    "name" : "ORDER_ID",
    "type" : [ "null", "string" ],
    "default" : null
  }, {
    "name" : "PRODUCT_PRICE",
    "type" : [ "null", "double" ],
    "default" : null
  }, {
    "name" : "PRODUCT_AMOUNT",
    "type" : [ "null", "double" ],
    "default" : null
  }, {
    "name" : "TRANSACTION_ID",
    "type" : [ "null", "string" ],
    "default" : null
  } ]
}

8.2.31.5.2.1.5 Avro行の構成プロパティ

表8-41 Avro行の構成プロパティ

プロパティ	オプション/必須	有効な値	デフォルト	説明
gg.handler.name.format.insertOpKey	オプション	任意の文字列	I	出力レコードに挿入され、挿入操作を示す指標です。
gg.handler.name.format.updateOpKey	オプション	任意の文字列	U	出力レコードに挿入され、更新操作を示す指標です。
gg.handler.name.format.deleteOpKey	オプション	任意の文字列	D	出力レコードに挿入され、削除操作を示す指標です。
gg.handler.name.format.truncateOpKey	オプション	任意の文字列	T	出力レコードに挿入され、切捨て操作を示す指標です。
gg.handler.name.format.encoding	オプション	Javaでサポートされる任意の有効なエンコーディング名または別名。	UTF-8 (JSONのデフォルト)	生成されるJSON Avroスキーマの出力エンコーディングを制御します。JSONのデフォルトはUTF-8です。Avroメッセージはバイナリで、独自の内部形式でエンコーディングをサポートしています。
gg.handler.name.format.treatAllColumnsAsStrings	オプション	true | false	false	生成されるAvroメッセージの出力の型付けを制御します。falseに設定すると、フォーマッタはOracle GoldenGateの型を、対応するAVROの型にマップしようと試みます。trueに設定すると、すべてのデータは生成されるAvroメッセージとスキーマで文字列として扱われます。
gg.handler.name.format.pkUpdateHandling	オプション	abend | update | delete-insert	abend	フォーマッタが、主キーを変更する更新操作をどのように処理するかを指定します。Avro行フォーマッタの主キーを操作する場合は、慎重に検討する必要があります。 abend: プロセスが終了します。 update: プロセスはこの更新を通常の更新として処理します。 deleteまたはinsert: プロセスはこの更新を削除および挿入として処理します。完全なサプリメンタル・ロギングを有効にする必要があります。操作前と操作後の完全な行イメージがない場合、挿入データは不完全になります。
gg.handler.name.format.lineDelimiter	オプション	任意の文字列	値なし	各Avroメッセージの後に区切り文字を挿入します。これはベスト・プラクティスではありませんが、特定のケースでは、データ・ストリームを解析し、そのストリームから個々のAvroメッセージを抽出することがあります。Avroメッセージには出現しそうにない一意の区切り文字を選択してください。このプロパティはCDATA[]ラッピングをサポートします。
gg.handler.name.format.versionSchemas	オプション	true|false	false	Avroスキーマは、常に、fully_qualified_table_name.avsc規則に従います。このプロパティをtrueに設定すると、fully_qualified_table_name_current_timestamp.avscという名前の追加のAvroスキーマがスキーマ・ディレクトリに作成されます。追加のAvroスキーマは、破棄も削除もされないため、スキーマ展開の履歴になります。
gg.handler.name.format.wrapMessageInGenericAvroMessage	オプション	true|false	false	汎用のAvroラッパー・メッセージで、ソース証跡ファイルからの操作に対してAvroメッセージをラップします。詳細は、「汎用のラッパー機能」を参照してください。
gg.handler.name.format.schemaDirectory	オプション	有効で存在する人気のファイル・システム・パス。	./dirdef	生成されるAvroスキーマの出力場所。
gg.handler.name.format.schemaFilePath	オプション	Javaでサポートされる任意の有効なエンコーディング名または別名。	./dirdef	スキーマが出力されるHDFS内のディレクトリ。メタデータ変更により、関連付けられた表の次の操作中にスキーマが上書きされます。スキーマは、ローカル・ファイル・システムcatalog.schema.table.avscに書き込まれるスキーマと同じ命名規則に従います。
gg.handler.name.format.iso8601Format	オプション	true | false	true	現在のタイムスタンプの形式。デフォルトはISO 8601形式です。falseに設定すると、現在のタイムスタンプの日付と時刻の間のTが削除され、かわりにスペースが出力されます。
gg.handler.name.format.includeIsMissingFields	オプション	true | false	false	各ソース・フィールドに{column_name}_isMissingブール・フィールドを含めるには、trueに設定します。このフィールドを使用すると、null値がソース証跡ファイルでnullである(値はfalse)か、ソース証跡ファイルにない(値はtrue)かを、ダウンストリーム・アプリケーションが区別できるようになります。
gg.handler.name.format.enableDecimalLogicalType	オプション	true | false	false	Avro decimal論理型の使用を有効にします。小数論理型は、数値をバイト配列として表し、従来の64ビット長またはdoubleデータ型に収まるよりも大きな数のサポートを提供できます。
gg.handler.name.format.oracleNumberScale	オプション	0から38までの任意の整数値。	なし	Avro decimalデータ型のスケールを設定できます。enableDecimalLogicalType=trueを設定した場合にのみ適用されます。Oracle NUMBERは、変数の精度とスケールをサポートするOracle Database固有の数値データ型です。精度とスケールは、Oracle NUMBERデータ型のインスタンスごとの変数です。精度とスケールは、Avro decimal論理型を生成する場合の必須パラメータです。これにより、Oracle NUMBERデータ型からAvroへのマッピングが難しくなります。Avroスキーマの生成時にOracle NUMBERデータ型の精度とスケールを確定する方法がないからです。最良の代替方法は、Oracle NUMBERの有効なインスタンスを保持できる、精度164およびスケール38の大きなAvro decimalデータ型を生成することです。これにより、Oracle Numberデータ型をAvro decimalデータ型に変換する際の精度損失の問題は解消されますが、Avroメッセージ・ダウンストリームから取得されたときのAvro decimalデータ型が小数点以下38桁であることが望ましくない場合があります。
gg.handler.name.format.mapOracleNumbersAsStrings	オプション	true | false	false	このプロパティは、プロパティgg.handler.name.format.enableDecimalLogialType=trueを介して小数論理型が有効になっている場合にのみ適用されます。Oracleの数値は、高精度(168)と最大38の浮動スケールがあるため、特に問題があります。Sparkなどの一部の分析ツールは、そこまで大きな数値を読み取ることができません。このプロパティを使用すると、これらのOracle数値を文字列としてマップでき、小さい数値を小数論理型としてマッピングできます。
gg.handler.name.format.enableTimestampLogicalType	オプション	true | false	false	ソースのdateおよびtimeデータ型をAvro TimestampMicros論理データ型にマップするには、trueに設定します。ソースのdateおよびtimeデータ型の意味をなすマスクを提供するように、変数gg.format.timestampを構成する必要があります。Avro TimestampMicrosは、Avro 1.8仕様に含まれています。gghandler.name.format.enableTimestampLogicalTypeがtrueに設定されており、gg.format.timestampが設定されていない場合、Replicatは構成例外で異常終了します。
gg.handler.name.format.mapLargeNumbersAsStrings	オプション	true | false	false	Oracle GoldenGateでは、浮動小数点および整数ソース・データ型がサポートされます。これらのデータ型の中には、Avroプリミティブのdoubleまたはlongデータ型に適合しないものもあります。Avroプリミティブのdoubleまたはlongデータ型に適合しないフィールドをAvro文字列にマップするには、このプロパティをtrueに設定します。
gg.handler.name.format.metaColumnsTemplate	オプション	「メタ列のキーワード」を参照してください。	なし	現在のメタ列情報を簡単な方法で構成でき、使用する明示的な必要性が排除されます。 insertOpKey | updateOpKey | deleteOpKey | truncateOpKey | includeTableName | includeOpTimestamp | includeOpType | includePosition | includeCurrentTimestamp, useIso8601Format これは、テンプレートを表す1つ以上のテンプレート化された値で構成されているカンマ区切りの文字列です。 メタ列のキーワードの詳細は、メタ列のキーワードを参照してください。
gg.handler.name.format.maxPrecision	オプション	なし	正の整数	Avro 10進数論理型の最大精度を設定できます。アプリケーションの消費には、Avroの精度に制限がある場合があります(Apache Sparkでのサポートは最大精度38です)。 警告: このプロパティの構成はリスクがないわけではありません。 Oracle RDBMSのNUMBER型のサポートは、最大精度164です。このプロパティの構成は、大きいソース数値型を小さいターゲット数値型にキャストしている可能性があります。ソース値の精度が構成済の精度より大きい場合、実行時例外が発生し、Replicatプロセスが異常終了します。この動作はバグではありません。これは予期された動作です。

8.2.31.5.2.1.6 サンプル構成の確認

Javaアダプタ・プロパティ・ファイルのAvro行フォーマッタのサンプル構成を次に示します。

gg.handler.hdfs.format=avro_row
gg.handler.hdfs.format.insertOpKey=I
gg.handler.hdfs.format.updateOpKey=U
gg.handler.hdfs.format.deleteOpKey=D
gg.handler.hdfs.format.truncateOpKey=T
gg.handler.hdfs.format.encoding=UTF-8
gg.handler.hdfs.format.pkUpdateHandling=abend
gg.handler.hdfs.format.wrapMessageInGenericAvroMessage=false

8.2.31.5.2.1.7 メタデータ変更イベント

複製されるデータベースとアップストリームのOracle GoldenGateレプリケーション・プロセスでメタデータ変更イベントを伝播できる場合、メタデータが変更されたときにAvro行フォーマッタはアクションを実行できます。Avroメッセージは対応するスキーマに緊密に依存しているため、Avroフォーマットを使用する場合、メタデータの変更は重要です。

メタデータ変更イベント後に表操作が発生するとすぐに更新されたAvroスキーマが生成されます。メタデータ変更イベントの影響を理解して、ダウンストリーム・ターゲットを新しいAvroスキーマに変更する必要があります。AvroメッセージがAvroスキーマに密に依存している場合、互換性の問題が生じることがあります。スキーマ変更の前に生成されるAvroメッセージを、新たに生成されたAvroスキーマでデシリアライズすることはできません。

逆に、スキーマ変更の後で生成されるAvroメッセージを、前に生成されたAvroスキーマでデシリアライズすることもできません。ベスト・プラクティスとして、メッセージの生成に使用されたのと同じバージョンのAvroスキーマを使用するようにしてください。詳細は、Apache Avroのドキュメントを参照してください。

8.2.31.5.2.1.8 特別な考慮事項

この項では、次の特別な考慮事項について説明します。

• トラブルシューティング
  
• 主キーの更新
  
• 汎用のラッパー機能
  

8.2.31.5.2.1.8.1 トラブルシューティング

Avroはバイナリ形式なので、人間が読める形式ではありません。Avroメッセージはバイナリ形式なので、問題が発生した場合にデバッグが容易ではないため、Avro行フォーマッタでは問題のデバッグに役立つ特別な機能が用意されています。log4j Javaロギング・レベルをTRACEに設定すると、Avroメッセージがデシリアライズされ、ログ・ファイルにJSONオブジェクトとして表示されるため、作成されたAvroメッセージの構造および内容を確認できます。TRACEは、パフォーマンスに大きくマイナスの影響を及ぼすため、本番環境では有効にしないでください。内容をトラブルシューティングするために、人間が読める内容を生成するフォーマッタの使用を検討することが必要な場合があります。XMLまたはJSONフォーマッタはどちらも人間が読める形式で内容を生成します。

8.2.31.5.2.1.8.2 主キーの更新

Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)統合では、主キーの更新操作には特別な考慮と計画が必要です。主キーの更新では、ソース・データベース内の特定の行の1つ以上の主キーを変更します。データはOracle GoldenGate for Distributed Applications and Analytics (GG for DAA)アプリケーションにおいては追加されるため、主キーの更新操作は、特別な処理がない更新というよりは、新規挿入に似ています。次のプロパティを使用して、主キーを処理するようにAvro行フォーマッタを構成できます。

表8-42 構成可能な動作

値	説明
abend	フォーマッタが終了します。この動作はデフォルトの動作です。
update	この構成では、主キーの更新が他の更新操作と同じように処理されます。この構成は、GG for DAAからの行データの選択基準として主キーが使用されないと間違いなくわかっている場合のみ使用してください。
delete-insert	主キーの更新は、操作前イメージのデータを使用する削除と、操作後イメージのデータを使用する挿入という特殊なケースとして処理されます。この構成では、GG for DAAアプリケーションでの主キー更新の影響がより正確にモデル化される場合があります。ただし、この構成を選択する場合は、ソース・データベースでのレプリケーションで完全なサプリメンタル・ロギングを有効にすることが重要です。完全なサプリメンタル・ロギングを有効にしない場合、削除操作は正常に処理されますが、挿入操作では、GG for DAAアプリケーションにおける行データの完全表現のためにすべての列のすべてのデータが含まれるわけではありません。

8.2.31.5.2.1.8.3 汎用のラッパー機能

Avroメッセージは自己記述型ではないため、メッセージの受信者は、メッセージに対応するスキーマのことを知っていないと、メッセージをデシリアライズできません。Avroメッセージはバイナリであり、メッセージの内容を調べてメッセージ・タイプを確定する一貫した、または信頼できる方法はありません。したがって、Kafkaのような1つのデータ・ストリームにメッセージをインタレースするときに、Avroは厄介です。

Avroフォーマッタには、汎用のAvroメッセージでAvroメッセージをラップする特別な機能があります。この機能を有効にするには、次の構成プロパティを設定します。

gg.handler.name.format.wrapMessageInGenericAvroMessage=true

汎用のメッセージとは、出力されるAvroメッセージすべてに共通するAvroペイロード・メッセージをラップするAvroメッセージです。汎用メッセージのスキーマは、generic_wrapper.avscという名前で、出力スキーマ・ディレクトリに書き込まれます。このメッセージには、次の3つのフィールドがあります。

• table_name :完全修飾のソース表名。

• schema_fingerprint : ラップされたメッセージのAvroスキーマのフィンガープリント。フィンガープリントは、Avro SchemaNormalization.parsingFingerprint64(schema)コールを使用して生成されます。

• payload: ラップされるAvroメッセージ。

Avroフォーマッタの汎用ラッパー・スキーマは、次のとおりです。

{
  "type" : "record",
  "name" : "generic_wrapper",
  "namespace" : "oracle.goldengate",
  "fields" : [ {
    "name" : "table_name",
    "type" : "string"
  }, {
    "name" : "schema_fingerprint",
    "type" : "long"
  }, {
    "name" : "payload",
    "type" : "bytes"
  } ]
}

8.2.31.5.2.2 Avro操作フォーマッタ

Avro操作フォーマッタは、ソース証跡ファイルの操作データを、Avroバイナリ配列形式のメッセージにフォーマットします。挿入、更新、削除および切捨ての各操作は、個々のAvroメッセージとしてフォーマットされます。ソース証跡ファイルには、操作データの操作前と操作後のイメージが含まれます。Avro操作フォーマッタは、このデータをAvroバイナリ形式の操作データにフォーマットします。

この形式は、Avroメッセージが行データをモデル化するAvro行フォーマッタの出力より詳細です。

• 操作メタデータのフォーマットの詳細
  
• 操作データのフォーマットの詳細
  
• Avro操作メッセージの例
  
• Avroスキーマ
  
• Avro操作フォーマッタの構成プロパティ
  
• サンプル構成の確認
  
• メタデータ変更イベント
  
• 特別な考慮事項
  

8.2.31.5.2.2.1 操作メタデータのフォーマットの詳細

メタ列を出力するには、gg.handler.name.format.metaColumnsTemplate=${objectname[table]},${optype[op_type]},${timestamp[op_ts]},${currenttimestamp[current_ts]},${position[pos]}を構成します

主キー列およびトークンも含めるには、次のように構成します。

gg.handler.name.format.metaColumnsTemplate=${objectname[table]},${optype[op_type]},${timestamp[op_ts]},${currenttimestamp[current_ts]},${position[pos]},${primarykeycolumns[primary_keys]},${alltokens[tokens]}

詳細は、構成プロパティgg.handler.name.format.metaColumnsTemplateを参照してください

表8-43 Avroメッセージとそのメタデータ

フィールド	説明
table	完全修飾の表名。形式は次のとおりです。 CATALOG_NAME.SCHEMA NAME.TABLE NAME
op_type	ソース証跡ファイルのデータベース操作のタイプ。デフォルト値は、挿入を表すI、更新を表すU、削除を表すD、および切捨てを表すTです。
op_ts	ソース証跡ファイルの操作のタイムスタンプ。このタイムスタンプはソース証跡から取得されるため、固定です。証跡ファイルを再生すると、同じ操作に対して同じタイムスタンプになります。
current_ts	フォーマッタが現在の操作レコードを処理した時刻。このタイムスタンプはISO-8601形式に従い、精度はミリ秒までです。証跡ファイルを再生しても、同じ操作に対して同じタイムスタンプにはなりません。
pos	連結された連番およびソース証跡ファイルのRBA番号。証跡のポジションは、操作からソース証跡ファイルをたどるトレーサビリティ情報になります。この連番は、ソース証跡ファイルの番号です。RBA番号は、証跡ファイルのオフセットです。
primary_keys	ソース表の主キーの列名を保持する配列変数。
tokens	ソース証跡ファイルからのトークン・キー値ペアを保持するマップ変数。

8.2.31.5.2.2.2 操作データのフォーマットの詳細

この操作データは、列名で識別される個々のフィールドとして表されます。

ソース証跡ファイルからの操作の列値は、列に値がある、列値がnullである、列値がないの3つの状態のいずれかです。Avro属性はこのうちの2つの状態(列に値がある、列値がnullである)のみをサポートします。Avro操作フォーマッタには、列値が欠落しているかどうかを示すために、列ごとに追加のブール・フィールドCOLUMN_NAME_isMissingがあります。COLUMN_NAMEフィールドをCOLUMN_NAME_isMissingフィールドとともに使用すると、3つすべての状態を定義できます。

• 状態1: 列に値がある

  COLUMN_NAMEフィールドに値がある

  COLUMN_NAME_isMissingフィールドがfalse

• 状態2: 列値がnullである

  COLUMN_NAMEフィールドの値がnull

  COLUMN_NAME_isMissingフィールドがfalse

• 状態3: 列値がない

  COLUMN_NAMEフィールドの値がnull

  COLUMN_NAME_isMissingフィールドがtrue

デフォルトでは、Avro行フォーマッタは、ソース証跡ファイルのデータ型を、対応するAvroデータ型にマップします。Avroでサポートされるデータ型は少ないため、この機能は通常、ソース証跡ファイルの数値フィールドを、数値として型付けされるメンバーにマップします。また、このデータ型マッピングを、すべてのデータを文字列として処理するように構成することもできます。

8.2.31.5.2.2.3 Avro操作メッセージの例

Avroメッセージはバイナリなので、人間が読める形式ではありません。次の各トピックでは、JSON形式のAvroメッセージの例を示しています。

• 挿入メッセージの例
  
• 更新メッセージの例
  
• 削除メッセージの例
  
• 切捨てメッセージの例
  

8.2.31.5.2.2.3.1 挿入メッセージの例

{"table": "GG.TCUSTORD",
"op_type": "I", 
"op_ts": "2013-06-02 22:14:36.000000", 
"current_ts": "2015-09-18T10:17:49.570000", 
"pos": "00000000000000001444", 
"primary_keys": ["CUST_CODE", "ORDER_DATE", "PRODUCT_CODE", "ORDER_ID"], "tokens":
 {"R": "AADPkvAAEAAEqL2AAA"}, 
"before": null, 
"after": {
"CUST_CODE": "WILL", 
"CUST_CODE_isMissing": false, 
"ORDER_DATE": "1994-09-30:15:33:00", 
"ORDER_DATE_isMissing": false, 
"PRODUCT_CODE": "CAR", 
"PRODUCT_CODE_isMissing": false, 
"ORDER_ID": "144", "ORDER_ID_isMissing": false, 
"PRODUCT_PRICE": 17520.0, 
"PRODUCT_PRICE_isMissing": false, 
"PRODUCT_AMOUNT": 3.0, "PRODUCT_AMOUNT_isMissing": false, 
"TRANSACTION_ID": "100", 
"TRANSACTION_ID_isMissing": false}}

8.2.31.5.2.2.3.2 更新メッセージの例

{"table": "GG.TCUSTORD", 
"op_type": "U", 
"op_ts": "2013-06-02 22:14:41.000000", 
"current_ts": "2015-09-18T10:17:49.880000", 
"pos": "00000000000000002891", 
"primary_keys": ["CUST_CODE", "ORDER_DATE", "PRODUCT_CODE", "ORDER_ID"], "tokens":
 {"R": "AADPkvAAEAAEqLzAAA"}, 
"before": {
"CUST_CODE": "BILL", 
"CUST_CODE_isMissing": false, 
"ORDER_DATE": "1995-12-31:15:00:00", 
"ORDER_DATE_isMissing": false, 
"PRODUCT_CODE": "CAR", 
"PRODUCT_CODE_isMissing": false, 
"ORDER_ID": "765", 
"ORDER_ID_isMissing": false, 
"PRODUCT_PRICE": 15000.0, 
"PRODUCT_PRICE_isMissing": false, 
"PRODUCT_AMOUNT": 3.0, 
"PRODUCT_AMOUNT_isMissing": false, 
"TRANSACTION_ID": "100", 
"TRANSACTION_ID_isMissing": false}, 
"after": {
"CUST_CODE": "BILL", 
"CUST_CODE_isMissing": false, 
"ORDER_DATE": "1995-12-31:15:00:00", 
"ORDER_DATE_isMissing": false, 
"PRODUCT_CODE": "CAR", 
"PRODUCT_CODE_isMissing": false, 
"ORDER_ID": "765", 
"ORDER_ID_isMissing": false, 
"PRODUCT_PRICE": 14000.0, 
"PRODUCT_PRICE_isMissing": false, 
"PRODUCT_AMOUNT": 3.0, 
"PRODUCT_AMOUNT_isMissing": false, 
"TRANSACTION_ID": "100", 
"TRANSACTION_ID_isMissing": false}}

8.2.31.5.2.2.3.3 削除メッセージの例

{"table": "GG.TCUSTORD", 
"op_type": "D", 
"op_ts": "2013-06-02 22:14:41.000000", 
"current_ts": "2015-09-18T10:17:49.899000", 
"pos": "00000000000000004338", 
"primary_keys": ["CUST_CODE", "ORDER_DATE", "PRODUCT_CODE", "ORDER_ID"], "tokens":
 {"L": "206080450", "6": "9.0.80330", "R": "AADPkvAAEAAEqLzAAC"}, "before": {
"CUST_CODE": "DAVE", 
"CUST_CODE_isMissing": false, 
"ORDER_DATE": "1993-11-03:07:51:35", 
"ORDER_DATE_isMissing": false, 
"PRODUCT_CODE": "PLANE", 
"PRODUCT_CODE_isMissing": false, 
"ORDER_ID": "600", 
"ORDER_ID_isMissing": false, 
"PRODUCT_PRICE": null, 
"PRODUCT_PRICE_isMissing": true, 
"PRODUCT_AMOUNT": null, 
"PRODUCT_AMOUNT_isMissing": true, 
"TRANSACTION_ID": null, 
"TRANSACTION_ID_isMissing": true}, 
"after": null}

8.2.31.5.2.2.3.4 切捨てメッセージの例

{"table": "GG.TCUSTORD", 
"op_type": "T", 
"op_ts": "2013-06-02 22:14:41.000000", 
"current_ts": "2015-09-18T10:17:49.900000", 
"pos": "00000000000000004515", 
"primary_keys": ["CUST_CODE", "ORDER_DATE", "PRODUCT_CODE", "ORDER_ID"], "tokens":
 {"R": "AADPkvAAEAAEqL2AAB"}, 
"before": null, 
"after": null}

8.2.31.5.2.2.4 Avroスキーマ

AvroスキーマはJSONとして表されます。Avroスキーマは、生成されるAvroメッセージの形式を定義し、Avroメッセージのシリアライズとデシリアライズに必要です。Avroスキーマは、最初に表に対する操作が発生した時点でジャストインタイム方式で生成されます。Avroスキーマは表定義に固有であるため、処理される操作で発生する表ごとに個別のAvroスキーマが生成されます。デフォルトでは、AvroスキーマはGoldenGate_Home/dirdefディレクトリに書き込まれますが、書き込む場所は設定を変更できます。Avroスキーマのファイル名は、Fully_Qualified_Table_Name.avsc という命名規則に従います。

前の項のサンプルに示したAvro操作フォーマッタのAvroスキーマのサンプルは、次のとおりです。

{
  "type" : "record",
  "name" : "TCUSTORD",
  "namespace" : "GG",
  "fields" : [ {
    "name" : "table",
    "type" : "string"
  }, {
    "name" : "op_type",
    "type" : "string"
  }, {
    "name" : "op_ts",
    "type" : "string"
  }, {
    "name" : "current_ts",
    "type" : "string"
  }, {
    "name" : "pos",
    "type" : "string"
  }, {
    "name" : "primary_keys",
    "type" : {
      "type" : "array",
      "items" : "string"
    }
  }, {
    "name" : "tokens",
    "type" : {
      "type" : "map",
      "values" : "string"
    },
    "default" : { }
  }, {
    "name" : "before",
    "type" : [ "null", {
      "type" : "record",
      "name" : "columns",
      "fields" : [ {
        "name" : "CUST_CODE",
        "type" : [ "null", "string" ],
        "default" : null
      }, {
        "name" : "CUST_CODE_isMissing",
        "type" : "boolean"
      }, {
        "name" : "ORDER_DATE",
        "type" : [ "null", "string" ],
        "default" : null
      }, {
        "name" : "ORDER_DATE_isMissing",
        "type" : "boolean"
      }, {
        "name" : "PRODUCT_CODE",
        "type" : [ "null", "string" ],
        "default" : null
      }, {
        "name" : "PRODUCT_CODE_isMissing",
        "type" : "boolean"
      }, {
        "name" : "ORDER_ID",
        "type" : [ "null", "string" ],
        "default" : null
      }, {
        "name" : "ORDER_ID_isMissing",
        "type" : "boolean"
      }, {
        "name" : "PRODUCT_PRICE",
        "type" : [ "null", "double" ],
        "default" : null
      }, {
        "name" : "PRODUCT_PRICE_isMissing",
        "type" : "boolean"
      }, {
        "name" : "PRODUCT_AMOUNT",
        "type" : [ "null", "double" ],
        "default" : null
      }, {
        "name" : "PRODUCT_AMOUNT_isMissing",
        "type" : "boolean"
      }, {
        "name" : "TRANSACTION_ID",
        "type" : [ "null", "string" ],
        "default" : null
      }, {
        "name" : "TRANSACTION_ID_isMissing",
        "type" : "boolean"
      } ]
    } ],
    "default" : null
  }, {
    "name" : "after",
    "type" : [ "null", "columns" ],
    "default" : null
  } ]
}

8.2.31.5.2.2.5 Avro操作フォーマッタの構成プロパティ

表8-44 構成プロパティ

プロパティ	オプションY/N	有効な値	デフォルト	説明
gg.handler.name.format.insertOpKey	オプション	任意の文字列	I	出力レコードに挿入され、挿入操作を示す指標です
gg.handler.name.format.updateOpKey	オプション	任意の文字列	U	出力レコードに挿入され、更新操作を示す指標です。
gg.handler.name.format.deleteOpKey	オプション	任意の文字列	D	出力レコードに挿入され、削除操作を示す指標です。
gg.handler.name.format.truncateOpKey	オプション	任意の文字列	T	出力レコードに挿入され、切捨て操作を示す指標です。
gg.handler.name.format.encoding	オプション	Javaでサポートされる任意の有効なエンコーディング名または別名	UTF-8 (JSONのデフォルト)	生成されるJSON Avroスキーマの出力エンコーディングを制御します。JSONのデフォルトはUTF-8です。Avroメッセージはバイナリで、独自の内部形式でエンコーディングをサポートしています。
gg.handler.name.format.treatAllColumnsAsStrings	オプション	true | false	false	生成されるAvroメッセージの出力の型付けを制御します。falseに設定すると、フォーマッタはOracle GoldenGateの型を、対応するAVROの型にマップしようと試みます。trueに設定すると、すべてのデータは生成されるAvroメッセージとスキーマで文字列として扱われます。
gg.handler.name.format.lineDelimiter	オプション	任意の文字列	値なし	各Avroメッセージの後に区切り文字を挿入します。これはベスト・プラクティスではありませんが、特定のケースでは、データ・ストリームを解析し、そのストリームから個々のAvroメッセージを抽出するために、このプロパティが役立つことがあります。Avroメッセージには出現しそうにない一意の区切り文字を選択してください。このプロパティはCDATA[]ラッピングをサポートします。
gg.handler.name.format.schemaDirectory	オプション	有効で存在する人気のファイル・システム・パス。	./dirdef	生成されるAvroスキーマの出力場所。
gg.handler.name.format.wrapMessageInGenericAvroMessage	オプション	true|false	false	汎用のAvroラッパー・メッセージで、ソース証跡ファイルからの操作に対してAvroメッセージをラップします。詳細は、「汎用のラッパー機能」を参照してください。
gg.handler.name.format.iso8601Format	オプション	true | false	true	現在のタイムスタンプの形式。デフォルトでは、ISO 8601をfalseに設定すると、現在のタイムスタンプの日付と時刻の間のTが削除され、かわりにスペースが出力されます。
gg.handler.name.format.includeIsMissingFields	オプション	true | false	false	各ソース・フィールドに{column_name}_isMissingブール・フィールドを含めるには、trueに設定します。このフィールドを使用すると、null値がソース証跡ファイルでnullである(値はfalse)か、ソース証跡ファイルにない(値はtrue)かを、ダウンストリーム・アプリケーションが区別できるようになります。
gg.handler.name.format.oracleNumberScale	オプション	0から38までの任意の整数値。	なし	Avro decimalデータ型のスケールを設定できます。enableDecimalLogicalType=trueを設定した場合にのみ適用されます。Oracle NUMBERは、変数の精度とスケールをサポートするOracle Database固有の数値データ型です。精度とスケールは、Oracle NUMBERデータ型のインスタンスごとの変数です。精度とスケールは、Avro decimal論理型を生成する場合の必須パラメータです。これにより、Oracle NUMBERデータ型からAvroへのマッピングが難しくなります。Avroスキーマの生成時にOracle NUMBERデータ型の精度とスケールを確定する方法がないからです。最良の代替方法は、Oracle NUMBERの有効なインスタンスを保持できる、精度164およびスケール38の大きなAvro decimalデータ型を生成することです。これにより、Oracle Numberデータ型をAvro decimalデータ型に変換する際の精度損失の問題は解消されますが、Avroメッセージ・ダウンストリームから取得されたときのAvro decimalデータ型が小数点以下38桁であることが望ましくない場合があります。
gg.handler.name.format.mapOracleNumbersAsStrings	オプション	true | false	false	このプロパティは、プロパティgg.handler.name.format.enableDecimalLogialType=trueを介して小数論理型が有効になっている場合にのみ適用されます。Oracleの数値は、高精度(168)と最大38の浮動スケールがあるため、特に問題があります。Sparkなどの一部の分析ツールは、そこまで大きな数値を読み取ることができません。このプロパティを使用すると、これらのOracle数値を文字列としてマップでき、小さい数値を小数論理型としてマッピングできます。
gg.handler.name.format.enableTimestampLogicalType	オプション	true | false	false	ソースのdateおよびtimeデータ型をAvro TimestampMicros論理データ型にマップするには、trueに設定します。gghandler.name.format.enableTimestampLogicalTypeがtrueに設定されており、gg.format.timestampが設定されていない場合、Replicatは構成例外で異常終了します。ソースのdateおよびtimeデータ型の意味をなすマスクを提供するように、変数gg.format.timestampを構成する必要があります。Avro TimestampMicrosは、Avro 1.8仕様に含まれています。
gg.handler.name.format.enableDecimalLogicalType	オプション	true | false	false	Avro decimal論理型の使用を有効にします。小数論理型は、数値をバイト配列として表し、従来の64ビット長またはdoubleデータ型に収まるよりも大きな数のサポートを提供できます。
gg.handler.name.format.mapLargeNumbersAsStrings	オプション	true | false	false	Oracle GoldenGateでは、浮動小数点および整数ソース・データ型がサポートされます。これらのデータ型の中には、Avroプリミティブのdoubleまたはlongデータ型に適合しないものもあります。Avroプリミティブのdoubleまたはlongデータ型に適合しないフィールドをAvro文字列にマップするには、このプロパティをtrueに設定します。
gg.handler.name.format.metaColumnsTemplate	オプション	「メタ列のキーワード」を参照してください	なし	現在のメタ列情報を簡単な方法で構成でき、使用する明示的な必要性が排除されます。 insertOpKey | updateOpKey | deleteOpKey | truncateOpKey | includeTableName | includeOpTimestamp | includeOpType | includePosition | includeCurrentTimestamp, useIso8601Format これは、テンプレートを表す1つ以上のテンプレート化された値で構成されているカンマ区切りの文字列です。 メタ列のキーワードの詳細は、メタ列のキーワードを参照してください。
gg.handler.name.format.maxPrecision	オプション	なし	正の整数	Avro 10進数論理型の最大精度を設定できます。アプリケーションの消費には、Avroの精度に制限がある場合があります(Apache Sparkでのサポートは最大精度38です)。 警告: このプロパティの構成はリスクがないわけではありません。 Oracle RDBMSのNUMBER型のサポートは、最大精度164です。このプロパティの構成は、大きいソース数値型を小さいターゲット数値型にキャストしている可能性があります。ソース値の精度が構成済の精度より大きい場合、実行時例外が発生し、Replicatプロセスが異常終了します。この動作はバグではありません。これは予期された動作です。

8.2.31.5.2.2.6 サンプル構成の確認

Javaアダプタproperg.handlertiesファイルのAvro操作フォーマッタのサンプル構成を次に示します。

gg.handler.hdfs.format=avro_op
gg.handler.hdfs.format.insertOpKey=I
gg.handler.hdfs.format.updateOpKey=U
gg.handler.hdfs.format.deleteOpKey=D
gg.handler.hdfs.format.truncateOpKey=T
gg.handler.hdfs.format.encoding=UTF-8
gg.handler.hdfs.format.wrapMessageInGenericAvroMessage=false

8.2.31.5.2.2.7 メタデータ変更イベント

複製されるデータベースとアップストリームのOracle GoldenGateレプリケーション・プロセスでメタデータ変更イベントを伝播できる場合、メタデータが変更されたときにAvro操作フォーマッタはアクションを実行できます。Avroメッセージは対応するスキーマに緊密に依存しているため、Avroフォーマットを使用する場合、メタデータの変更は重要です。

メタデータ変更イベント後に表操作が発生するとすぐに更新されたAvroスキーマが生成されます。

メタデータ変更イベントの影響を理解して、ダウンストリーム・ターゲットを新しいAvroスキーマに変更する必要があります。AvroメッセージがAvroスキーマに密に依存している場合、互換性の問題が生じることがあります。スキーマ変更の前に生成されるAvroメッセージを、新たに生成されたAvroスキーマでデシリアライズすることはできません。逆に、スキーマ変更の後で生成されるAvroメッセージを、前に生成されたAvroスキーマでデシリアライズすることもできません。ベスト・プラクティスとして、メッセージの生成に使用されたのと同じバージョンのAvroスキーマを使用するようにしてください

詳細は、Apache Avroのドキュメントを参照してください。

8.2.31.5.2.2.8 特別な考慮事項

この項では、次の特別な考慮事項について説明します。

• トラブルシューティング
  
• 主キーの更新
  
• 汎用のラッパー・メッセージ
  

8.2.31.5.2.2.8.1 トラブルシューティング

Avroはバイナリ形式なので、人間が読める形式ではありません。ただし、log4j Javaロギング・レベルをTRACEに設定すると、Avroメッセージがデシリアライズされ、ログ・ファイルにJSONオブジェクトとして表示されるため、作成されたAvroメッセージの構造および内容を確認できます。TRACEは、パフォーマンスに大きい影響を及ぼすため、本番環境では有効にしないでください。

8.2.31.5.2.2.8.2 主キーの更新

Avro操作フォーマッタは、更新操作の操作前イメージと操作後イメージの完全なデータを使用してメッセージを作成します。したがって、Avro操作フォーマッタでは、主キーの更新について特別な処理は必要ありません。

8.2.31.5.2.2.8.3 汎用のラッパー・メッセージ

Avroメッセージは自己記述型ではないため、メッセージの受信者は、メッセージに対応するスキーマのことを知っていないと、メッセージをデシリアライズできません。Avroメッセージはバイナリであり、メッセージの内容を調べてメッセージ・タイプを確定する一貫した、または信頼できる方法はありません。したがって、Kafkaのような1つのデータ・ストリームにメッセージをインタレースするときに、Avroは厄介です。

Avroフォーマッタには、汎用のAvroメッセージでAvroメッセージをラップする特別な機能があります。この機能を有効にするには、次の構成プロパティを設定します。

gg.handler.name.format.wrapMessageInGenericAvroMessage=true

汎用のメッセージとは、出力されるAvroメッセージすべてに共通するAvroペイロード・メッセージをラップするAvroメッセージです。汎用メッセージのスキーマは、generic_wrapper.avscという名前で、出力スキーマ・ディレクトリに書き込まれます。このメッセージには、次の3つのフィールドがあります。

• table_name: 完全修飾のソース表名。

• schema_fingerprint : メッセージを生成するAvroスキーマのフィンガープリント。フィンガープリントは、org.apache.avro.SchemaNormalizationクラスのparsingFingerprint64(Schema s)メソッドを使用して生成されます。

• payload: ラップされるAvroメッセージ。

Avroフォーマッタの汎用ラッパー・スキーマは、次のとおりです。

{
  "type" : "record",
  "name" : "generic_wrapper",
  "namespace" : "oracle.goldengate",
  "fields" : [ {
    "name" : "table_name",
    "type" : "string"
  }, {
    "name" : "schema_fingerprint",
    "type" : "long"
  }, {
    "name" : "payload",
    "type" : "bytes"
  } ]
}

8.2.31.5.2.3 Avroオブジェクト・コンテナ・ファイル・フォーマッタ

Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)では、Avroオブジェクト・コンテナ・ファイル(OCF)形式でHDFSに書き込むことができます。Avro OCFは、スキーマ展開を他の形式よりも効率的に処理します。また、Avro OCFフォーマッタでは圧縮および圧縮解除もサポートされ、ディスク領域をより効率的に使用できます。

HDFSハンドラはAvroフォーマッタと統合されており、Avro OCF形式でHDFSにファイルを書き込みます。Avro OCF形式は、HiveではHDFSでAvroデータを読み取るために必要です。Avro OCF形式の詳細は、Avro仕様に記載されています。http://avro.apache.org/docs/current/spec.html#Object+Container+Filesを参照してください。

データをAvro OCF形式でストリーミングし、Hiveで表定義を生成し、メタデータ変更イベントが発生した場合はHiveで表定義を更新するようHDFSハンドラを構成できます。

• Avro OCFフォーマッタの構成プロパティ
  

8.2.31.5.2.3.1 Avro OCFフォーマッタの構成プロパティ

プロパティ	オプション/必須	有効な値	デフォルト	説明
gg.handler.name.format.insertOpKey	オプション	任意の文字列	I	出力レコードに挿入され、挿入操作を示す指標です。
gg.handler.name.format.updateOpKey	オプション	任意の文字列	U	出力レコードに挿入され、更新操作を示す指標です。
gg.handler.name.format.truncateOpKey	オプション	任意の文字列	T	出力レコードに切り捨てられ、切捨て操作を示す指標です。
gg.handler.name.format.deleteOpKey	オプション	任意の文字列	D	出力レコードに挿入され、切捨て操作を示す指標です。
gg.handler.name.format.encoding	オプション	Javaでサポートされる任意の有効なエンコーディング名または別名。	UTF-8	生成されるJSON Avroスキーマの出力エンコーディングを制御します。JSONのデフォルトはUTF-8です。Avroメッセージはバイナリで、独自の内部形式でエンコーディングをサポートしています。
gg.handler.name.format.treatAllColumnsAsStrings	オプション	true | false	false	生成されるAvroメッセージの出力の型付けを制御します。falseに設定すると、フォーマッタはOracle GoldenGateの型を、対応するAvroの型にマップしようとします。trueに設定すると、すべてのデータは生成されるAvroメッセージとスキーマで文字列として扱われます。
gg.handler.name.format.pkUpdateHandling	オプション	abend | update | delete-insert	abend	フォーマッタが、主キーを変更する更新操作をどのように処理するかを制御します。主キーを操作するとAvro行フォーマッタで問題が起きることがあるので、ユーザーは特に慎重を期する必要があります。 abend : プロセスが終了します。 update : プロセスはこれを通常の更新として処理します deleteおよびinsert: プロセスはこの操作を削除および挿入として処理します。この機能が正常に動作するためには、完全な操作前イメージが必要です。そのためには、Oracleで完全なサプリメンタル・ロギングを使用します。操作前と操作後の完全な行イメージがない場合、挿入データは不完全になります。
gg.handler.name.format.generateSchema	オプション	true | false	true	Avroのシリアライズのためにスキーマを生成する必要があるため、falseに設定して、ローカル・ファイル・システムへの生成されたスキーマの書込みを抑止できます。
gg.handler.name.format.schemaDirectory	オプション	有効で存在する人気のファイル・システム・パス	./dirdef	生成されたAvroスキーマが保存されるローカル・ファイル・システムのディレクトリ。このプロパティは、Avroスキーマが書き込まれるHDFSの場所を制御しません。この場所はHDFSハンドラ・プロパティで制御されます。
gg.handler.name.format.iso8601Format	オプション	true | false	true	デフォルトでは、このプロパティの値はtrueで、現在のタイムスタンプの形式はISO8601です。falseに設定すると、現在のタイムスタンプの日付と時刻の間のTが削除され、かわりにスペースが出力されます。
gg.handler.name.format.versionSchemas	オプション	true | false	false	trueに設定すると、Avroスキーマがスキーマ・ディレクトリに作成されて、タイムスタンプでバージョン管理されます。スキーマには、次の形式を使用します。 fully_qualifiedtable_name_time stamp.avsc

8.2.31.5.3 区切りテキスト・フォーマッタの使用

区切りテキスト・フォーマッタは、ソース証跡ファイルから、データベース操作の内容を、区切りテキスト出力としてフォーマットします。ソース証跡からの挿入、更新、削除または切捨ての各操作は、区切られた個々のメッセージとしてフォーマットされます。区切りテキスト出力は、各表に対して固定数のフィールドがあり、フィールド区切り文字によって区切られ、最後が行区切り文字になります。フィールドは、位置が関係します。Hiveを含め多くのOracle GoldenGate for Distributed Applications and Analytics (GG for DAA)分析ツールは、区切りテキストを含むHDFSファイルで適切に機能します。ソース証跡ファイルからの操作の列値は、列に値がある、列値がnullである、列値がないの3つの状態のいずれかです。デフォルトでは、区切りテキストはこれらの列値状態を区切りテキスト出力に次のようにマップします。

• 列値がある: 列値が出力されます。

• 列値がnullである: デフォルトの出力値はNULLです。列値がnullの場合の出力は、設定を変更できます。

• 列値がない: デフォルトの出力値は空の文字列("")です。列値がない場合の出力は、設定を変更できます。

• 区切りテキスト行フォーマッタの使用
  区切りテキスト行フォーマッタは、Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA) 19.1.0.0.0リリースより前のリリースに含まれていた区切りテキスト・フォーマッタです。これは、挿入および更新の場合は変更後のデータを書き込み、削除の場合は変更前のデータを書き込みます。
• 区切りテキスト操作フォーマッタ
  区切りテキスト操作フォーマッタでは、挿入、更新および削除操作の変更前データと変更後データの両方が出力されます。

8.2.31.5.3.1 区切りテキスト行フォーマッタの使用

区切りテキスト行フォーマッタは、Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA) 19.1.0.0.0リリースより前のリリースに含まれていた区切りテキスト・フォーマッタです。これは、挿入および更新の場合は変更後のデータを書き込み、削除の場合は変更前のデータを書き込みます。

• メッセージのフォーマットの詳細
  
• フォーマットしたメッセージの例
  
• 出力形式サマリーのログ
  
• 構成
  
• メタデータ変更イベント
  
• その他の考慮事項
  

8.2.31.5.3.1.1 メッセージのフォーマットの詳細

生成された区切りテキスト・メッセージ内のメタ列フィールドの自動出力は、Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)リリース21.1以降では削除されています。メタ列フィールドは出力可能ですが、次のプロパティとして明示的に構成する必要があります:

gg.handler.name.format.metaColumnsTemplate

メタ列を以前のバージョンと同様に出力するには、次のように構成します。

gg.handler.name.format.metaColumnsTemplate=${optype[op_type]},${objectname[table]},${timestamp[op_ts]},${currenttimestamp[current_ts]},${position[pos]}

主キー列およびトークンも含めるには、次のように構成します。

gg.handler.name.format.metaColumnsTemplate=${optype[op_type]},${objectname[table]},${timestamp[op_ts]},${currenttimestamp[current_ts]},${position[pos]},${primarykeycolumns[primary_keys]},${alltokens[tokens]}

詳細は、次の章を参照してください。

「区切りテキスト・フォーマッタの構成プロパティ」表の構成プロパティgg.handler.name.format.metaColumnsTemplateを参照してください。

フォーマットの詳細:

• 操作タイプ : ソース証跡ファイルのデータベース操作のタイプを示します。デフォルト値は挿入を表すI、更新を表すU、削除を表すD、切捨てを表すTです。このフィールドの出力は、抑止できます。

• 完全修飾の表名: 完全修飾の表名はソース・データベース表で、カタログ名とスキーマ名が含まれます。完全修飾の表名の形式は、catalog_name.schema_name.table_nameです。このフィールドの出力は抑止できます。

• 操作のタイムスタンプ : ソース・システムのコミット・レコードのタイムスタンプ。トランザクション(バッチ処理以外のトランザクション)のすべての操作は、操作タイムスタンプが同じになります。このタイムスタンプは固定で、証跡ファイルを再生する場合、操作のタイムスタンプは同じです。このフィールドの出力は抑止できます。

• 現在のタイムスタンプ : 区切りテキスト・フォーマッタが現在の操作レコードを処理した現在時刻のタイムスタンプ。このタイムスタンプはISO-8601形式に従い、精度はミリ秒までです。証跡ファイルを再生しても、同じ操作に対して同じタイムスタンプにはなりません。このフィールドの出力は抑止できます。

• 証跡のポジション: 連結された連番およびソース証跡ファイルのRBA番号。証跡のポジションにより、操作からソース証跡ファイルをたどることができます。この連番は、ソース証跡ファイルの番号です。RBA番号は、証跡ファイルのオフセットです。このフィールドの出力は抑止できます。

• トークン : ソース証跡ファイルのトークン・キー値ペア。対応するハンドラのincludeTokens構成プロパティが明示的にtrueに設定されていない場合、区切りテキスト出力のこのフィールドの出力は表示されません。

8.2.31.5.3.1.2 フォーマットしたメッセージの例

次の各項では、区切りテキスト・フォーマッタのサンプル・メッセージを示します。メッセージを明確に表示するために、デフォルトのフィールド区切り文字がパイプ文字(|)に変更されています。

• 挿入メッセージの例
  
• 更新メッセージの例
  
• 削除メッセージの例
  
• 切捨てメッセージの例
  

8.2.31.5.3.1.2.1 挿入メッセージの例

I|GG.TCUSTORD|2013-06-02
22:14:36.000000|2015-09-18T13:23:01.612001|00000000000000001444|R=AADPkvAAEAAEqL2A
AA|WILL|1994-09-30:15:33:00|CAR|144|17520.00|3|100

8.2.31.5.3.1.2.2 更新メッセージの例

U|GG.TCUSTORD|2013-06-02
22:14:41.000000|2015-09-18T13:23:01.987000|00000000000000002891|R=AADPkvAAEAAEqLzA
AA|BILL|1995-12-31:15:00:00|CAR|765|14000.00|3|100

8.2.31.5.3.1.2.3 削除メッセージの例

D,GG.TCUSTORD,2013-06-02
22:14:41.000000,2015-09-18T13:23:02.000000,00000000000000004338,L=206080450,6=9.0.
80330,R=AADPkvAAEAAEqLzAAC,DAVE,1993-11-03:07:51:35,PLANE,600,,,

8.2.31.5.3.1.2.4 切捨てメッセージの例

T|GG.TCUSTORD|2013-06-02
22:14:41.000000|2015-09-18T13:23:02.001000|00000000000000004515|R=AADPkvAAEAAEqL2A
AB|||||||

8.2.31.5.3.1.3 出力形式サマリーのログ

INFOレベルのロギングが有効になっている場合、Java log4jのロギングでは、区切りテキスト出力形式のサマリーが記録されます。区切りフィールドのサマリーは、確認されたソース表ごとに記録され、その表に対する最初の操作が区切りテキスト・フォーマッタによって受け取られたときに発生します。区切りテキスト出力のフィールドに関するこうした詳細な説明は、初期設定を実行するときに役立つ場合があります。メタデータ変更イベントが発生した場合、区切りフィールドのサマリーが再生成され、その表に対する最初の後続操作で再度記録されます。

8.2.31.5.3.1.4 構成

• サンプル構成の確認
  

8.2.31.5.3.1.4.1 サンプル構成の確認

Javaアダプタ構成ファイルの区切りテキスト・フォーマッタのサンプル構成を次に示します。

gg.handler.name.format.includeColumnNames=false
gg.handler.name.format.insertOpKey=I
gg.handler.name.format.updateOpKey=U
gg.handler.name.format.deleteOpKey=D
gg.handler.name.format.truncateOpKey=T
gg.handler.name.format.encoding=UTF-8
gg.handler.name.format.fieldDelimiter=CDATA[\u0001]
gg.handler.name.format.lineDelimiter=CDATA[\n]
gg.handler.name.format.keyValueDelimiter=CDATA[=]
gg.handler.name.format.kevValuePairDelimiter=CDATA[,]
gg.handler.name.format.pkUpdateHandling=abend
gg.handler.name.format.nullValueRepresentation=NULL
gg.handler.name.format.missingValueRepresentation=CDATA[]
gg.handler.name.format.includeGroupCols=false
gg.handler.name.format=delimitedtext

8.2.31.5.3.1.5 メタデータ変更イベント

Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)で、実行時にメタデータ変更イベントが処理されるようになりました。これは、複製されるデータベースとアップストリームのレプリケーション・プロセスでメタデータ変更イベントが伝播されると想定しています。区切りテキスト・フォーマッタは、変更を反映して出力形式を変更し、実行を続行します。

ノート:

メタデータの変更はダウンストリーム・アプリケーションに影響を与える可能性があります。区切りテキスト形式には、位置の関係を持つ固定数のフィールドが含まれます。ソース表での列の削除は、Oracle GoldenGateの実行時にシームレスに処理できますが、フィールドの合計数が変わることになるため、一部のフィールドの位置関係が変わる可能性があります。新しい列は最後に追加されると想定されるため、列(単数または複数)の追加は、メタデータ変更イベントの中でも影響が最も小さいと考えられます。メタデータ変更イベントを実行する前に、そのイベントの影響を考慮してください。メタデータ変更イベントが頻繁に発生する場合は、JSONやXMLなどの、より柔軟で自己記述型のフォーマットを検討することをお薦めします。

8.2.31.5.3.1.6 その他の考慮事項

フィールドおよび行区切り文字を選択するときは、十分に注意してください。データの内容に出現しない区切り文字を選択することが重要です。

空白と見なされる構成値の先行文字と後続文字は、Javaアダプタ構成によって削除されます。ただし、含めるまたは完全に空白と見なされる、フィールド区切り文字、行区切り文字、null値形式および欠落値形式を選択する必要がある場合があります。この場合、空白を維持するJavaアダプタ構成ファイルに特殊な構文を使用する必要があります。構成値に空白と見なされる先行文字または後続文字が含まれている場合にその空白を維持するには、CDATA[]ラッパーで構成値をラップします。たとえば、\nという構成値はCDATA[\n]として構成します。

正規表現を使用して列値を検索してから、一致項目を指定した値に置き換えることができます。この検索および置換機能を区切りテキスト・フォーマッタとともに使用し、列値の内容とフィールドおよび行区切り文字の間に不一致がないことを確認できます。詳細は、「正規表現を使用した検索と置換」を参照してください。

Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)アプリケーションでは、RDBMSとは異なる方法でデータが格納されます。RDBMSで更新操作と削除操作を行うと、既存のデータが変更されます。ただし、GG for DAAアプリケーションでは、データは変更されるのではなく追加されます。したがって、特定の行の現在の状態は、HDFSシステムにおけるその行に対する既存の操作がすべて統合された結果になります。これにより、次の各項で説明するような特別なシナリオが発生します。

• 主キーの更新
  
• データの統合
  

8.2.31.5.3.1.6.1 主キーの更新

Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)統合では、主キーの更新操作には特別な考慮と計画が必要です。主キーの更新では、ソース・データベースの特定の行の1つ以上の主キーを変更します。GG for DAAアプリケーションにおいてはデータは追加されるため、主キーの更新操作は、特別な処理がない更新というより挿入に似ています。区切りテキスト・フォーマッタが主キーの更新を処理する方法を構成できます。設定変更が可能な動作は次のとおりです。

表8-45 構成可能な動作

値	説明
abend	デフォルトでは、主キーが更新されると、区切りテキスト・フォーマッタは終了します。
update	主キーの更新は、他の更新操作と同じように処理されます。この構成は、GG for DAAシステムから行データを選択する際の選択基準として主キーが使用されないと間違いなくわかっている場合のみ使用してください。
delete-insert	主キーの更新は、操作前イメージのデータを使用する削除と、操作後イメージのデータを使用する挿入という特殊なケースとして処理されます。この構成では、GG for DAAアプリケーションでの主キー更新の影響がより正確にモデル化される場合があります。ただし、この構成を選択する場合は、ソース・データベースでのレプリケーションで完全なサプリメンタル・ロギングを有効にすることが重要です。完全なサプリメンタル・ロギングを有効にしない場合、削除操作は正常に処理されますが、挿入操作では、GG for DAAアプリケーションにおける行データの完全表現のためにすべての列のすべてのデータが含まれるわけではありません。

8.2.31.5.3.1.6.2 データの統合

Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)アプリケーションでは、基礎となるストレージにデータが追加されます。分析ツールは通常、データ・ファイルを横断して、特定の行の操作をすべて1つの出力に統合するMapReduceプログラムを生成します。したがって、操作順序を指定することが重要です。区切りテキスト・フォーマッタには、これを行う多くのメタデータ・フィールドがあります。この要件を満たすには、操作のタイムスタンプでも十分です。また、現在のタイムスタンプは操作順序の指標として最適な場合があります。この状況では、証跡のポジションは、操作のタイムスタンプに関する判別基準のフィールドになります。さらに、現在のタイムスタンプは、GG for DAAにおける操作順序の指標として最適である場合があります。

8.2.31.5.3.2 区切りテキスト操作フォーマッタ

区切りテキスト操作フォーマッタでは、挿入、更新および削除操作の変更前データと変更後データの両方が出力されます。

• メッセージのフォーマットの詳細
  
• フォーマットしたメッセージの例
  
• 出力形式サマリーのログ
  
• 区切りテキスト・フォーマッタの構成プロパティ
  
• サンプル構成の確認
  
• メタデータ変更イベント
  Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)で、実行時にメタデータ変更イベントが処理されるようになりました。これは、複製されるデータベースとアップストリームのレプリケーション・プロセスでメタデータ変更イベントが伝播されると想定しています。区切りテキスト・フォーマッタは、変更を反映して出力形式を変更し、実行を続行します。
• その他の考慮事項
  フィールドおよび行区切り文字を選択するときは、十分に注意してください。データの内容に出現しない区切り文字を選択することが重要です。

8.2.31.5.3.2.1 メッセージのフォーマットの詳細

生成された区切りテキスト・メッセージ内のメタ列フィールドの自動出力は、Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)リリース21.1以降では削除されています。メタ列フィールドは出力可能ですが、次のプロパティとして明示的に構成する必要があります: gg.handler.name.format.metaColumnsTemplate。詳細は、「区切りテキスト・フォーマッタの構成プロパティ」表の構成プロパティgg.handler.name.format.metaColumnsTemplateを参照してください。

メタ列を以前のバージョンと同様に出力するには、次のように構成します。

gg.handler.name.format.metaColumnsTemplate=${optype[op_type]},${objectname[table]},${timestamp[op_ts]},${currenttimestamp[current_ts]},${position[pos]}

主キー列およびトークンも含めるには、次のように構成します。

gg.handler.name.format.metaColumnsTemplate=${optype[op_type]},${objectname[table]},${timestamp[op_ts]},${currenttimestamp[current_ts]},${position[pos]},${primarykeycolumns[primary_keys]},${alltokens[tokens]}

フォーマットの詳細:

• 操作タイプ : ソース証跡ファイルのデータベース操作のタイプを示します。デフォルト値は挿入を表すI、更新を表すU、削除を表すD、切捨てを表すTです。このフィールドの出力は、抑止できます。

• 完全修飾の表名: 完全修飾の表名はソース・データベース表で、カタログ名とスキーマ名が含まれます。完全修飾の表名の形式は、catalog_name.schema_name.table_nameです。このフィールドの出力は抑止できます。

• 操作のタイムスタンプ : ソース・システムのコミット・レコードのタイムスタンプ。トランザクション(バッチ処理以外のトランザクション)のすべての操作は、操作タイムスタンプが同じになります。このタイムスタンプは固定で、証跡ファイルを再生する場合、操作のタイムスタンプは同じです。このフィールドの出力は抑止できます。

• 現在のタイムスタンプ : 区切りテキスト・フォーマッタが現在の操作レコードを処理した現在時刻のタイムスタンプ。このタイムスタンプはISO-8601形式に従い、精度はミリ秒までです。証跡ファイルを再生しても、同じ操作に対して同じタイムスタンプにはなりません。このフィールドの出力は抑止できます。

• 証跡のポジション: 連結された連番およびソース証跡ファイルのRBA番号。証跡のポジションにより、操作からソース証跡ファイルをたどることができます。この連番は、ソース証跡ファイルの番号です。RBA番号は、証跡ファイルのオフセットです。このフィールドの出力は抑止できます。

• トークン : ソース証跡ファイルのトークン・キー値ペア。対応するハンドラのincludeTokens構成プロパティが明示的にtrueに設定されていない場合、区切りテキスト出力のこのフィールドの出力は表示されません。

8.2.31.5.3.2.2 フォーマットしたメッセージの例

次の各項では、区切りテキスト・フォーマッタのサンプル・メッセージを示します。メッセージを明確に表示するために、デフォルトのフィールド区切り文字がパイプ文字(|)に変更されています。

• 挿入メッセージの例
  
• 更新メッセージの例
  
• 削除メッセージの例
  
• 切捨てメッセージの例
  

8.2.31.5.3.2.2.1 挿入メッセージの例

I|GG.TCUSTMER|2015-11-05 18:45:36.000000|2019-04-17T04:49:00.156000|00000000000000001956|R=AAKifQAAKAAAFDHAAA,t=,L=7824137832,6=2.3.228025||WILL||BG SOFTWARE CO.||SEATTLE||WA

8.2.31.5.3.2.2.2 更新メッセージの例

U|QASOURCE.TCUSTMER|2015-11-05
18:45:39.000000|2019-07-16T11:54:06.008002|00000000000000005100|R=AAKifQAAKAAAFDHAAE|ANN|ANN|ANN'S
BOATS||SEATTLE|NEW YORK|WA|NY

8.2.31.5.3.2.2.3 削除メッセージの例

D|QASOURCE.TCUSTORD|2015-11-05 18:45:39.000000|2019-07-16T11:54:06.009000|00000000000000005272|L=7824137921,R=AAKifSAAKAAAMZHAAE,6=9.9.479055|DAVE||1993-11-03 07:51:35||PLANE||600||135000.00||2||200|

8.2.31.5.3.2.2.4 切捨てメッセージの例

T|QASOURCE.TCUSTMER|2015-11-05 18:45:39.000000|2019-07-16T11:54:06.004002|00000000000000003600|R=AAKifQAAKAAAFDHAAE||||||||

8.2.31.5.3.2.3 出力形式サマリーのログ

INFOレベルのロギングが有効になっている場合、Java log4jのロギングでは、区切りテキスト出力形式のサマリーが記録されます。区切りフィールドのサマリーは、確認されたソース表ごとに記録され、その表に対する最初の操作が区切りテキスト・フォーマッタによって受け取られたときに発生します。区切りテキスト出力のフィールドに関するこうした詳細な説明は、初期設定を実行するときに役立つ場合があります。メタデータ変更イベントが発生した場合、区切りフィールドのサマリーが再生成され、その表に対する最初の後続操作で再度記録されます。

8.2.31.5.3.2.4 区切りテキスト・フォーマッタの構成プロパティ

表8-46 区切りテキスト・フォーマッタの構成プロパティ

プロパティ	オプション/必須	有効な値	デフォルト	説明
gg.handler.name.format	必須	delimitedtext_op	なし	区切りテキスト操作フォーマッタをフォーマッタとして選択します。
gg.handler.name.format.includeColumnNames	オプション	true | false	false	列値に先行する区切りフィールドとして列名を書き込む出力を制御します。trueの場合、出力は次のようになります。 COL1_Name|COL1_Before_Value|COL1_After_Value|COL2_Name|COL2_Before_Value|COL2_After_Value falseの場合、出力は次のようになります。 COL1_Before_Value|COL1_After_Value|COL2_Before_Value|COL2_After_Value
gg.handler.name.format.disableEscaping	オプション	true | false	false	構成された区切り文字と競合する文字のエスケープを無効にするには、trueに設定します。gg.handler.name.format.fieldDelimiterが複数の文字の値に設定されている場合は、trueに設定する必要があります。
gg.handler.name.format.insertOpKey	オプション	任意の文字列	I	出力レコードに挿入され、挿入操作を示す指標です。
gg.handler.name.format.updateOpKey	オプション	任意の文字列	U	出力レコードに挿入され、更新操作を示す指標です。
gg.handler.name.format.deleteOpKey	オプション	任意の文字列	D	出力レコードに挿入され、削除操作を示す指標です。
gg.handler.name.format.truncateOpKey	オプション	任意の文字列	T	出力レコードに挿入され、切捨て操作を示す指標です。
gg.handler.name.format.encoding	オプション	Javaでサポートされる任意のエンコーディング名または別名。	Oracle GoldenGateプロセスをホストしているマシンのネイティブのシステム・エンコーディング。	出力される区切りテキストのエンコーディングを決定します。
gg.handler.name.format.fieldDelimiter	オプション	任意の文字列	ASCII 001 (デフォルトのHive区切り文字)	区切りフィールド間に使用される区切り文字。この値はCDATA[]ラッピングをサポートします。複数の文字のデリミタが構成されている場合、エスケープは自動的に無効になります。
gg.handler.name.format.lineDelimiter	オプション	任意の文字列	改行 (デフォルトのHive区切り文字)	区切りフィールド間に使用される区切り文字。この値はCDATA[]ラッピングをサポートします。
gg.handler.name.format.keyValueDelimiter	オプション	任意の文字列	=	マップにおけるキーと値の間の区切り文字を指定します。Key1=value1。トークンはマップされた値です。構成値はCDATA[]ラッピングをサポートします。
gg.handler.name.format.keyValuePairDelimiter	オプション	任意の文字列	,	マップにおけるキー値ペアの間の区切り文字を指定します。Key1=Value1,Key2=Value2。トークンはマップされた値です。構成値は、CDATA[]ラッピングをサポートします。
gg.handler.name.format.nullValueRepresentation	オプション	任意の文字列	NULL	NULL値の場合に区切り出力に含まれる内容を指定します。構成値はCDATA[]ラッピングをサポートします。
gg.handler.name.format.missingValueRepresentation	オプション	任意の文字列	""(値なし)	値がない場合に区切りテキスト出力に含まれる内容を指定します。構成値はCDATA[]ラッピングをサポートします。
gg.handler.name.format.includeMetaColumnNames	オプション	true | false	false	trueに設定すると、各メタデータ列値の前にフィールドが追加されます。これは、メタデータ列の列名です。これを使用して、区切られたメッセージを自己記述型にすることができます。
gg.handler.name.format.wrapStringsInQuotes	オプション	true | false	false	trueに設定すると、区切りテキスト形式の文字列値の出力を二重引用符(")でラップします。
gg.handler.name.format.includeGroupCols	オプション	true | false	false	trueに設定されている場合、列は、すべての名前のセット、すべてのビフォア値のセットおよびすべてのアフター値のセットにグループ化されます U,QASOURCE.TCUSTMER,2015-11-05 18:45:39.000000,2019-04-17T05:19:30.556000,00000000000000005100,R=AAKifQAAKAAAFDHAAE,CUST_CODE,NAME,CITY,STATE,ANN,ANN'S BOATS,SEATTLE,WA,ANN,,NEW YORK,NY
gg.handler.name.format.enableFieldDescriptorHeaders	オプション	true | false	false	trueに設定すると、区切りテキスト出力用の説明ヘッダーが各データ・ファイルに追加されます。ヘッダーは、フィールド・デリミタで区切られた個々のフィールド名になります。
gg.handler.name.format.metaColumnsTemplate	オプション	「メタ列のキーワード」を参照してください。	なし	現在のメタ列情報を簡単な方法で構成でき、使用する明示的な必要性が排除されます。 insertOpKey | updateOpKey | deleteOpKey | truncateOpKey | includeTableName | includeOpTimestamp | includeOpType | includePosition | includeCurrentTimestamp, useIso8601Format これは、テンプレートを表す1つ以上のテンプレート化された値で構成されているカンマ区切りの文字列です。メタ列のキーワードの詳細は、メタ列のキーワードを参照してください。これは、メタ列のリストを生成する例です: ${optype}, ${token.ROWID}, ${sys.username}, ${currenttimestamp}

8.2.31.5.3.2.5 サンプル構成の確認

Javaアダプタ構成ファイルの区切りテキスト・フォーマッタのサンプル構成を次に示します。

gg.handler.name.format.includeColumnNames=false
gg.handler.name.format.insertOpKey=I
gg.handler.name.format.updateOpKey=U
gg.handler.name.format.deleteOpKey=D
gg.handler.name.format.truncateOpKey=T
gg.handler.name.format.encoding=UTF-8
gg.handler.name.format.fieldDelimiter=CDATA[\u0001]
gg.handler.name.format.lineDelimiter=CDATA[\n]
gg.handler.name.format.keyValueDelimiter=CDATA[=]
gg.handler.name.format.kevValuePairDelimiter=CDATA[,]
gg.handler.name.format.nullValueRepresentation=NULL
gg.handler.name.format.missingValueRepresentation=CDATA[]
gg.handler.name.format.includeGroupCols=false
gg.handler.name.format=delimitedtext_op

8.2.31.5.3.2.6 メタデータ変更イベント

Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)で、実行時にメタデータ変更イベントが処理されるようになりました。これは、複製されるデータベースとアップストリームのレプリケーション・プロセスでメタデータ変更イベントが伝播されると想定しています。区切りテキスト・フォーマッタは、変更を反映して出力形式を変更し、実行を続行します。

ノート:

メタデータの変更はダウンストリーム・アプリケーションに影響を与える可能性があります。区切りテキスト形式には、位置の関係を持つ固定数のフィールドが含まれます。ソース表での列の削除は、Oracle GoldenGateの実行時にシームレスに処理できますが、フィールドの合計数が変わることになるため、一部のフィールドの位置関係が変わる可能性があります。新しい列は最後に追加されると想定されるため、列(単数または複数)の追加は、メタデータ変更イベントの中でも影響が最も小さいと考えられます。メタデータ変更イベントを実行する前に、そのイベントの影響を考慮してください。メタデータ変更イベントが頻繁に発生する場合は、JSONやXMLなどの、より柔軟で自己記述型のフォーマットを検討することをお薦めします。

8.2.31.5.3.2.7 その他の考慮事項

フィールドおよび行区切り文字を選択するときは、十分に注意してください。データの内容に出現しない区切り文字を選択することが重要です。

空白と見なされる構成値の先行文字と後続文字は、Javaアダプタ構成によって削除されます。ただし、含めるまたは完全に空白と見なされる、フィールド区切り文字、行区切り文字、null値形式および欠落値形式を選択する必要がある場合があります。この場合、空白を維持するJavaアダプタ構成ファイルに特殊な構文を使用する必要があります。構成値に空白と見なされる先行文字または後続文字が含まれている場合にその空白を維持するには、CDATA[]ラッパーで構成値をラップします。たとえば、\nという構成値はCDATA[\n]として構成します。

正規表現を使用して列値を検索してから、一致項目を指定した値に置き換えることができます。この検索および置換機能を区切りテキスト・フォーマッタとともに使用し、列値の内容とフィールドおよび行区切り文字の間に不一致がないことを確認できます。詳細は、「正規表現を使用した検索と置換」を参照してください。

ビッグ・データ・アプリケーションは、データの格納方法がRDBMSとは異なります。RDBMSで更新操作と削除操作を行うと、既存のデータが変更されます。ただし、ビッグ・データ・アプリケーションでは、データを変更するのではなく追加します。したがって、特定の行の現在の状態は、HDFSシステムにおけるその行に対する既存の操作がすべて統合された結果になります。これにより、次の各項で説明するような特別なシナリオが発生します。

8.2.31.5.4 JSONフォーマッタの使用

JavaScript Object Notation (JSON)フォーマッタは、行ベースのフォーマットまたは操作ベースのフォーマットで、ソース証跡ファイルから操作を出力できます。ソース証跡ファイルから、操作データをJSONオブジェクトとしてフォーマットします。挿入、更新、削除および切捨ての各操作は、個々のJSONメッセージとしてフォーマットされます。

• 操作メタデータのフォーマットの詳細
  
• 操作データのフォーマットの詳細
  
• 行データのフォーマットの詳細
  
• JSONメッセージの例
  
• JSONスキーマ
  
• JSONフォーマッタの構成プロパティ
  
• サンプル構成の確認
  
• メタデータ変更イベント
  
• JSON主キーの更新
  
• Oracle Stream Analyticsの統合
  
• Mongoドキュメントのフォーマットの詳細
  

8.2.31.5.4.1 操作メタデータのフォーマットの詳細

メタ列を出力するには、次のように構成します。

gg.handler.name.format.metaColumnsTemplate=${objectname[table]},${optype[op_type]},${timestamp[op_ts]},${currenttimestamp[current_ts]},${position[pos]}

主キー列およびトークンも含めるには、次のように構成します。

gg.handler.name.format.metaColumnsTemplate=${objectname[table]},${optype[op_type]},${timestamp[op_ts]},${currenttimestamp[current_ts]},${position[pos]},${primarykeycolumns[primary_keys]},${alltokens[tokens]}

詳細は、構成プロパティgg.handler.name.format.metaColumnsTemplateを参照してください。

8.2.31.5.4.2 操作データのフォーマットの詳細

JSONメッセージは、操作メタデータ・フィールドから始まり、操作データ・フィールドが続きます。このデータは、オブジェクトであるbeforeおよびafterメンバーによって表されます。これらのオブジェクトには、キーが列名のメンバーおよび値が列値のメンバーが含まれます。

操作データは次のようにモデル化されます。

• 挿入: 操作後イメージのデータが含まれます。

• 更新: 操作前イメージと操作後イメージの両方のデータが含まれます。

• 削除: 操作前イメージのデータが含まれます。

ソース証跡ファイルからの操作の列値は、列に値がある、列値がnullである、列値がないの3つの状態のいずれかです。JSONフォーマッタは、これらの列値状態を、作成されたJSONオブジェクトに次のようにマップします。

• 列値がある: 列値が出力されます。次の例では、メンバーSTATEに値があります。

      "after":{        "CUST_CODE":"BILL",        "NAME":"BILL'S USED CARS",        "CITY":"DENVER",        "STATE":"CO"    }
  

• 列値がnullである: デフォルトの出力値はJSON NULLです。次の例では、メンバーSTATEはnullです。

      "after":{        "CUST_CODE":"BILL",        "NAME":"BILL'S USED CARS",        "CITY":"DENVER",        "STATE":null    }
  

• 列値がない: JSONには、列値がない場合は要素は含まれません。次の例では、メンバーSTATEがありません。

      "after":{        "CUST_CODE":"BILL",        "NAME":"BILL'S USED CARS",        "CITY":"DENVER",    }
  

JSONフォーマッタのデフォルト設定では、ソース証跡ファイルのデータ型を、対応するJSONデータ型にマップします。JSONでサポートされるデータ型は少ないため、この機能は通常、ソース証跡ファイルの数値フィールドを、数値として型付けされるメンバーにマップします。このデータ型マッピングは、すべてのデータを文字列として扱うように構成できます。

8.2.31.5.4.3 行データのフォーマットの詳細

JSONメッセージは、操作メタデータ・フィールドから始まり、操作データ・フィールドが続きます。行データのフォーマットの場合、これはJSONキー値ペアとしてのソース列名とソース列値です。このデータは、オブジェクトであるbeforeおよびafterメンバーによって表されます。これらのオブジェクトには、キーが列名のメンバーおよび値が列値のメンバーが含まれます。

行データは次のようにモデル化されます。

• 挿入: 操作後イメージのデータが含まれます。

• 更新: 操作後イメージのデータが含まれます。

• 削除: 操作前イメージのデータが含まれます。

ソース証跡ファイルからの操作の列値は、列に値がある、列値がnullである、列値がないの3つの状態のいずれかです。JSONフォーマッタは、これらの列値状態を、作成されたJSONオブジェクトに次のようにマップします。

• 列値がある: 列値が出力されます。次の例では、メンバーSTATEに値があります。

          "CUST_CODE":"BILL",        "NAME":"BILL'S USED CARS",        "CITY":"DENVER",        "STATE":"CO"    }
  

• 列値がnullである: デフォルトの出力値はJSON NULLです。次の例では、メンバーSTATEはnullです。

          "CUST_CODE":"BILL",        "NAME":"BILL'S USED CARS",        "CITY":"DENVER",        "STATE":null    }
  

• 列値がない: JSONには、列値がない場合は要素は含まれません。次の例では、メンバーSTATEがありません。

          "CUST_CODE":"BILL",        "NAME":"BILL'S USED CARS",        "CITY":"DENVER",    }
  

JSONフォーマッタのデフォルト設定では、ソース証跡ファイルのデータ型を、対応するJSONデータ型にマップします。JSONでサポートされるデータ型は少ないため、この機能は通常、ソース証跡ファイルの数値フィールドを、数値として型付けされるメンバーにマップします。このデータ型マッピングは、すべてのデータを文字列として扱うように構成できます。

8.2.31.5.4.4 JSONメッセージの例

次のトピックでは、挿入、更新、削除および切捨て操作に対してJSONフォーマッタによって作成されるJSONメッセージの例を示します。

• 操作モデル化JSONメッセージの例
  
• フラット化操作モデル化JSONメッセージの例
  
• 行モデル化JSONメッセージの例
  
• 主キー出力JSONメッセージの例
  

8.2.31.5.4.4.1 操作モデル化JSONメッセージの例

挿入

{
    "table":"QASOURCE.TCUSTORD",
    "op_type":"I",
    "op_ts":"2015-11-05 18:45:36.000000",
    "current_ts":"2016-10-05T10:15:51.267000",
    "pos":"00000000000000002928",
    "after":{
        "CUST_CODE":"WILL",
        "ORDER_DATE":"1994-09-30:15:33:00",
        "PRODUCT_CODE":"CAR",
        "ORDER_ID":144,
        "PRODUCT_PRICE":17520.00,
        "PRODUCT_AMOUNT":3,
        "TRANSACTION_ID":100
    }
}

更新

{
    "table":"QASOURCE.TCUSTORD",
    "op_type":"U",
    "op_ts":"2015-11-05 18:45:39.000000",
    "current_ts":"2016-10-05T10:15:51.310002",
    "pos":"00000000000000004300",
    "before":{
        "CUST_CODE":"BILL",
        "ORDER_DATE":"1995-12-31:15:00:00",
        "PRODUCT_CODE":"CAR",
        "ORDER_ID":765,
        "PRODUCT_PRICE":15000.00,
        "PRODUCT_AMOUNT":3,
        "TRANSACTION_ID":100
    },
    "after":{
        "CUST_CODE":"BILL",
        "ORDER_DATE":"1995-12-31:15:00:00",
        "PRODUCT_CODE":"CAR",
        "ORDER_ID":765,
        "PRODUCT_PRICE":14000.00
    }
}

削除

{
    "table":"QASOURCE.TCUSTORD",
    "op_type":"D",
    "op_ts":"2015-11-05 18:45:39.000000",
    "current_ts":"2016-10-05T10:15:51.312000",
    "pos":"00000000000000005272",
    "before":{
        "CUST_CODE":"DAVE",
        "ORDER_DATE":"1993-11-03:07:51:35",
        "PRODUCT_CODE":"PLANE",
        "ORDER_ID":600,
        "PRODUCT_PRICE":135000.00,
        "PRODUCT_AMOUNT":2,
        "TRANSACTION_ID":200
    }
}

切捨て

{
    "table":"QASOURCE.TCUSTORD",
    "op_type":"T",
    "op_ts":"2015-11-05 18:45:39.000000",
    "current_ts":"2016-10-05T10:15:51.312001",
    "pos":"00000000000000005480",
}

8.2.31.5.4.4.2 フラット化操作モデル化JSONメッセージの例

挿入

{
    "table":"QASOURCE.TCUSTORD",
    "op_type":"I",
    "op_ts":"2015-11-05 18:45:36.000000",
    "current_ts":"2016-10-05T10:34:47.956000",
    "pos":"00000000000000002928",
    "after.CUST_CODE":"WILL",
    "after.ORDER_DATE":"1994-09-30:15:33:00",
    "after.PRODUCT_CODE":"CAR",
    "after.ORDER_ID":144,
    "after.PRODUCT_PRICE":17520.00,
    "after.PRODUCT_AMOUNT":3,
    "after.TRANSACTION_ID":100
}

更新

{
    "table":"QASOURCE.TCUSTORD",
    "op_type":"U",
    "op_ts":"2015-11-05 18:45:39.000000",
    "current_ts":"2016-10-05T10:34:48.192000",
    "pos":"00000000000000004300",
    "before.CUST_CODE":"BILL",
    "before.ORDER_DATE":"1995-12-31:15:00:00",
    "before.PRODUCT_CODE":"CAR",
    "before.ORDER_ID":765,
    "before.PRODUCT_PRICE":15000.00,
    "before.PRODUCT_AMOUNT":3,
    "before.TRANSACTION_ID":100,
    "after.CUST_CODE":"BILL",
    "after.ORDER_DATE":"1995-12-31:15:00:00",
    "after.PRODUCT_CODE":"CAR",
    "after.ORDER_ID":765,
    "after.PRODUCT_PRICE":14000.00
}

削除

{
    "table":"QASOURCE.TCUSTORD",
    "op_type":"D",
    "op_ts":"2015-11-05 18:45:39.000000",
    "current_ts":"2016-10-05T10:34:48.193000",
    "pos":"00000000000000005272",
    "before.CUST_CODE":"DAVE",
    "before.ORDER_DATE":"1993-11-03:07:51:35",
    "before.PRODUCT_CODE":"PLANE",
    "before.ORDER_ID":600,
    "before.PRODUCT_PRICE":135000.00,
    "before.PRODUCT_AMOUNT":2,
    "before.TRANSACTION_ID":200
}

切捨て

{
    "table":"QASOURCE.TCUSTORD",
    "op_type":"D",
    "op_ts":"2015-11-05 18:45:39.000000",
    "current_ts":"2016-10-05T10:34:48.193001",
    "pos":"00000000000000005480",
    "before.CUST_CODE":"JANE",
    "before.ORDER_DATE":"1995-11-11:13:52:00",
    "before.PRODUCT_CODE":"PLANE",
    "before.ORDER_ID":256,
    "before.PRODUCT_PRICE":133300.00,
    "before.PRODUCT_AMOUNT":1,
    "before.TRANSACTION_ID":100
}

8.2.31.5.4.4.3 行モデル化JSONメッセージの例

挿入

{
    "table":"QASOURCE.TCUSTORD",
    "op_type":"I",
    "op_ts":"2015-11-05 18:45:36.000000",
    "current_ts":"2016-10-05T11:10:42.294000",
    "pos":"00000000000000002928",
    "CUST_CODE":"WILL",
    "ORDER_DATE":"1994-09-30:15:33:00",
    "PRODUCT_CODE":"CAR",
    "ORDER_ID":144,
    "PRODUCT_PRICE":17520.00,
    "PRODUCT_AMOUNT":3,
    "TRANSACTION_ID":100
}

更新

{
    "table":"QASOURCE.TCUSTORD",
    "op_type":"U",
    "op_ts":"2015-11-05 18:45:39.000000",
    "current_ts":"2016-10-05T11:10:42.350005",
    "pos":"00000000000000004300",
    "CUST_CODE":"BILL",
    "ORDER_DATE":"1995-12-31:15:00:00",
    "PRODUCT_CODE":"CAR",
    "ORDER_ID":765,
    "PRODUCT_PRICE":14000.00
}

削除

{
    "table":"QASOURCE.TCUSTORD",
    "op_type":"D",
    "op_ts":"2015-11-05 18:45:39.000000",
    "current_ts":"2016-10-05T11:10:42.351002",
    "pos":"00000000000000005272",
    "CUST_CODE":"DAVE",
    "ORDER_DATE":"1993-11-03:07:51:35",
    "PRODUCT_CODE":"PLANE",
    "ORDER_ID":600,
    "PRODUCT_PRICE":135000.00,
    "PRODUCT_AMOUNT":2,
    "TRANSACTION_ID":200
}

切捨て

{
    "table":"QASOURCE.TCUSTORD",
    "op_type":"T",
    "op_ts":"2015-11-05 18:45:39.000000",
    "current_ts":"2016-10-05T11:10:42.351003",
    "pos":"00000000000000005480",
}

8.2.31.5.4.4.4 主キー出力JSONメッセージの例

{
    "table":"DDL_OGGSRC.TCUSTMER",
    "op_type":"I",
    "op_ts":"2015-10-26 03:00:06.000000",
    "current_ts":"2016-04-05T08:59:23.001000",
    "pos":"00000000000000006605",
    "primary_keys":[
        "CUST_CODE"
    ],
    "after":{
        "CUST_CODE":"WILL",
        "NAME":"BG SOFTWARE CO.",
        "CITY":"SEATTLE",
        "STATE":"WA"
    }
}

8.2.31.5.4.5 JSONスキーマ

デフォルトでは、JSONスキーマは発生するソース表ごとに生成されます。JSONスキーマは、その表に対する操作が発生した時点でジャスト・イン・タイム方式で生成されます。メタデータに変更があると、新しいスキーマが生成されます。JSONスキーマは、JSONオブジェクトの解析に必須ではありません。ただし、多くのJSONパーサーがJSONスキーマを使用して、JSONオブジェクトの検証解析を実行します。また、JSONスキーマを確認すると、出力されるJSONオブジェクトのレイアウトを把握できます。デフォルトでは、JSONスキーマはGoldenGate_Home/dirdefディレクトリに作成され、次の命名規則に従って名前が付けられます。

FULLY_QUALIFIED_TABLE_NAME.schema.json

JSONスキーマの生成は抑止できます。

「操作モデル化JSONメッセージの例」でリストしたJSONオブジェクトのJSONスキーマの例を次に示します。

{
    "$schema":"http://json-schema.org/draft-04/schema#",
    "title":"QASOURCE.TCUSTORD",
    "description":"JSON schema for table QASOURCE.TCUSTORD",
    "definitions":{
        "row":{
            "type":"object",
            "properties":{
                "CUST_CODE":{
                    "type":[
                        "string",
                        "null"
                    ]
                },
                "ORDER_DATE":{
                    "type":[
                        "string",
                        "null"
                    ]
                },
                "PRODUCT_CODE":{
                    "type":[
                        "string",
                        "null"
                    ]
                },
                "ORDER_ID":{
                    "type":[
                        "number",
                        "null"
                    ]
                },
                "PRODUCT_PRICE":{
                    "type":[
                        "number",
                        "null"
                    ]
                },
                "PRODUCT_AMOUNT":{
                    "type":[
                        "integer",
                        "null"
                    ]
                },
                "TRANSACTION_ID":{
                    "type":[
                        "number",
                        "null"
                    ]
                }
            },
            "additionalProperties":false
        },
        "tokens":{
            "type":"object",
            "description":"Token keys and values are free form key value pairs.",
            "properties":{
            },
            "additionalProperties":true
        }
    },
    "type":"object",
    "properties":{
        "table":{
            "description":"The fully qualified table name",
            "type":"string"
        },
        "op_type":{
            "description":"The operation type",
            "type":"string"
        },
        "op_ts":{
            "description":"The operation timestamp",
            "type":"string"
        },
        "current_ts":{
            "description":"The current processing timestamp",
            "type":"string"
        },
        "pos":{
            "description":"The position of the operation in the data source",
            "type":"string"
        },
        "primary_keys":{
            "description":"Array of the primary key column names.",
            "type":"array",
            "items":{
                "type":"string"
            },
            "minItems":0,
            "uniqueItems":true
        },
        "tokens":{
            "$ref":"#/definitions/tokens"
        },
        "before":{
            "$ref":"#/definitions/row"
        },
        "after":{
            "$ref":"#/definitions/row"
        }
    },
    "required":[
        "table",
        "op_type",
        "op_ts",
        "current_ts",
        "pos"
    ],
    "additionalProperties":false
}

「フラット化操作モデル化JSONメッセージの例」でリストしたJSONオブジェクトのJSONスキーマの例を次に示します。

{
    "$schema":"http://json-schema.org/draft-04/schema#",
    "title":"QASOURCE.TCUSTORD",
    "description":"JSON schema for table QASOURCE.TCUSTORD",
    "definitions":{
        "tokens":{
            "type":"object",
            "description":"Token keys and values are free form key value pairs.",
            "properties":{
            },
            "additionalProperties":true
        }
    },
    "type":"object",
    "properties":{
        "table":{
            "description":"The fully qualified table name",
            "type":"string"
        },
        "op_type":{
            "description":"The operation type",
            "type":"string"
        },
        "op_ts":{
            "description":"The operation timestamp",
            "type":"string"
        },
        "current_ts":{
            "description":"The current processing timestamp",
            "type":"string"
        },
        "pos":{
            "description":"The position of the operation in the data source",
            "type":"string"
        },
        "primary_keys":{
            "description":"Array of the primary key column names.",
            "type":"array",
            "items":{
                "type":"string"
            },
            "minItems":0,
            "uniqueItems":true
        },
        "tokens":{
            "$ref":"#/definitions/tokens"
        },
        "before.CUST_CODE":{
            "type":[
                "string",
                "null"
            ]
        },
        "before.ORDER_DATE":{
            "type":[
                "string",
                "null"
            ]
        },
        "before.PRODUCT_CODE":{
            "type":[
                "string",
                "null"
            ]
        },
        "before.ORDER_ID":{
            "type":[
                "number",
                "null"
            ]
        },
        "before.PRODUCT_PRICE":{
            "type":[
                "number",
                "null"
            ]
        },
        "before.PRODUCT_AMOUNT":{
            "type":[
                "integer",
                "null"
            ]
        },
        "before.TRANSACTION_ID":{
            "type":[
                "number",
                "null"
            ]
        },
        "after.CUST_CODE":{
            "type":[
                "string",
                "null"
            ]
        },
        "after.ORDER_DATE":{
            "type":[
                "string",
                "null"
            ]
        },
        "after.PRODUCT_CODE":{
            "type":[
                "string",
                "null"
            ]
        },
        "after.ORDER_ID":{
            "type":[
                "number",
                "null"
            ]
        },
        "after.PRODUCT_PRICE":{
            "type":[
                "number",
                "null"
            ]
        },
        "after.PRODUCT_AMOUNT":{
            "type":[
                "integer",
                "null"
            ]
        },
        "after.TRANSACTION_ID":{
            "type":[
                "number",
                "null"
            ]
        }
    },
    "required":[
        "table",
        "op_type",
        "op_ts",
        "current_ts",
        "pos"
    ],
    "additionalProperties":false
}

「行モデル化JSONメッセージの例」でリストしたJSONオブジェクトのJSONスキーマの例を次に示します。

{
    "$schema":"http://json-schema.org/draft-04/schema#",
    "title":"QASOURCE.TCUSTORD",
    "description":"JSON schema for table QASOURCE.TCUSTORD",
    "definitions":{
        "tokens":{
            "type":"object",
            "description":"Token keys and values are free form key value pairs.",
            "properties":{
            },
            "additionalProperties":true
        }
    },
    "type":"object",
    "properties":{
        "table":{
            "description":"The fully qualified table name",
            "type":"string"
        },
        "op_type":{
            "description":"The operation type",
            "type":"string"
        },
        "op_ts":{
            "description":"The operation timestamp",
            "type":"string"
        },
        "current_ts":{
            "description":"The current processing timestamp",
            "type":"string"
        },
        "pos":{
            "description":"The position of the operation in the data source",
            "type":"string"
        },
        "primary_keys":{
            "description":"Array of the primary key column names.",
            "type":"array",
            "items":{
                "type":"string"
            },
            "minItems":0,
            "uniqueItems":true
        },
        "tokens":{
            "$ref":"#/definitions/tokens"
        },
        "CUST_CODE":{
            "type":[
                "string",
                "null"
            ]
        },
        "ORDER_DATE":{
            "type":[
                "string",
                "null"
            ]
        },
        "PRODUCT_CODE":{
            "type":[
                "string",
                "null"
            ]
        },
        "ORDER_ID":{
            "type":[
                "number",
                "null"
            ]
        },
        "PRODUCT_PRICE":{
            "type":[
                "number",
                "null"
            ]
        },
        "PRODUCT_AMOUNT":{
            "type":[
                "integer",
                "null"
            ]
        },
        "TRANSACTION_ID":{
            "type":[
                "number",
                "null"
            ]
        }
    },
    "required":[
        "table",
        "op_type",
        "op_ts",
        "current_ts",
        "pos"
    ],
    "additionalProperties":false
}

8.2.31.5.4.6 JSONフォーマッタの構成プロパティ

表8-47 JSONフォーマッタの構成プロパティ

プロパティ	必須/オプション	有効な値	デフォルト	説明
gg.handler.name.format	オプション	json | json_row	なし	生成されるJSON出力メッセージが操作モデル化か行モデル化かを制御します。操作モデル化の場合はjson、行モデル化の場合はjson_rowに設定します。
gg.handler.name.format.insertOpKey	オプション	任意の文字列	I	出力レコードに挿入され、挿入操作を示す指標です。
gg.handler.name.format.updateOpKey	オプション	任意の文字列	U	出力レコードに挿入され、更新操作を示す指標です。
gg.handler.name.format.deleteOpKey	オプション	任意の文字列	D	出力レコードに挿入され、削除操作を示す指標です。
gg.handler.name.format.truncateOpKey	オプション	任意の文字列	T	出力レコードに挿入され、切捨て操作を示す指標です。
gg.handler.name.format.prettyPrint	オプション	true | false	false	JSONデータの出力形式を制御します。trueの場合は、読みやすいようにデータに空白を追加してフォーマットします。falseの場合は、読み取るのが難しいコンパクトな出力が生成されます。
gg.handler.name.format.jsonDelimiter	オプション	任意の文字列	""(値なし)	生成されるJSON間に区切り文字が挿入されるため、データの連続ストリームで簡単に解析できます。構成値はCDATA[]ラッピングをサポートします。
gg.handler.name.format.generateSchema	オプション	true | false	true	生成されるJSONドキュメントに対して、JSONスキーマの生成を制御します。JSONスキーマは、表ごとに生成されます。JSONスキーマは、JSONドキュメントの解析に必須ではありません。ただし、JSONスキーマを使用すると、JSONドキュメントがどのように見えるかが示されるため、JSON解析の検証に使用できます。
gg.handler.name.format.schemaDirectory	オプション	有効で存在する人気のファイル・システム・パス	./dirdef	生成されるJSONスキーマの出力場所を制御します。
gg.handler.name.format.treatAllColumnsAsStrings	オプション	true | false	false	生成されるJSONドキュメントの出力の型付けを制御します。falseの場合、フォーマッタはOracle GoldenGateの型を、対応するJSONの型にマップしようとします。trueの場合、生成されるJSONとJSONスキーマで、すべてのデータが文字列として扱われます。
gg.handler.name.format.encoding	オプション	Javaでサポートされる任意の有効なエンコーディング名または別名。	UTF-8 (JSONのデフォルト)	生成されるJSONスキーマおよびドキュメントの出力のエンコーディングを制御します。
gg.handler.name.format.versionSchemas	オプション	true | false	false	作成されたスキーマのバージョンを制御します。スキーマ・バージョン管理によって、新しいスキーマが作成されるたびにローカル・ファイル・システム上のスキーマ・ディレクトリにタイムスタンプ付きのスキーマが作成されます。Trueに設定すると、スキーマ・バージョン管理が有効化されます。Falseに設定すると、スキーマ・バージョン管理が無効化されます。
gg.handler.name.format.iso8601Format	オプション	true | false	true	現在のタイムスタンプの形式を制御します。デフォルトはISO 8601形式です。falseに設定すると、現在のタイムスタンプの日付と時刻の間の"T"が削除され、かわりに単一のスペース (" ")が出力されます。
gg.handler.name.format.flatten	オプション	true | false	false	ターゲット・エンティティへのフラット化JSONのフォーマット済データの送信を制御します。フラット化デリミタ・プロパティを機能させるには、trueに設定する必要があります。 このプロパティは、操作フォーマット済JSON (gg.handler.name.format=json)にのみ適用できます。
gg.handler.name.format.flattenDelimiter	オプション	JSONフィールド名の任意の有効な文字または文字列。	.	連結されたJSON要素名の区切り文字を制御します。このプロパティは、空白を維持するCDATA[]ラッピングをサポートします。これが関係するのは、gg.handler.name.format.flattenがtrueに設定されている場合のみです。
gg.handler.name.format.beforeObjectName	オプション	JSONフィールド名の任意の有効な文字または文字列。	任意の有効なJSON属性名。	変更前の列値を含むJSON要素の名前を変更できるかどうかを設定できます。 このプロパティは、操作フォーマット済JSON (gg.handler.name.format=json)にのみ適用できます。
gg.handler.name.format.afterObjectName	オプション	JSONフィールド名の任意の有効な文字または文字列。	任意の有効なJSON属性名。	変更後の列値を含むJSON要素の名前を変更できるかどうかを設定できます。 このプロパティは、操作フォーマット済JSON (gg.handler.name.format=json)にのみ適用できます。
gg.handler.name.format.pkUpdateHandling	オプション	abend | update | delete-insert	abend	フォーマッタが、主キーを変更する更新操作をどのように処理するかを指定します。主キーを操作するとJSONフォーマッタで問題が起きることがあるので、ユーザーは特に慎重を期する必要があります。このプロパティは、行モデル化JSON出力メッセージとあわせてのみ使用できます。 このプロパティは、行フォーマット済JSON (gg.handler.name.format=json_row)にのみ適用できます。 abend : プロセスが終了することを示します。 update: プロセスはこの操作を通常の更新として処理します。 deleteまたはinsert: プロセスはこの操作を削除および挿入として処理します。完全なサプリメンタル・ロギングを有効にする必要があります。操作前と操作後の完全な行イメージがない場合、挿入データは不完全になります。
gg.handler.name.format.omitNullValues	オプション	true | false	false	trueに設定すると、生成されるJSON出力に含まれるフィールドからnull値を持つフィールドが省略されます。
gg.handler.name.format.omitNullValuesSpecialUpdateHandling	オプション	true | false	false	gg.handler.name.format.omitNullValues=trueの場合にのみ適用されます。trueに設定すると、変更前イメージ・データが欠落している場合または値が存在する場合に、更新後のイメージにNULL値を伝播するための特別な処理が提供されます。
gg.handler.name.format.enableJsonArrayOutput	オプション	true | false	false	操作データを表すJSONドキュメントをJSON配列にネストするには、trueに設定します。これは、トランザクション・モードのファイル出力およびKafkaメッセージで機能します。
gg.handler.name.format.metaColumnsTemplate	オプション	「メタ列のキーワード」を参照してください	なし	現在のメタ列情報を簡単な方法で構成でき、使用する明示的な必要性が排除されます。 insertOpKey | updateOpKey | deleteOpKey | truncateOpKey | includeTableName | includeOpTimestamp | includeOpType | includePosition | includeCurrentTimestamp, useIso8601Format これは、テンプレートを表す1つ以上のテンプレート化された値で構成されているカンマ区切りの文字列です。 メタ列のキーワードの詳細は、メタ列のキーワードを参照してください。 これは、メタ列のリストを生成する例です: ${optype}, ${token.ROWID}, ${sys.username}, ${currenttimestamp}

8.2.31.5.4.7 サンプル構成の確認

Javaアダプタ構成ファイルのJSONフォーマッタのサンプル構成を次に示します。

gg.handler.hdfs.format=json
gg.handler.hdfs.format.insertOpKey=I
gg.handler.hdfs.format.updateOpKey=U
gg.handler.hdfs.format.deleteOpKey=D
gg.handler.hdfs.format.truncateOpKey=T
gg.handler.hdfs.format.prettyPrint=false
gg.handler.hdfs.format.jsonDelimiter=CDATA[]
gg.handler.hdfs.format.generateSchema=true
gg.handler.hdfs.format.schemaDirectory=dirdef
gg.handler.hdfs.format.treatAllColumnsAsStrings=false

8.2.31.5.4.8 メタデータ変更イベント

メタデータ変更イベントは、実行時に処理されます。表でメタデータが変更されると、次回その表に対する操作が発生したときにJSONスキーマが再生成されます。作成されるJSONメッセージの内容は、メタデータの変更に応じて変わります。たとえば、列が追加された場合、新しい列は、メタデータ変更イベント後に作成されたJSONメッセージに追加されます。

8.2.31.5.4.9 JSON主キーの更新

JSONフォーマッタが操作データをモデル化するように構成されている場合、主キーの更新に特別な処理は不要で、他の更新と同じように扱われます。操作前と操作後の値には、主キーの変更が反映されます。

JSONフォーマッタが行データをモデル化するように構成されている場合、主キーの更新は特別な方法で処理する必要があります。デフォルトの動作は異常終了です。ただし、gg.handler.name.format.pkUpdateHandling構成プロパティを使用すると、JSONフォーマッタを行データをモデル化するように構成して、主キーの更新を通常の更新操作として、または削除操作後の挿入操作として処理できます。主キーの更新を削除および挿入操作として処理するようにフォーマッタを構成する場合は、更新前イメージと更新後イメージの完全なデータを含むようにレプリケーション・ストリームを構成することをお薦めします。そうしないと、主キーの更新で生成される挿入操作によって、変更されなかったフィールドのデータが欠落します。

8.2.31.5.4.10 Oracle Stream Analyticsの統合

操作モデル化JSONメッセージをKafkaハンドラに送信すると、Oracle GoldenGate for Big DataをOracle Stream Analytics (OSA)と統合できます。これが機能するのは、JSONフォーマッタが操作モデル化JSONメッセージを出力するように構成されている場合のみです。

OSAにはフラット化JSONオブジェクトが必要であるため、JSONフォーマッタの新機能により、フラット化JSONを生成します。この機能を使用するには、gg.handler.name.format.flatten=falseをtrueに設定します。(デフォルト設定はfalseです)。フラット化JSONファイルの例を次に示します。

{
    "table":"QASOURCE.TCUSTMER",
    "op_type":"U",
    "op_ts":"2015-11-05 18:45:39.000000",
    "current_ts":"2016-06-22T13:38:45.335001",
    "pos":"00000000000000005100",
    "before.CUST_CODE":"ANN",
    "before.NAME":"ANN'S BOATS",
    "before.CITY":"SEATTLE",
    "before.STATE":"WA",
    "after.CUST_CODE":"ANN",
    "after.CITY":"NEW YORK",
    "after.STATE":"NY"
}

8.2.31.5.4.11 Mongoドキュメントのフォーマットの詳細

証跡内の、MongoDBキャプチャで処理されたドキュメントには、次の2つの列があります:

• 列0は"_id"であり、これにより、コレクション内のドキュメントを特定します。
• 列1は"payload"であり、これにより、すべての列(コレクションのフィールド)が保持されます。

JSON Mongo Documentフォーマッタでは、MongoDBキャプチャで処理されたドキュメントが、ペイロード情報のみを含むJSON形式にフォーマットされます。

例

受信した証跡にあるドキュメントは次のとおりです

{"after":{"id":"{ \"_id\" :

{ \"$oid\" : \"65b9f02b80f1c27eb4b498e1\" }

}", "payload":"{\"_id\":

{\"$oid\": \"65b9f02b80f1c27eb4b498e1\"}

, \"CUST_CODE\":

\"test2\", \"name\": \"hello world\", \"cost\": {\"$numberDouble\": \"3000.0\"}}"}}

次のように記述されます:

{"data":"{\"_id\":

{\"$oid\": \"65b9f02b80f1c27eb4b498e1\"}

, \"CUST_CODE\": \"test2\", \"name\": \"hello world\", \"cost\": {\"$numberDouble\": \"3000.0\"}}"}

ここでは、idフィールドは削除され、列名payloadは削除されています。

JSON MongoDocumentフォーマッタを、データをペイロード値を含むJSON EXTENDED形式またはJSON RELAXED形式で記述するように構成できます。

必要な依存性

Oracle GoldenGateでは、4.11.1 bsonライブラリをJSON Mongo Documentフォーマッタとともに使用する必要があります。このドライバは、https://mvnrepository.com/artifact/org.mongodb/bson/4.11.1からダウンロードできます

bson-4.11.1のMavenアーティファクトは次のとおりです:

<dependency>

                <groupId>org.mongodb</groupId>

                <artifactId>bson</artifactId>

                <version>4.11.1</version>

           </dependency>

gg.classpathプロパティにbsonライブラリのパスを含める必要があります。

例:

gg.classpath=./bson-4.11.1.jar

JSON MongoDocumentフォーマッタの構成プロパティ

プロパティ	必須/オプション	有効な値	デフォルト	説明
gg.handler.name.format	オプション	mongodocument	なし	MongoDBキャプチャで処理されたドキュメントを、ペイロード情報のみを含むJSON形式にフォーマットします
gg.handler.name.format.jsonMode	オプション	RELAXED/EXTENDED	RELAXED	MongoDBドキュメントは、Extended形式またはRelaxed形式で表されます。
gg.handler.name.format.insertOpKey	オプション	任意の文字列	I	出力レコードに挿入され、挿入操作を示す指標です。
gg.handler.name.format.updateOpKey	オプション	任意の文字列	U	出力レコードに挿入され、更新操作を示す指標です。
gg.handler.name.format.deleteOpKey	オプション	任意の文字列	D	出力レコードに挿入され、削除操作を示す指標です。
gg.handler.name.format.truncateOpKey	オプション	任意の文字列	T	出力レコードに挿入され、切捨て操作を示す指標です。
gg.handler.name.format.metaColumnsTemplate	オプション	「メタ列のキーワード」を参照してください	なし	現在のメタ列情報は簡単に構成できます。これにより、insertOpKey | updateOpKey | deleteOpKey | truncateOpKey | includeTableName | includeOpTimestamp | includeOpType | includePosition | includeCurrentTimestampを明示的に使用する必要がなくなります。useIso8601FormatItは、テンプレートを表すテンプレート値1つ以上からなるカンマ区切りの文字列です。メタ列のキーワードの詳細は、メタ列のキーワードを参照してください。メタ列のリストの生成例を次に示します: ${optype}, ${token.ROWID}, ${sys.username}, ${currenttimestamp}
gg.handler.name.format.encoding	オプション	Javaでサポートされる任意の有効なエンコーディング名または別名。	UTF-8 (JSONのデフォルト)	生成されるJSONスキーマおよびドキュメントの出力のエンコーディングを制御します。

サンプル構成の確認

Javaアダプタ構成ファイル内のJSON Mongo Documentフォーマッタのサンプル構成を次に示します:

gg.handler.kafka.format=mongodocument

gg.handler.kafka.format.insertOpKey=I

gg.handler.kafka.format.updateOpKey=U

gg.handler.kafka.format.deleteOpKey=D

gg.handler.kafka.format.truncateOpKey=T

gg.handler.kafka.format.metaColumnsTemplate=${optype},${timestampmicro},${currenttimestampmicro},${timestamp}

8.2.31.5.5 長さ区切り値フォーマッタの使用

長さ区切り値(LDV)フォーマッタは、行ベースのフォーマッタの一種です。ソース証跡ファイルから、データベース操作の内容を、長さ区切り値出力としてフォーマットします。ソース証跡からの挿入、更新、削除または切捨ての各操作は、個々の長さ区切りメッセージにフォーマットされます。

長さ区切りでは、フィールド・デリミタはありません。フィールドのサイズは、データに基づいて可変です。

長さ区切りでは、デフォルトで次の列値状態が長さ区切り値出力にマップされます。ソース証跡ファイルからの操作の列値は、次の3つの状態のいずれかになります。

• 列値がある —列値は、接頭辞指標がPの出力です。

• 列値がNULL —デフォルトの出力値はNです。列値がNULLの場合の出力は、構成可能です。

• 列値がない - デフォルトの出力値はMです。列値がない場合の出力は、設定を変更できます。

• メッセージのフォーマットの詳細
  
• フォーマットしたメッセージの例
  
• LDVフォーマッタの構成プロパティ
  
• その他の考慮事項
  

8.2.31.5.5.1 メッセージのフォーマットの詳細

データの出力のデフォルト形式は、次のとおりです。

最初は行の長さで、その後にメタデータが続きます。

<ROW LENGTH><PRESENT INDICATOR><FIELD LENGTH><OPERATION TYPE><PRESENT INDICATOR><FIELD LENGTH><FULLY QUALIFIED TABLE NAME><PRESENT INDICATOR><FIELD LENGTH><OPERATION TIMESTAMP><PRESENT INDICATOR><FIELD LENGTH><CURRENT TIMESTAMP><PRESENT INDICATOR><FIELD LENGTH><TRAIL POSITION><PRESENT INDICATOR><FIELD LENGTH><TOKENS>

または

<ROW LENGTH><FIELD LENGTH><FULLY QUALIFIED TABLE NAME><FIELD LENGTH><OPERATION TIMESTAMP><FIELD LENGTH><CURRENT TIMESTAMP><FIELD LENGTH><TRAIL POSITION><FIELD LENGTH><TOKENS>	

次が行データです。

<PRESENT INDICATOR><FIELD LENGTH><COLUMN 1 VALUE><PRESENT INDICATOR><FIELD LENGTH><COLUMN N VALUE>

8.2.31.5.5.2 フォーマットしたメッセージの例

挿入メッセージ:

0133P01IP161446749136000000P161529311765024000P262015-11-05 
18:45:36.000000P04WILLP191994-09-30 15:33:00P03CARP03144P0817520.00P013P03100

更新メッセージ

0133P01UP161446749139000000P161529311765035000P262015-11-05 
18:45:39.000000P04BILLP191995-12-31 15:00:00P03CARP03765P0814000.00P013P03100

削除メッセージ

0136P01DP161446749139000000P161529311765038000P262015-11-05 
18:45:39.000000P04DAVEP191993-11-03 
07:51:35P05PLANEP03600P09135000.00P012P03200

8.2.31.5.5.3 LDVフォーマッタの構成プロパティ

表8-48 LDVフォーマッタの構成プロパティ

プロパティ	必須/オプション	有効な値	デフォルト	説明
gg.handler.name.format.binaryLengthMode	オプション	true | false	false	フィールドまたはレコード長をバイナリ形式またはASCII形式で表示するように出力を制御できます。trueに設定した場合、レコードまたはフィールド長はバイナリ形式で表され、それ以外の場合はASCIIで表されます。
gg.handler.name.format.recordLength	オプション	4 | 8	true	trueに設定すると、レコード長は4バイトまたは8バイトのビッグ・エンディアン整数で表されます。falseに設定すると、長さが4または8となるよう値が埋め込まれたレコード長の文字列表現が使用されます。
gg.handler.name.format.fieldLength	オプション	2 | 4	true	trueに設定すると、レコード長は2バイトまたは4バイトのビッグ・エンディアン整数で表されます。falseに設定すると、長さが2または4となるよう値が埋め込まれたレコード長の文字列表現が使用されます。
gg.handler.name.format.format	オプション	true | false	true	メタ列でP指標を構成するのに使用します。falseに設定すると、メタ列の前の指標Pが有効になります。trueに設定した場合、指標は無効になります。
gg.handler.name.format.presentValue	オプション	任意の文字列	P	列値が存在する場合に出力に含める内容を構成するのに使用します。この値はCDATA[]ラッピングをサポートします。
gg.handler.name.format.missingValue	オプション	任意の文字列	M	欠落値が存在する場合に出力に含める内容を構成するのに使用します。この値はCDATA[]ラッピングをサポートします。
gg.handler.name.format.nullValue	オプション	任意の文字列	N	NULL値が存在する場合に出力に含める内容を構成するのに使用します。この値はCDATA[]ラッピングをサポートします。
gg.handler.name.format.metaColumnsTemplate	オプション	「メタ列のキーワード」を参照してください。	なし	現在のメタ列情報を単純な方法で構成し、insertOpKey、updateOpKey、deleteOpKey、truncateOpKey、includeTableName、includeOpTimestamp、includeOpType、includePosition、includeCurrentTimestampおよびuseIso8601Formatの明示的な必要性を取り除くのに使用します。 1つ以上のテンプレート化された値で構成されているカンマ区切りの文字列でテンプレートを表します。この例では、メタ列のリストを生成します。 ${optype}, ${token.ROWID},${sys.username},${currenttimestamp} 「メタ列のキーワード」を参照してください。
gg.handler.name.format.pkUpdateHandling	オプション	abend | update | delete-insert	abend	フォーマッタが、主キーを変更する更新操作をどのように処理するかを指定します。主キーを操作するとテキスト・フォーマッタで問題が起きることがあるので、ユーザーは特に慎重を期する必要があります。 abend : プロセスが異常終了することを示します update : プロセスでこれが通常の更新として扱われることを示します delete-insert: プロセスでこれが削除および挿入として扱われることを示します。これが機能するには、完全なサプリメンタル・ロギングを有効にする必要があります。操作前と操作後の完全な行イメージがない場合、挿入データは不完全になります。
gg.handler.name.format.encoding	オプション	Javaでサポートされる任意のエンコーディング名または別名。	Oracle GoldenGateプロセスをホストしているマシンのネイティブのシステム・エンコーディング。	文字データおよび列の出力エンコーディングを設定するのに使用します。

メタ列のキーワードの詳細は、メタ列のキーワードを参照してください。

次に、メタ列のリストを生成する例を示します。

${optype}, ${token.ROWID}, ${sys.username}, ${currenttimestamp}

サンプル構成の確認

#The LDV Handler
gg.handler.filewriter.format=binary
gg.handler.filewriter.format.binaryLengthMode=false
gg.handler.filewriter.format.recordLength=4
gg.handler.filewriter.format.fieldLength=2
gg.handler.filewriter.format.legacyFormat=false
gg.handler.filewriter.format.presentValue=CDATA[P]
gg.handler.filewriter.format.missingValue=CDATA[M]
gg.handler.filewriter.format.nullValue=CDATA[N]
gg.handler.filewriter.format.metaColumnsTemplate=${optype},${timestampmicro},${currenttimestampmicro},${timestamp}
gg.handler.filewriter.format.pkUpdateHandling=abend

8.2.31.5.5.4 その他の考慮事項

ビッグ・データ・アプリケーションは、格納方法がRDBMSと異なります。RDBMSで更新操作と削除操作を行うと、既存のデータが変更されます。ビッグ・データ・アプリケーションでは、データは変更されず、既存のデータに追加されるだけです。特定の行の現在の状態は、HDFSシステムにおけるその行に対する既存の操作がすべて統合された結果になります。

主キーの更新

主キーを更新する操作では、ビッグ・データ統合について特別な考慮と計画が必要です。主キーの更新は、ソース・データベースの特定の行に対する1つ以上の主キーを変更する更新操作です。データはビッグ・データ・アプリケーションで追加されるだけなので、主キーの更新操作は、何も処理しない更新というより新しい挿入にも似ています。長さ区切り値フォーマッタは、主キーの特別な処理に対応しており、ユーザーが設定を変更できます。設定変更が可能な動作は次のとおりです。

表8-49 主キーの更新の動作

値	説明
Abend	デフォルトの動作で、主キーが更新される場合、長さ区切り値フォーマッタは異常終了します。
更新	この構成では、主キー更新が他の更新操作と同じように処理されます。この構成は、ビッグ・データ・システムから行データを選択するとき、変更される主キーが選択基準として使用されないと間違いなくわかっている場合にのみ選択してください。
Delete-Insert	この構成を使用すると、主キーの更新は、操作前のイメージ・データを使用する削除と、操作後のイメージ・データを使用する挿入という特殊なケースとして処理されます。この構成は、ビッグ・データ・アプリケーションで主キー更新の影響をより正確にモデル化する場合があります。ただし、この構成を選択する場合は、ソース・データベースでのレプリケーションで完全なサプリメンタル・ロギングを有効にすることが重要です。完全なサプリメンタル・ロギングを有効にしない場合、削除操作は正常に処理されますが、挿入操作では、ビッグ・データ・アプリケーションで行データの完全な形式の列のデータがすべては含まれません。

データの統合

ビッグ・データ・アプリケーションは、基礎となるストレージにデータを単に追加します。通常、分析ツールはデータ・ファイルを横断して、特定の行の操作をすべて1つの出力に統合するマップ・リデュース・プログラムを生成します。操作順序を指定することが重要です。長さ区切り値フォーマッタには、このニーズに対応する多くのメタデータ・フィールドがあります。この要件を満たすには、操作のタイムスタンプでも十分です。が、共通のトランザクションを共有する場合などには特に、2つの更新操作が同じタイムスタンプになる場合もあります。操作タイムスタンプが等しい場合には、証跡のポジションが判別基準のフィールドになります。最後に、現在のタイムスタンプもビッグ・データにおける操作の順序指標として最適です。

8.2.31.5.6 XMLフォーマッタの使用

XMLフォーマッタは、ソース証跡ファイルの操作前イメージと操作後イメージのデータをXMLドキュメント形式の操作データにフォーマットします。XMLドキュメントの形式は、これまでのリリースのOracle GoldenGate Java AdapterにおけるXML形式と実質的に同じです。

• メッセージのフォーマットの詳細
  
• XMLメッセージの例
  
• XMLスキーマ
  
• XMLフォーマッタの構成プロパティ
  
• サンプル構成の確認
  
• メタデータ変更イベント
  
• 主キーの更新
  

8.2.31.5.6.1 メッセージのフォーマットの詳細

XMLでフォーマットされたメッセージには、次の情報が含まれます。

表8-50 XMLフォーマットの詳細

値	説明
table	完全修飾の表名。
type	操作タイプ。
current_ts	現在のタイムスタンプは、フォーマッタが現在の操作レコードを処理した時刻です。このタイムスタンプはISO-8601形式に従い、精度はミリ秒までです。証跡ファイルを再生しても、同じ操作に対して同じタイムスタンプにはなりません。
pos	ソース証跡ファイルからのポジション。
numCols	ソース表の列の合計数。
col	col要素は、操作データの操作前と操作後のイメージを含む反復要素です。
tokens	tokens要素には、ソース証跡ファイルからのトークン値が含まれます。

8.2.31.5.6.2 XMLメッセージの例

次の各項では、XMLメッセージの例を示します。

• 挿入メッセージの例
  
• 更新メッセージの例
  
• 削除メッセージの例
  
• 切捨てメッセージの例
  

8.2.31.5.6.2.1 挿入メッセージの例

<?xml version='1.0' encoding='UTF-8'?>
<operation table='GG.TCUSTORD' type='I' ts='2013-06-02 22:14:36.000000' current_ts='2015-10-06T12:21:50.100001' pos='00000000000000001444' numCols='7'>
 <col name='CUST_CODE' index='0'>
   <before missing='true'/>
   <after><![CDATA[WILL]]></after>
 </col>
 <col name='ORDER_DATE' index='1'>
   <before missing='true'/>
   <after><![CDATA[1994-09-30:15:33:00]]></after>
 </col>
 <col name='PRODUCT_CODE' index='2'>
   <before missing='true'/>
   <after><![CDATA[CAR]]></after>
 </col>
 <col name='ORDER_ID' index='3'>
   <before missing='true'/>
   <after><![CDATA[144]]></after>
 </col>
 <col name='PRODUCT_PRICE' index='4'>
   <before missing='true'/>
   <after><![CDATA[17520.00]]></after>
 </col>
 <col name='PRODUCT_AMOUNT' index='5'>
   <before missing='true'/>
   <after><![CDATA[3]]></after>
 </col>
 <col name='TRANSACTION_ID' index='6'>
   <before missing='true'/>
   <after><![CDATA[100]]></after>
 </col>
 <tokens>
   <token>
     <Name><![CDATA[R]]></Name>
     <Value><![CDATA[AADPkvAAEAAEqL2AAA]]></Value>
   </token>
 </tokens>
</operation>

8.2.31.5.6.2.2 更新メッセージの例

<?xml version='1.0' encoding='UTF-8'?>
<operation table='GG.TCUSTORD' type='U' ts='2013-06-02 22:14:41.000000' current_ts='2015-10-06T12:21:50.413000' pos='00000000000000002891' numCols='7'>
 <col name='CUST_CODE' index='0'>
   <before><![CDATA[BILL]]></before>
   <after><![CDATA[BILL]]></after>
 </col>
 <col name='ORDER_DATE' index='1'>
   <before><![CDATA[1995-12-31:15:00:00]]></before>
   <after><![CDATA[1995-12-31:15:00:00]]></after>
 </col>
 <col name='PRODUCT_CODE' index='2'>
   <before><![CDATA[CAR]]></before>
   <after><![CDATA[CAR]]></after>
 </col>
 <col name='ORDER_ID' index='3'>
   <before><![CDATA[765]]></before>
   <after><![CDATA[765]]></after>
 </col>
 <col name='PRODUCT_PRICE' index='4'>
   <before><![CDATA[15000.00]]></before>
   <after><![CDATA[14000.00]]></after>
 </col>
 <col name='PRODUCT_AMOUNT' index='5'>
   <before><![CDATA[3]]></before>
   <after><![CDATA[3]]></after>
 </col>
 <col name='TRANSACTION_ID' index='6'>
   <before><![CDATA[100]]></before>
   <after><![CDATA[100]]></after>
 </col>
 <tokens>
   <token>
     <Name><![CDATA[R]]></Name>
     <Value><![CDATA[AADPkvAAEAAEqLzAAA]]></Value>
   </token>
 </tokens>
</operation>

8.2.31.5.6.2.3 削除メッセージの例

<?xml version='1.0' encoding='UTF-8'?>
<operation table='GG.TCUSTORD' type='D' ts='2013-06-02 22:14:41.000000' current_ts='2015-10-06T12:21:50.415000' pos='00000000000000004338' numCols='7'>
 <col name='CUST_CODE' index='0'>
   <before><![CDATA[DAVE]]></before>
   <after missing='true'/>
 </col>
 <col name='ORDER_DATE' index='1'>
   <before><![CDATA[1993-11-03:07:51:35]]></before>
   <after missing='true'/>
 </col>
 <col name='PRODUCT_CODE' index='2'>
   <before><![CDATA[PLANE]]></before>
   <after missing='true'/>
 </col>
 <col name='ORDER_ID' index='3'>
   <before><![CDATA[600]]></before>
   <after missing='true'/>
 </col>
 <col name='PRODUCT_PRICE' index='4'>
  <missing/>
 </col>
 <col name='PRODUCT_AMOUNT' index='5'>
  <missing/>
 </col>
 <col name='TRANSACTION_ID' index='6'>
  <missing/>
 </col>
 <tokens>
   <token>
     <Name><![CDATA[L]]></Name>
     <Value><![CDATA[206080450]]></Value>
   </token>
   <token>
     <Name><![CDATA[6]]></Name>
     <Value><![CDATA[9.0.80330]]></Value>
   </token>
   <token>
     <Name><![CDATA[R]]></Name>
     <Value><![CDATA[AADPkvAAEAAEqLzAAC]]></Value>
   </token>
 </tokens>
</operation>

8.2.31.5.6.2.4 切捨てメッセージの例

<?xml version='1.0' encoding='UTF-8'?>
<operation table='GG.TCUSTORD' type='T' ts='2013-06-02 22:14:41.000000' current_ts='2015-10-06T12:21:50.415001' pos='00000000000000004515' numCols='7'>
 <col name='CUST_CODE' index='0'>
   <missing/> 
 </col>
 <col name='ORDER_DATE' index='1'>
   <missing/> 
 </col>
 <col name='PRODUCT_CODE' index='2'>
   <missing/> 
 </col>
 <col name='ORDER_ID' index='3'>
   <missing/> 
 </col>
 <col name='PRODUCT_PRICE' index='4'>
  <missing/>
 </col>
 <col name='PRODUCT_AMOUNT' index='5'>
  <missing/>
 </col>
 <col name='TRANSACTION_ID' index='6'>
  <missing/>
 </col>
 <tokens>
   <token>
     <Name><![CDATA[R]]></Name>
     <Value><![CDATA[AADPkvAAEAAEqL2AAB]]></Value>
   </token>
 </tokens>
</operation>

8.2.31.5.6.3 XMLスキーマ

XMLフォーマッタは、XMLスキーマ(XSD)を生成しません。XSDは、XMLフォーマッタによって生成されるすべてのメッセージに適用されます。次のXSDは、XMLフォーマッタによって生成されるXMLドキュメントの構造を定義します。

<xs:schema attributeFormDefault="unqualified" 
elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="operation">
     <xs:complexType>
       <xs:sequence>
          <xs:element name="col" maxOccurs="unbounded" minOccurs="0">
           <xs:complexType>
             <xs:sequence>
               <xs:element name="before" minOccurs="0">
                 <xs:complexType>
                   <xs:simpleContent>
                     <xs:extension base="xs:string">
                       <xs:attribute type="xs:string" name="missing" 
use="optional"/>
                     </xs:extension>
                   </xs:simpleContent>
                 </xs:complexType>
               </xs:element>
               <xs:element name="after" minOccurs="0">
                 <xs:complexType>
                   <xs:simpleContent>
                     <xs:extension base="xs:string">
                       <xs:attribute type="xs:string" name="missing" 
use="optional"/>
                     </xs:extension>
                   </xs:simpleContent>
                 </xs:complexType>
               </xs:element>
               <xs:element type="xs:string" name="missing" minOccurs="0"/>
             </xs:sequence>
             <xs:attribute type="xs:string" name="name"/>
             <xs:attribute type="xs:short" name="index"/>
           </xs:complexType>
         </xs:element>
         <xs:element name="tokens" minOccurs="0">
           <xs:complexType>
             <xs:sequence>
               <xs:element name="token" maxOccurs="unbounded" minOccurs="0">
                 <xs:complexType>
                   <xs:sequence>
                     <xs:element type="xs:string" name="Name"/>
                     <xs:element type="xs:string" name="Value"/>
                   </xs:sequence>
                 </xs:complexType>
               </xs:element>
             </xs:sequence>
           </xs:complexType>
         </xs:element>
       </xs:sequence>
       <xs:attribute type="xs:string" name="table"/>
       <xs:attribute type="xs:string" name="type"/>
       <xs:attribute type="xs:string" name="ts"/>
       <xs:attribute type="xs:dateTime" name="current_ts"/>
       <xs:attribute type="xs:long" name="pos"/>
       <xs:attribute type="xs:short" name="numCols"/>
     </xs:complexType>
   </xs:element>
</xs:schema>

8.2.31.5.6.4 XMLフォーマッタの構成プロパティ

表8-51 XMLフォーマッタの構成プロパティ

プロパティ	オプションY/N	有効な値	デフォルト	説明
gg.handler.name.format.insertOpKey	オプション	任意の文字列	I	出力レコードに挿入され、挿入操作を示す指標です。
gg.handler.name.format.updateOpKey	オプション	任意の文字列	U	出力レコードに挿入され、更新操作を示す指標です。
gg.handler.name.format.deleteOpKey	オプション	任意の文字列	D	出力レコードに挿入され、削除操作を示す指標です。
gg.handler.name.format.truncateOpKey	オプション	任意の文字列	T	出力レコードに挿入され、切捨て操作を示す指標です。
gg.handler.name.format.encoding	オプション	Javaでサポートされる任意の有効なエンコーディング名または別名。	UTF-8 (XMLのデフォルト)	生成されるXMLドキュメントの出力エンコーディング。
gg.handler.name.format.includeProlog	オプション	true | false	false	生成されるXMLドキュメントにXML prologが含まれるかどうかを決定します。XML prologは、整形式のXMLではオプションです。XML prologは、<?xml version='1.0' encoding='UTF-8'?>のようになります。
gg.handler.name.format.iso8601Format	オプション	true | false	true	XMLメッセージの現在のタイムスタンプの形式を制御します。デフォルトでは、日付と時刻の間にTが追加されます。falseに設定すると、日付と時刻の間にTは表示されず、かわりに空白が出力されます。
gg.handler.name.format.missing	オプション	true | false	true	trueに設定すると、XML出力に、操作前のイメージと操作後のイメージの欠落している列値が表示されます。
gg.handler.name.format.missingAfter	オプション	true | false	true	trueに設定すると、XML出力に操作後のイメージの欠落している列値が表示されます。
gg.handler.name.format.missingBefore	オプション	true | false	true	trueに設定すると、XML出力に操作前のイメージの欠落している列値が表示されます。
gg.handler.name.format.metaColumnsTemplate	オプション	「メタ列のキーワード」を参照してください。	なし	現在のメタ列情報を簡単な方法で構成でき、使用する明示的な必要性が排除されます。 insertOpKey | updateOpKey | deleteOpKey | truncateOpKey | includeTableName | includeOpTimestamp | includeOpType | includePosition | includeCurrentTimestamp, useIso8601Format これは、テンプレートを表す1つ以上のテンプレート化された値で構成されているカンマ区切りの文字列です。メタ列のキーワードの詳細は、メタ列のキーワードを参照してください。

8.2.31.5.6.5 サンプル構成の確認

Javaアダプタ・プロパティ・ファイルのXMLフォーマッタのサンプル構成を次に示します。

gg.handler.hdfs.format=xml
gg.handler.hdfs.format.insertOpKey=I
gg.handler.hdfs.format.updateOpKey=U
gg.handler.hdfs.format.deleteOpKey=D
gg.handler.hdfs.format.truncateOpKey=T
gg.handler.hdfs.format.encoding=ISO-8859-1
gg.handler.hdfs.format.includeProlog=false

8.2.31.5.6.6 メタデータ変更イベント

XMLフォーマッタは、メタデータ変更イベントをシームレスに処理します。メタデータ変更イベントによってXMLスキーマが変更されることはありません。XMLスキーマは汎用として設計されているので、同じスキーマが任意の表の操作を表します。

複製されるデータベースとアップストリームのOracle GoldenGateレプリケーション・プロセスでメタデータ変更イベントを伝播できる場合、メタデータが変更されたときにXMLフォーマッタはアクションを実行できます。メタデータの変更は、変更後にメッセージに反映されます。たとえば、列が追加されると、新しい列データが表のXMLメッセージに表示されます。

8.2.31.5.6.7 主キーの更新

主キーを更新する際、XMLフォーマッタによる特別な処理は必要ありません。XMLフォーマッタは、データベース操作をモデル化するメッセージを作成します。更新操作の場合、これには列値の操作前と操作後のイメージが含まれます。主キーの変更は、他の列値を変更する場合と同様に、列値に対する変更としてこの形式で表されます。

8.2.31.6 ステージングおよびマージによるデータ・ウェアハウス・レプリケーション

通常データ・ウェアハウス・ターゲットはMassively Parallel Processing (MPP)をサポートしています。1回のデータ操作言語(DML)操作のコストがバッチDMLの実行コストに匹敵します。

そのためスループットを向上させる方法として、Oracle GoldenGate証跡からの変更データを一時的なステージング場所でマイクロ・バッチにステージングし、ステージングしたデータ・レコードを各データ・ウェアハウスのマージSQL文を使用してデータ・ウェアハウスのターゲット表にマージします。この項では、ステージングとマージを使用して、ソース・データベースからターゲット・データ・ウェアハウスに変更データ・レコードをレプリケートする方法の概要を説明します。このソリューションでは、コマンド・イベント・ハンドラを使用してカスタムbash-shellスクリプトを起動します。

この章では、コマンド・イベント・ハンドラ機能で実行内容の例を示します。

• ステージングおよびマージのステップ
  
• Hiveにおけるステージングおよびマージ
  HiveはHadoop上に構築されるデータ・ウェアハウス・インフラストラクチャです。このツールはデータETLを容易にするツールやデータに構造を配置するメカニズムを提供するほか、Hadoopファイルに格納された大規模データ・セットに対する問合せ機能や分析機能を提供します。

8.2.31.6.1 ステージングおよびマージのステップ

• ステージング
  このステップでは、Oracle GoldenGate証跡ファイルの変更データ・レコードがステージングの場所にプッシュされます。ステージング場所は通常、OCI、AWS S3、Azure Data Lake、Google Cloud Storageなどのクラウド・オブジェクト・ストアです。
• マージ
  このステップでは、オブジェクト・ストア内の変更データ・ファイルがデータ・ウェアハウスで定義された外部表として表示されます。外部ステージング表のデータがターゲット表にマージされます。
• ハンドラの構成
  ファイル・ライター(FW)ハンドラを構成して、GoldenGate証跡ファイルからの変更データが含まれたローカル・ステージング・ファイルを生成する必要があります。
• ファイル・ライター・ハンドラ
  通常ファイル・ライター(FW)ハンドラは、構成gg.handler.{name}.partitionByTable=trueを使用してファイルを表ごとにパーティション化して生成するように構成されます。
• 集計操作
  集計操作は、同じ行に対する複数の操作をしきい値に基づいて単一の出力操作に集計(マージ/圧縮)するプロセスです。
• オブジェクト・ストア・イベント・ハンドラ
  ファイル・ライター・ハンドラはオブジェクト・ストア・イベント・ハンドラに連結する必要があります。Oracle GoldenGate for BigDataは、OCI、AWS S3、Azure Data Lakeなどのほとんどのクラウド・オブジェクト・ストアへのファイルのアップロードをサポートしています。
• JDBCメタデータ・プロバイダ
  データ・ウェアハウスでJDBC接続がサポートされている場合、JDBCメタデータ・プロバイダを有効にする必要があります。
• コマンド・イベント・ハンドラのマージ・スクリプト
  コマンド・イベント・ハンドラはbash-shellスクリプトを起動するように構成されています。OracleにはSQL文を実行するbash-shellスクリプトが用意されており、これを使用してステージング・ファイル内の変更データをターゲット表にマージできます。
• ステージングおよびマージのサンプル構成
  各データ・ウェアハウスの実用構成は、ディレクトリAdapterExamples/big-data/data-warehouse-utils/<target>/にあります。
• マージ・スクリプト内の変数
  変数は通常、Oracle提供スクリプトの先頭に表示されます。変更する必要のあるスクリプト内の変数については、その説明が#TODO:で始まる行に記載されています。
• マージ・スクリプト内のSQL文
  シェル・スクリプト内のSQL文をカスタマイズする必要があります。変更する必要のあるSQL文については、その説明が#TODO:で始まる行に記載されています。
• マージ・スクリプトの関数
  
• 前提条件
  
• 制限事項
  

8.2.31.6.1.1 ステージング

このステップでは、Oracle GoldenGate証跡ファイルの変更データ・レコードがステージングの場所にプッシュされます。ステージング場所は通常、OCI、AWS S3、Azure Data Lake、Google Cloud Storageなどのクラウド・オブジェクト・ストアです。

これは、ファイル・ライター・ハンドラと、オブジェクト・ストア・イベント・ハンドラ用の1つのOracle GoldenGate for Distributed Applications and Analytics (GG for DAA)を使用して実現できます。

8.2.31.6.1.2 マージ

このステップでは、オブジェクト・ストア内の変更データ・ファイルがデータ・ウェアハウスで定義された外部表として表示されます。外部ステージング表のデータがターゲット表にマージされます。

マージSQLでは、ステージング表として外部表が使用されます。マージはスループットの向上につながるバッチ操作です。

8.2.31.6.1.3 ハンドラの構成

ファイル・ライター(FW)ハンドラを構成して、GoldenGate証跡ファイルからの変更データが含まれたローカル・ステージング・ファイルを生成する必要があります。

FWハンドラをオブジェクト・ストア・イベント・ハンドラに連結し、ステージング・ファイルがステージング場所にアップロードされるようにします。

ステージング場所は通常、AWS S3やAzure Data Lakeなどのクラウド・オブジェクト・ストアです。

オブジェクト・ストア・イベント・ハンドラの出力はコマンド・イベント・ハンドラに連結し、ここからカスタム・スクリプトを起動して、ターゲット・データ・ウェアハウスでマージSQL文を実行します。

8.2.31.6.1.4 ファイル・ライター・ハンドラ

通常ファイル・ライター(FW)ハンドラは、構成gg.handler.{name}.partitionByTable=trueを使用してファイルを表ごとにパーティション化して生成するように構成されます。

FWハンドラは多くの場合、Avro Object Container Format (OCF)フォーマッタを使用するように構成されます。

出力ファイル形式は使用するデータ・ウェアハウス・ターゲットによって異なることがあります。

8.2.31.6.1.5 操作集計

集計操作は、同じ行に対する複数の操作をしきい値に基づいて単一の出力操作に集計(マージ/圧縮)するプロセスです。

ステージングおよびマージによるレプリケーションでは、構成 gg.aggregate.operations=trueを使用して操作集計を有効にする必要があります。

8.2.31.6.1.6 オブジェクト・ストア・イベント・ハンドラ

ファイル・ライター・ハンドラはオブジェクト・ストア・イベント・ハンドラに連結する必要があります。Oracle GoldenGate for BigDataは、OCI、AWS S3、Azure Data Lakeなどのほとんどのクラウド・オブジェクト・ストアへのファイルのアップロードをサポートしています。

8.2.31.6.1.7 JDBCメタデータ・プロバイダ

データ・ウェアハウスでJDBC接続がサポートされている場合、JDBCメタデータ・プロバイダを有効にする必要があります。

8.2.31.6.1.8 コマンド・イベント・ハンドラのマージ・スクリプト

コマンド・イベント・ハンドラはbash-shellスクリプトを起動するように構成されています。OracleにはSQL文を実行するbash-shellスクリプトが用意されており、これを使用してステージング・ファイル内の変更データをターゲット表にマージできます。

レプリケーション・プロセスを開始する前に、必要な構成に従ってシェル・スクリプトをカスタマイズする必要があります。

8.2.31.6.1.9 ステージングおよびマージのサンプル構成

各データ・ウェアハウスの実用構成は、ディレクトリAdapterExamples/big-data/data-warehouse-utils/<target>/にあります。

このディレクトリには次のソフトウェアが格納されます。

• Replicatパラメータ(.prm)ファイル。
• FWハンドラおよびすべてのイベント・ハンドラ構成が含まれたReplicatプロパティ・ファイル。
• マージ・スクリプトで使用されるサンプル表のDDLファイル。
• 特定のデータ・ウェアハウス用のマージ・スクリプト。このスクリプトには、DDLファイルで定義されたサンプル表を使用してテストされたSQL文が含まれています。

8.2.31.6.1.10 マージ・スクリプト内の変数

変数は通常、Oracle提供スクリプトの先頭に表示されます。変更する必要のあるスクリプト内の変数については、その説明が#TODO:で始まる行に記載されています。

例:

#TODO: Edit this. Provide the replicat group name.
repName=RBD

#TODO: Edit this. Ensure each replicat uses a unique prefix.
stagingTablePrefix=${repName}_STAGE_

#TODO: Edit the AWS S3 bucket name.
bucket=<AWS S3 bucket name>

#TODO: Edit this variable as needed.
s3Location="'s3://${bucket}/${dir}/'"

#TODO: Edit AWS credentials awsKeyId and awsSecretKey
awsKeyId=<AWS Access Key Id>
awsSecretKey=<AWS Secret key>

変数repNameおよびstagingTablePrefixは、すべてのデータ・ウェアハウス・ターゲットに関連する変数です。

8.2.31.6.1.11 マージ・スクリプト内のSQL文

シェル・スクリプト内のSQL文をカスタマイズする必要があります。変更する必要のあるSQL文については、その説明が#TODO:で始まる行に記載されています。

通常、SQL文では識別子を二重引用符で囲む必要があります。二重引用符は、バックスラッシュを使用してスクリプト内でエスケープする必要があります。たとえば、\"です。

OracleではSQL文の実例を提供しています。この実例は、サンプルDDLファイルで定義された事前定義済列セットが含まれる単一表に使用できます。独自の表用の新しいセクションはスクリプトのif-elseコード・ブロックに追加する必要があります。

例:

if [ "${tableName}" == "DBO.TCUSTORD" ]
then
  #TODO: Edit all the column names of the staging and target tables.
  # The merge SQL example here is configured for the example table defined in the DDL file.
  # Oracle provided SQL statements

# TODO: Add similar SQL queries for each table.
elif [ "${tableName}" == "DBO.ANOTHER_TABLE" ]
then
  
#Edit SQLs for this table.
fi

8.2.31.6.1.12 マージ・スクリプトの関数

スクリプトのコードには次のシェル関数を含めます。

• main
• validateParams
• process
• processTruncate
• processDML
• dropExternalTable
• createExternalTable
• merge

スクリプトには各関数の目的を示すコード・コメントが含まれています。

マージ・スクリプトmain関数

関数mainはスクリプトのエントリ・ポイントです。ステージングされた変更後データ・ファイルの処理はここから開始します。

この関数はvalidateParamsとprocessの2つの関数を呼び出します。

スクリプトの入力パラメータは関数validateParamsで検証されます。

検証が成功すると、process関数で処理が再開されます。

マージ・スクリプトprocess関数

この関数は、ステージングされた変更データ・ファイル内の操作レコードを処理し、必要に応じてprocessTruncateまたはprocessDMLを呼び出します。

切捨て操作レコードは、関数processTruncateで処理されます。Insert、UpdateおよびDelete操作レコードは、関数processDMLで処理されます。

マージ・スクリプトmerge関数

関数processDMLによって呼び出されるmerge関数には、各表に対して実行されるマージSQL文が含まれています。

マージSQLのON句で使用するキー列はカスタマイズする必要があります。

null値を持つキー列を処理するには、ON句でデータ・ウェアハウス固有のNVL関数を使用します。単一キー列"C01Key"の例:

ON ((NVL(CAST(TARGET.\"C01Key\" AS VARCHAR(4000)),'${uuid}')=NVL(CAST(STAGE.\"C01Key\" AS VARCHAR(4000)),'${uuid}')))`

merge文のupdate句およびinsert句の列名も、すべての表についてカスタマイズする必要があります。

マージ・スクリプトcreateExternalTable関数

関数processDMLによって起動されるcreateExternalTable関数は、各オブジェクト・ストア・ファイル内のファイルよって裏付けされる外部表を作成します。

この関数では各ターゲット表について、外部表のDDL SQL文をカスタマイズし、すべてのターゲット表列が含まれるようにする必要があります。

外部表定義にはターゲット表の列のほか、optype、position、fieldmaskという3つのメタ列が含まれています。

メタ列のデータ型は変更しないでください。DDL文でメタ列の位置を変更しないでください。

8.2.31.6.1.13 前提条件

• コマンド・ハンドラのマージ・スクリプトは、Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)リリース19.1.0.0.8以降で使用できます。
• SQL問合せを実行する、それぞれのデータ・ウェアハウスのコマンドライン・プログラムを、GG for DAAがインストールされているマシンにインストールする必要があります。

8.2.31.6.1.14 制限事項

主キーの更新操作は、削除と挿入のペアに分割されます。Oracle GoldenGate証跡ファイルに各表のすべての列値が含まれていない場合、欠落している列はターゲット表上でnullに更新されます。

8.2.31.6.2 Hiveにおけるステージングおよびマージ

HiveはHadoop上に構築されるデータ・ウェアハウス・インフラストラクチャです。このツールはデータETLを容易にするツールやデータに構造を配置するメカニズムを提供するほか、Hadoopファイルに格納された大規模データ・セットに対する問合せ機能や分析機能を提供します。

このトピックでは、Hiveコマンド・イベント・ハンドラでの実行内容の例を示します

• データ・フロー
  
• 構成
  Oracle GoldenGate BigDataインストールのディレクトリAdapterExamples/big-data/data-warehouse-utils/hive/には、ステージングおよびマージを使用したHiveへのレプリケーションに必要なすべての構成およびスクリプトが含まれています。
• マージ・スクリプトの変数
  
• 前提条件
  

8.2.31.6.2.1 データ・フロー

• ファイル・ライター(FW)ハンドラは、Avro Object Container Format (OCF)でファイルを生成するように構成されます。
• HDFSイベント・ハンドラは、Avro OCFファイルをHadoopにプッシュするために使用されます。
• コマンド・イベント・ハンドラはHadoopファイル・メタデータをhive.shスクリプトに渡します。

8.2.31.6.2.2 構成

Oracle GoldenGate BigDataインストールのディレクトリAdapterExamples/big-data/data-warehouse-utils/hive/には、ステージングおよびマージを使用したHiveへのレプリケーションに必要なすべての構成およびスクリプトが含まれています。

ファイルは次のとおりです。

• hive.prm: Replicatパラメータ・ファイル。
• hive.props: Hadoopにデータをステージングし、コマンド・イベント・ハンドラを実行するReplicatプロパティ・ファイル。
• hive.sh: Hadoopにステージングされたデータを読み取り、データをHiveのターゲット表にマージするbash-shellスクリプト。
• hive-ddl.sql: スクリプトhive.shで使用されるサンプル・ターゲット表を含むDDL文。

プロパティ・ファイルhive.propsで、#TODO:コメント付きのプロパティを編集します。

bash-shellスクリプト関数merge()には、ターゲット表にあわせてカスタマイズする必要があるSQL文が含まれています。

8.2.31.6.2.3 マージ・スクリプトの変数

必要に応じて変数を変更します。

#TODO: Modify the location of the OGGBD dirdef directory where the Avro schema files exist.
avroSchemaDir=/opt/ogg/dirdef

#TODO: Edit the JDBC URL to connect to hive.
hiveJdbcUrl=jdbc:hive2://localhost:10000/default
#TODO: Edit the JDBC user to connect to hive.
hiveJdbcUser=APP
#TODO: Edit the JDBC password to connect to hive.
hiveJdbcPassword=mine

#TODO: Edit the replicat group name.
repName=HIVE

#TODO: Edit this. Ensure each replicat uses a unique prefix.
stagingTablePrefix=${repName}_STAGE_

8.2.31.6.2.4 前提条件

前提条件は次のとおりです。

• マージ・スクリプトhive.shを使用するには、Oracle GoldenGate for BigDataのReplicatがインストールされているマシンにbeelineコマンドライン・プログラムをインストールする必要があります。
• カスタム・スクリプトhive.shでは、merge SQL文を使用します。

  Hiveクエリ言語(Hive QL)にはHiveバージョン2.2のmergeのサポートが導入されています。

8.2.31.7 テンプレートのキーワード

テンプレート機能を使用すると、実行時に文字列値をコンテキスト・ベースで解決するために、定数やキーワードを組み合せて使用​​できます。テンプレート機能は、Oracle GoldenGate for Big Dataで、ファイル・パス、ファイル名、トピック名、またはメッセージ・キーを解決するために広く使用されています。この付録では、キーワードと、該当する場合にはそれに関連する引数について説明します。さらに、テンプレートと解決された値を示す例もあります。

テンプレートのキーワード

この表には、トランザクション・レベルのメッセージでそのキーワードがサポートされているかどうかを示す列が含まれています。

キーワード	説明	トランザクション・メッセージのサポート
${fullyQualifiedTableName}	カタログ、スキーマおよび表名の間にピリオド(.)のデリミタを含む、完全修飾表名に解決されます。 たとえば、TEST.DBO.TABLE1です。	なし
${catalogName}	カタログ名に解決されます。	なし
${schemaName}	スキーマ名に解決されます。	なし
${tableName}	短い表名に解決されます。	なし
${opType}	操作の種類(INSERT、UPDATE、DELETEまたはTRUNCATE)に解決されます	なし
${primaryKeys[]}	最初のパラメータはオプションであり、主キー値の間にデリミタを設定できます。デフォルトは_です。	なし
${position}	ソース証跡ファイルのシーケンス番号の後にオフセット(RBA)が続きます。	あり
${opTimestamp}	ソース証跡ファイルからの操作タイムスタンプ。	あり
${emptyString}	""に解決されます。	あり
${groupName}	Replicatプロセスの名前に解決されます。調整された配信を使用している場合は、レプリケートのスレッド番号が付加されたReplicatプロセスの名前に解決されます。	あり
${staticMap[]} または ${staticMap[][]}	キーが完全修飾表名である静的な値に解決されます。キーおよび値は、大カッコの内部に次の形式で指定します: ${staticMap[DBO.TABLE1=value1,DBO.TABLE2=value2]} 2番目のパラメータはオプションのデフォルト値です。表名による検索を使用して値が見つからない場合、かわりにデフォルト値が使用されます。	なし
${xid}	トランザクションIDを解決します。	あり
${columnValue[][]} または ${columnValue[][][]}	キーが完全修飾表名であり、値が解決される列名である列の値に解決されます。たとえば: ${columnValue[DBO.TABLE1=COL1,DBO.TABLE2=COL2]} 2番目のパラメータはオプションであり、列値がnullの場合に使用する値を設定できます。デフォルトは空の文字列""です。 3番目のパラメータはオプションであり、列値がない場合に使用する値を設定できます。デフォルトは空の文字列""です。 パーティション化で${columnValue}キーワードを使用する場合は、列名のみを設定する必要があります。HDFSハンドラおよびファイル・ライター・ハンドラのみがパーティション化をサポートしています。パーティション化の場合、パーティション化構成がソース表ごとに異なるため、表名はすでにわかっています。次に、パーティション化のコンテキストで使用される${columnValue}の例を示します。 ${columnValue[COL1]} または ${columnValue[COL2][NULL][MISSING]}	なし
${currentTimestamp} または ${currentTimestamp[]}	現在のタイムスタンプに解決されます。SimpleDateFormatクラスで説明されているJavaベースの書式設定を使用して、現在のタイムスタンプの書式を制御できます。https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.htmlを参照してください 例: ${currentTimestamp}${currentTimestamp[yyyy-MM-dd HH:mm:ss.SSS]}	あり
${null}	NULL文字列に解決されます。	あり
${custom[]}	カスタム値リゾルバを記述することが可能です。必要に応じて、Oracleサポートに連絡してください。	実装依存
${token[]}	トークン値を解決します。	なし
${toLowerCase[]}	引数を小文字に変換するためのキーワード。引数には定数、キーワードまたは両方の組合せを指定できます。	あり
${toUpperCase[]}	引数を大文字に変換するためのキーワード。引数には定数、キーワードまたは両方の組合せを指定できます。	あり
${substring[][]} または ${substring[][][]}	構成されたコンテンツに対して部分文字列操作を実行するためのキーワード。 サブ文字列機能を実行する文字列。ネストされたキーワード、定数または両方の組合せを指定できます。 開始インデックス。 終了インデックス。(指定されていない場合は、入力文字列の終わりです。)${substring[thisisfun][4]}はisfunを返します。${substring[thisisfun][4][6]}はisを返します。 ノート: substring関数を実行すると、実行時に配列インデックス範囲外状態が発生する可能性があります。これは、構成した開始インデックスまたは終了インデックスが、現在の作用対象の文字列の長さを超える場合に発生します。${substring}関数は実行時例外をスローしません。かわりに、配列インデックス範囲外状態を検出し、検出された場合には部分文字列関数を実行しません。	あり
${regex[][][]}	コンテンツの検索および置換に正規表現を適用するためのキーワード。これには3つの必須パラメータがあります。 正規表現の検索および置換機能を実行する文字列。ネストされたキーワード、定数または両方の組合せを指定できます。 正規表現の検索文字列。 正規表現の置換文字列。	あり
${operationCount}	操作の数を解決するキーワード。	あり
${insertCount}	挿入操作の数を解決するキーワード。	あり
${deleteCount}	削除操作の数を解決するキーワード。	あり
${updateCount}	更新操作の数を解決するキーワード。	あり
${truncateCount}	切捨て操作の数を解決するキーワード。	あり
${uuid}	汎用一意識別子(UUID)を解決するためのキーワード。これは、一意であることが保証された36文字の文字列です。UUIDの例: 7f6e4529-e387-48c1-a1b6-3e7a4146b211	あり

テンプレートの例

テンプレートの構成値の例と解決される値を次に示します。

テンプレートの例	解決される値
${groupName}_${fullyQualfiedTableName}	KAFKA001_DBO.TABLE1
prefix_${schemaName}_${tableName}_suffix	prefix_DBO_TABLE1_suffix
${currentTimestamp[yyyy-MM-dd HH:mm:ss.SSS]}	2017-05-17 11:45:34.254
A_STATIC_VALUE	A_STATIC_VALUE

8.2.31.8 Velocity依存性

Oracle GoldenGate for Big Dataリリース21.1.0.0.0から、Velocity jarファイルがパッケージから削除されました。

Velocityフォーマットを機能させるには、jarをダウンロードし、gg.classpathを変更してこれらをランタイムに含める必要があります。

VelocityのMaven座標は次のとおりです。

Maven groupId: org.apache.velocity

Maven artifactId: velocity

バージョン: 1.7