5 ファイル・ライター・ハンドラの使用
ファイル・ライター・ハンドラおよび関連イベント・ハンドラを使用すると、データ・ファイルをローカル・システムに書き込むことができます。
この章では、ファイル・ライター・ハンドラの使用方法について説明します。
- 概要
ファイル・ライター・ハンドラとイベント・ハンドラを使用してデータを変換できます。
5.1 概要
ファイル・ライター・ハンドラとイベント・ハンドラを使用してデータを変換できます。
ファイル・ライター・ハンドラは、区切りテキスト、XML、JSON、AvroおよびAvroオブジェクト・コンテナ・ファイル形式でのデータ・ファイルの生成をサポートします。抽出、ロードおよび変換のユースケースに対応するためのものです。データ・ファイルは、ローカル・ファイル・システム上にステージングされます。その後、データ・ファイルへの書込みが完了すると、サード・パーティ・アプリケーションを使用して、追加処理を実行するファイルを読み取ることができます。
ファイル・ライター・ハンドラは、イベント・ハンドラ・フレームワークもサポートしています。イベント・ハンドラ・フレームワークを使用すると、ファイル・ライター・ハンドラで生成されたデータ・ファイルを、Optimized Row Columnar (ORC)やParquetなどの他の形式に変換できます。データ・ファイルは、HDFSやAmazon S3などのサード・パーティ・アプリケーションにロードできます。イベント・ハンドラ・フレームワークは、より多くのイベント・ハンドラが様々な変換を実行したり、開発される別のターゲットにロードできるように拡張できます。また、ビッグ・データ環境用のカスタム・イベント・ハンドラを開発できます。
Oracle GoldenGate for Big Dataには、HDFSに書き込む2つのハンドラが用意されています。次の状況では、HDFSハンドラまたはファイル・ライター・ハンドラを使用することをお薦めします。
- HDFSイベント・ハンドラが、HDFSにデータを直接ストリーミングするように設計されています。
-
HDFSで書込み後処理が発生しません。HDFSイベント・ハンドラではファイルの内容を変更せず、単に、既存のファイルをHDFSにアップロードします。
分析ツールが、開いていて頻繁に書き込まれるファイル内のデータなど、HDFSに書き込まれるデータにリアルタイムでアクセスします。
- -ファイル・ライター・ハンドラが、ファイルの書込みが完了したときにローカル・ファイル・システムにデータをステージングし、完了したデータ・ファイルをHDFSにロードするように設計されています。
-
分析ツールが、HDFSに書き込まれるデータにリアルタイムでアクセスしません。
データを変換、リフォーマット、マージおよび最終的な場所に移動する書込み後処理がHDFSで発生します。
データ・ファイルがORCまたはParquet形式でHDFSに書き込まれます。
5.1.1 機能の詳細
5.1.1.1 ファイル・ロール・イベントの使用
ファイル・ロール・イベントは、特定のデータ・ファイルへの書込みが完了したときに発生します。その特定のデータ・ファイルには、これ以上データが書き込まれません。
ファイナライズ・アクション操作
次のオプションとともにfinalizeaction
パラメータを使用してファイナライズ・アクション操作を構成し、ファイル・ロール・アクションが正常に実行された後に特定のデータ・ファイルがクリーン・アップされるようにできます。
-
none
-
データ・ファイルをそのままにします(アクティブな書込み接尾辞を削除します。「アクティブな書込み接尾辞について」を参照)。
-
delete
-
データ・ファイルを削除します(データ・ファイルが別の形式に変換されていたり、サード・パーティ・アプリケーションにロードされている場合)。
-
move
-
ファイル名を維持(アクティブな書込み接尾辞を削除)しますが、ファイルを
movePathMappingTemplate
プロパティを使用して解決したディレクトリに移動します。 -
rename
-
現在のディレクトリを維持しますが、
fileRenameMappingTemplate
プロパティを使用して、データ・ファイルの名前を変更します。 -
move-rename
-
fileRenameMappingTemplate
プロパティによって生成されたファイル名を使用してファイル名を変更し、movePathMappingTemplate
プロパティを使用して解決したディレクトリにファイルを移動します。
通常、イベント・ハンドラは、これらの同じアクションのサブセットを提供します。
ファイナライズ・アクション操作のサンプル構成を次に示します。
gg.handlerlist=filewriter
#The File Writer Handler
gg.handler.filewriter.type=filewriter
gg.handler.filewriter.mode=op
gg.handler.filewriter.pathMappingTemplate=./dirout/evActParamS3R
gg.handler.filewriter.stateFileDirectory=./dirsta
gg.handler.filewriter.fileNameMappingTemplate=${fullyQualifiedTableName}_${currentTimestamp}.txt
gg.handler.filewriter.fileRollInterval=7m
gg.handler.filewriter.finalizeAction=delete
gg.handler.filewriter.inactivityRollInterval=7m
ファイル・ローリング・アクション
次のすべてのアクションによって、ファイル・ロール・イベントがトリガーされます。
-
メタデータ変更イベント。
-
構成ファイルの最大サイズ超過
-
ファイル・ロールの間隔超過(現在時刻から最初のファイル書込み時刻を差し引いた時間が、ファイル・ロール間隔よりも大きい)。
-
非アクティブ・ロールの間隔超過(現在時刻から最後のファイル書込み時刻を差し引いた時間が、ファイル・ロール間隔よりも大きい)。
-
ファイル・ライター・ハンドラはシャットダウン時にロールするよう構成されている場合のReplicatプロセスの停止。
操作シーケンス
ファイル・ロール・イベントによって、操作のシーケンスの発生がトリガーされます。個々のデータファイルがロールされたときに発生する操作の順序を理解することが重要です。
-
アクティブなデータ・ファイルが非アクティブに切り替えられ、データ・ファイルがフラッシュされて、状態データ・ファイルがフラッシュされます。
-
構成されたイベント・ハンドラは、指定された順序で呼び出されます。
-
ファイナライズ・アクションは、すべてのイベント・ハンドラで、構成した順序と逆の順序で実行されます。構成したすべてのファイナライズ・アクションが実行されます。
-
ファイナライズ・アクションは、データ・ファイルおよび状態ファイルに対して実行されます。すべてのアクションが正常に完了すると、状態ファイルが削除されます。構成したすべてのファイナライズ・アクションが実行されます。
たとえば、Parquetイベント・ハンドラとS3イベント・ハンドラを使用してファイル・ライター・ハンドラを構成する場合、ロール・イベントの順序は次のようになります。
-
アクティブなデータ・ファイルが非アクティブに切り替えられ、データ・ファイルがフラッシュされて、状態データ・ファイルがフラッシュされます。
-
Parquetイベント・ハンドラが呼び出され、ソース・データ・ファイルからParquetファイルが生成されます。
-
S3イベント・ハンドラが呼び出され、生成されたParquetファイルがS3にロードされます。
-
ファイナライズ・アクションが、S3 Parquetイベント・ハンドラに対して実行されます。構成したすべてのファイナライズ・アクションが実行されます。
-
ファイナライズ・アクションが、Parquetイベント・ハンドラに対して実行されます。構成したすべてのファイナライズ・アクションが実行されます。
-
ファイナライズ・アクションが、ファイル・ライター・ハンドラのデータ・ファイルに対して実行されます
親トピック: 機能の詳細
5.1.1.2 自動ディレクトリの作成
親トピック: 機能の詳細
5.1.1.3 アクティブな書込み接尾辞について
一般的なユースケースでは、サード・パーティ・アプリケーションを使用して、データ・ファイルを読み取る書込みディレクトリを監視します。サード・パーティ・アプリケーションは、ファイルへの書込みが完了した場合にのみデータ・ファイルを読み取ることができます。これらのアプリケーションでは、データ・ファイルへの書込みがアクティブであるか、または完了しているかを判別する方法が必要になります。ファイル・ライター・ハンドラを使用すると、次のプロパティを使用してアクティブな書込み接尾辞を構成できます。
gg.handler.name.fileWriteActiveSuffix=.tmp
このプロパティの値は、生成されたファイル名に付加されます。ファイルへの書込みが完了すると、データ・ファイルの名前が変更され、アクティブな書込み接尾辞がファイル名から削除されます。データ・ファイル名を監視し、アクティブな書込み接尾辞がいつ削除されたかを識別するように、サード・パーティ・アプリケーションを設定できます。
親トピック: 機能の詳細
5.1.1.4 状態のメンテナンス
これまでは、すべてのOracle GoldenGate for Big Dataハンドラがステートレスでした。これらのステートレス・ハンドラでは、実行していたReplicatプロセスのコンテキストでの状態のみを保持します。Replicatプロセスを停止して再起動した場合、すべての状態が失われていました。Replicatを再起動すると、ハンドラは、前回の実行時の状況の認識がない状態で書込みを開始しました。
ファイル・ライター・ハンドラは、Replicatプロセスの呼出し間で状態を維持するための機能を提供します。デフォルトでは、再起動に伴って次のことが実行されます。
-
状態保存ファイルが読み取られます。
-
状態がリストアされます。
-
前回の実行が停止した位置からアクティブ・データ・ファイルの追加が続行されます。
次のプロパティを設定することで、このデフォルトのアクションから、シャットダウン時にすべてのファイルのロールが必要になるように変更できます。
gg.handler.name.rollOnShutdown=true
親トピック: 機能の詳細
5.1.1.5 テンプレート文字列の使用
テンプレート文字列には、実行時に動的に解決されるリテラルとキーワードの組合せを含めることができます。ORCイベント・ハンドラは、テンプレート文字列を多用して、ORCディレクトリ名、データ・ファイル名およびORCバケット名を生成します。これらの文字列によって、データ・ファイルおよびデータ・ファイルの名前を書き込む場所を柔軟に選択できます。ファイルおよびディレクトリの名前を選択する場合は、異常終了の原因となる可能性があるファイル命名の競合を回避するように注意する必要があります。
サポートされているテンプレート文字列
キーワード | 説明 |
---|---|
${fullyQualifiedTableName} |
ピリオド( |
${catalogName} |
個々のソース・カタログ名。たとえば、 |
${schemaName} |
個々のソース・スキーマ名。たとえば、 |
${tableName} |
個々のソース表名。たとえば、 |
${groupName} |
Replicatプロセスの名前(調整された適用を使用する場合は、スレッド番号を含む)。 |
${emptyString} |
空の文字列になります。たとえば、 |
${operationCount} |
データ・ファイル内の操作の合計数。名前変更か、イベント・ハンドラで使用する必要があります。それ以外の場合、何もまだ書き込まれていないため、ゼロ( |
${insertCount} |
データ・ファイル内の挿入操作の合計数。名前変更か、イベント・ハンドラで使用する必要があります。それ以外の場合、何もまだ書き込まれていないため、ゼロ( |
${updateCount} |
データ・ファイル内の更新操作の合計数。名前変更か、イベント・ハンドラで使用する必要があります。それ以外の場合、何もまだ書き込まれていないため、ゼロ( |
${deleteCount} |
データ・ファイル内の削除操作の合計数。名前変更か、イベント・ハンドラで使用する必要があります。それ以外の場合、何もまだ書き込まれていないため、ゼロ( |
${truncateCount} |
データ・ファイル内の切捨て操作の合計数。名前変更か、イベント・ハンドラで使用する必要があります。それ以外の場合、何もまだ書き込まれていないため、ゼロ( |
${currentTimestamp} |
現在のタイムスタンプ。日時のデフォルトの出力形式は
この形式は、Javaの |
${toUpperCase[]} |
角カッコ内のコンテンツを大文字に変換します。たとえば、 |
${toLowerCase[]} |
角カッコ内のコンテンツを小文字に変換します。たとえば、 |
テンプレート文字列の構成では、キーワードおよび静的文字列の組合せを使用して、実行時にパスとデータ・ファイル名を構成できます。
要件
テンプレートを使用して生成されたディレクトリ名およびファイル名は、書込み先のシステム上で有効である必要があります。ファイル名の競合を避けるために、ファイル名は一意である必要があります。${currentTimestamp}
キーワードを使用して、現在のタイムスタンプを追加すると、競合を回避できます。調整された適用を使用している場合は、データ・ファイル名に${groupName}
を追加することをお薦めします。
親トピック: 機能の詳細
5.1.2 ファイル・ライター・ハンドラの構成
ファイル・ライター・ハンドラの構成可能な値を示しています。これらのプロパティは、Javaアダプタ・プロパティ・ファイルにあります(Replicatプロパティ・ファイルにはありません)
ファイル・ライター・ハンドラの選択を有効にするには、まずgg.handler.name.type=filewriter
およびその他のファイル・ライター・プロパティを次のように指定してハンドラ・タイプを構成する必要があります。
表5-1 ファイル・ライター・ハンドラの構成プロパティ
プロパティ | 必須/オプション | 有効な値 | デフォルト | 説明 |
---|---|---|---|---|
|
必須 |
|
なし |
使用するファイル・ライター・ハンドラを選択します。 |
|
オプション |
デフォルトの測定単位はバイトです。 |
1g |
ファイル・ライター・ハンドラによって生成されるファイルの最大ファイル・サイズを設定します。ファイル・サイズが超過すると、ロール・イベントがトリガーされます。 |
|
オプション |
デフォルトの測定単位はミリ秒です。 |
ファイルのローリング・オン時間がオフ。 |
タイマーは、ファイルが作成されるときにスタートします。間隔が経過したときにまだファイルが開いている場合、ファイル・ロール・イベントがトリガーされます。 |
|
オプション |
デフォルトの測定単位はミリ秒です。 |
ファイルの非アクティブ・ローリングがオフ。 |
タイマーは、生成されたファイルへの前回の書込みからスタートします。生成されたファイルへの新しい書込みでカウンタが再開されます。タイマーが経過したときにまだファイルが開いている場合、ロール・イベントがトリガーされます。 |
|
必須 |
実行時にファイル・ライター・ハンドラのデータ・ファイル名を動的に生成するために使用される、解決可能なキーワードと定数を含む文字列。 |
なし |
定数とともにインタレースされるキーワードを使用して、一意のパス名を実行時に動的に生成します。パス名は、通常、 |
|
必須 |
ファイルが書き込まれるディレクトリを動的に生成するために使用される、解決可能なキーワードと定数を含む文字列。 |
なし |
定数とともにインタレースされるキーワードを使用して、一意のパス名を実行時に動的に生成します。パス名は、通常、 |
|
オプション |
文字列。 |
なし |
ファイルへの書込みがアクティブであることを示すために、ファイル・ライター・ハンドラによって生成されたファイルに付加されるオプションの接尾辞。ファイナライズ・アクションで、接尾辞が削除されます。 |
|
必須 |
ファイル・ライター・ハンドラの状態ファイルを格納するローカル・マシン上のディレクトリ。 |
なし |
ファイル・ライター・ハンドラの状態ファイルを格納するローカル・マシン上のディレクトリを設定します。調整された適用環境での操作時に機能するように、グループ名がディレクトリに追加されます。 |
|
オプション |
|
|
|
|
オプション |
|
|
ファイナライズ・アクションでのファイル・ライター・ハンドラの動作を示します。
|
|
オプション |
|
|
|
|
オプション |
|
イベント・ハンドラは構成されない。 |
イベント・ハンドラを相互参照する一意の文字列識別子。イベント・ハンドラは、ファイル・ロール・イベントで呼び出されます。イベント・ハンドラは、S3へのファイルのロード、ParquetまたはORC形式への変換、HDFSへのファイルのロードなどのファイル・ロール・イベントのアクションを実行できます。 |
|
|
ファイナライズ・アクションにおけるファイルの名前変更用にファイル・ライター・ハンドラのデータ・ファイル名を動的に生成するために使用される、解決可能なキーワードと定数を含む文字列。 |
なし。 |
定数とともにインタレースされるキーワードを使用して、一意のファイル名を実行時に動的に生成します。ファイル名は、通常、 |
|
|
ファイルが書き込まれるディレクトリを動的に生成するために使用される、解決可能なキーワードと定数を含む文字列。 |
なし |
定数とともにインタレースされるキーワードを使用して、一意のパス名を実行時に動的に生成します。パス名は、通常、 |
|
必須 |
|
|
出力データのフォーマット方法について、HDFSハンドラのフォーマッタを選択します
ParquetまたはORCイベント・ハンドラを使用する場合、選択した形式が |
|
オプション |
16進文字の偶数。 |
なし |
各2文字がバイト・オーダー・マーク(BOM)で1バイトに対応している16進文字の偶数を入力します。たとえば、文字列 |
|
オプション |
|
|
制御ファイルを作成するには、 |
|
オプション |
任意の文字列 |
改行( |
制御ファイルで区切り文字で区切られたファイル名を制御できます。このプロパティでは |
|
オプション |
制御ファイルを格納するディレクトリのパス。 |
ピリオド( |
制御ファイルを作成する場所を指定するように設定されます。 |
|
オプション |
|
|
所有者ファイルを作成するには、 |
|
オプション |
開いているすべてのファイルのロール・アクションをトリガーするために1回以上。 |
なし |
次の形式で1つ以上のトリガー時刻を構成します。 HH:MM,HH:MM,HH:MM エントリは24時間制に基づきます。たとえば、1日のうち3回個別の時刻にロールされるアクションを構成するエントリは次のとおりです。 gg.handler.fw.atTime=03:30,21:00,23:51 |
|
オプション |
圧縮なし。 |
|
生成されたAvro OCFファイルに対応する圧縮アルゴリズムを有効にします。圧縮を有効にしたら、対応する圧縮ライブラリを |
|
オプション |
|
正の整数 >= 512 |
アクティブな書込みストリームごとに |
親トピック: 概要
5.1.3 サンプル構成の確認
このファイル・ライター・ハンドラの構成例では、Parquetイベント・ハンドラを使用して、データ・ファイルをParquetに変換し、その後、S3イベント・ハンドラ用にParquetファイルをS3にロードしています。
gg.handlerlist=filewriter #The handler properties gg.handler.name.type=filewriter gg.handler.name.mode=op gg.handler.name.pathMappingTemplate=./dirout gg.handler.name.stateFileDirectory=./dirsta gg.handler.name.fileNameMappingTemplate=${fullyQualifiedTableName}_${currentTimestamp}.txt gg.handler.name.fileRollInterval=7m gg.handler.name.finalizeAction=delete gg.handler.name.inactivityRollInterval=7m gg.handler.name.format=avro_row_ocf gg.handler.name.includetokens=true gg.handler.name.partitionByTable=true gg.handler.name.eventHandler=parquet gg.handler.name.rollOnShutdown=true gg.eventhandler.parquet.type=parquet gg.eventhandler.parquet.pathMappingTemplate=./dirparquet gg.eventhandler.parquet.writeToHDFS=false gg.eventhandler.parquet.finalizeAction=delete gg.eventhandler.parquet.eventHandler=s3 gg.eventhandler.parquet.fileNameMappingTemplate=${tableName}_${currentTimestamp}.parquet gg.handler.filewriter.eventHandler=s3 gg.eventhandler.s3.type=s3 gg.eventhandler.s3.region=us-west-2 gg.eventhandler.s3.proxyServer=www-proxy.us.oracle.com gg.eventhandler.s3.proxyPort=80 gg.eventhandler.s3.bucketMappingTemplate=tomsfunbucket gg.eventhandler.s3.pathMappingTemplate=thepath gg.eventhandler.s3.finalizeAction=none goldengate.userexit.writers=javawriter
親トピック: 概要