1. Oracle GoldenGate for Big Dataの使用
  2. Oracle Cloud Infrastructureイベント・ハンドラの使用

9 Oracle Cloud Infrastructureイベント・ハンドラの使用

Oracle Cloud Infrastructureイベント・ハンドラを使用して、ファイル・ライター・ハンドラによって生成されたファイルをOracle Cloud Infrastructureオブジェクト・ストアにロードします。

このトピックでは、OCIイベント・ハンドラの使用方法について説明します。

9.1 概要

Oracle Cloud Infrastructure Object Storageサービスは、信頼性およびコスト効率が高いデータ耐久性を実現するインターネット規模の高パフォーマンス・ストレージ・プラットフォームです。Object Storageサービスは、分析データやリッチ・コンテンツ(イメージやビデオなど)を含め、あらゆるコンテンツ・タイプの非構造化データを無制限に格納できます。https://cloud.oracle.com/en_US/cloud-infrastructureを参照してください。

ファイル・ライター・ハンドラでサポートされるフォーマット・ハンドラはすべて使用できます。

親トピック: Oracle Cloud Infrastructureイベント・ハンドラの使用

9.2 機能の詳細

Oracle Cloud Infrastructureイベント・ハンドラには、Oracle Cloud Infrastructure Object Storageにファイルを転送するためのOracle Cloud Infrastructure Javaソフトウェア開発キット(SDK)が必要です。Oracle GoldenGate for Big Dataには、Oracle Cloud Infrastructure Java SDKが付属していません。 https://docs.cloud.oracle.com/iaas/Content/API/Concepts/sdkconfig.htmを参照してください。

Oracle Cloud Infrastructure Java SDKは、次の場所でダウンロードする必要があります。

https://docs.us-phoenix-1.oraclecloud.com/Content/API/SDKDocs/javasdk.htm

JARファイルを永続ディレクトリに解凍します。ハンドラには、Oracle Cloud Infrastructure SDK JARがあるJARライブラリ・ディレクトリとサード・パーティのJARライブラリの2つのディレクトリが必要です。両方のディレクトリは、gg.classpathにある必要があります。

環境変数gg.classpathを指定し、Oracle Cloud Infrastructure Java SDKのJARファイルを含めます。

例

gg.classpath=/usr/var/oci/lib/*:/usr/var/oci/third-party/lib/*

詳細は、OCI依存性を参照してください。

親トピック: Oracle Cloud Infrastructureイベント・ハンドラの使用

9.3 Oracle Cloud Infrastructureイベント・ハンドラの構成

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

Oracle Cloud Infrastructureイベント・ハンドラは、ファイル・ライター・ハンドラとの組合せでのみ機能します。

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

表9-1 Oracle Cloud Infrastructureイベント・ハンドラの構成プロパティ

プロパティ 必須/オプション 有効な値 デフォルト 説明

gg.eventhandler.name.type

必須

oci

なし

Oracle Cloud Infrastructureイベント・ハンドラを選択します。
gg.eventhandler.name.contentType オプション リソースのメディア・タイプを示すために使用される有効なコンテンツ・タイプ値。 application/octet-stream オブジェクトのコンテンツ・タイプ。
gg.eventhandler.name.contentEncoding オプション 有効な値は、適用されるエンコーディングを示します。 utf-8 オブジェクトのコンテンツ・エンコーディング。
gg.eventhandler.name.contentLanguage オプション 利用者のための有効な言語。 en オブジェクトのコンテンツ言語。

gg.eventhandler.name.configFilePath

必須

イベント・ハンドラのconfigファイルへのパス。

なし

構成ファイルの名前および場所。

gg.eventhandler.name.profile

必須

プロファイル名を表す有効な文字列。

なし

Oracle Cloud Infrastructureのconfigファイルでは、エントリがプロファイル名で識別されます。デフォルトのプロファイルはDEFAULTです。ADMIN_USERなどのプロファイルを追加できます。ADMIN_USERプロファイル(またはconfigファイルに追加する他のプロファイル)に明示的に定義されていない値は、DEFAULTプロファイルから継承されます。

gg.eventhandler.name.namespace

必須

Oracle Cloud Infrastructureのネームスペース。

なし

ネームスペースは、すべてのバケットおよびオブジェクトの最上位レベルのコンテナとして機能し、ユーザーのテナント内のバケット命名を制御できます。オブジェクト・ストレージのネームスペースは、アカウントの作成時に割り当てられるシステム生成文字列です。ネームスペース文字列は、Oracle Cloud Infrastructureコンソールの使用中に「Object Storage Settings」に示されます。

gg.eventhandler.name.region

必須

Oracle Cloud Infrastructureのリージョン。

なし

Oracle Cloud Infrastructureのサーバーおよびデータはリージョンでホストされ、ローカライズされた地理的領域です。

有効なリージョン識別子は、「Oracle Cloud Infrastructure Documentation - Regions and Availability Domains」に一覧表示されています。

gg.eventhandler.name.compartmentID

必須

有効なコンパートメントID。

なし

コンパートメントは、Oracle Cloud Infrastructureのリソースを編成するための論理コンテナです。compartmentIDは、Oracle Cloud Infrastructureコンソールの使用中に「Bucket Details」に示されます。

gg.eventhandler.name.pathMappingTemplate

必須

ファイルを書き込むOracle Cloud Infrastructureバケットのパスを動的に生成するために使用される、解決可能なキーワードと定数を含む文字列。

なし

定数とともにインタレースされるキーワードを使用して、実行時に一意のOracle Cloud Infrastructureパス名を動的に生成します。

gg.eventhandler.name.fileNameMappingTemplate

オプション

実行時にOracle Cloud Infrastructureファイル名を動的に生成するために使用される、解決可能なキーワードと定数を含む文字列。

なし

解決可能なキーワードと定数を使用して、実行時にOracle Cloud Infrastructureデータ・ファイル名を動的に生成します。設定しない場合、アップストリームのファイル名が使用されます。

gg.eventhandler.name.bucketMappingTemplate

必須

ファイルを書き込むOracle Cloud Infrastructureバケットのパスを動的に生成するために使用される、解決可能なキーワードと定数を含む文字列。

なし

解決可能なキーワードと定数を使用して、実行時にOracle Cloud Infrastructureバケット名を動的に生成します。Oracle Cloud Infrastructureバケットが存在しない場合、イベント・ハンドラはOracle Cloud Infrastructureバケットを作成しようとします。

gg.eventhandler.name.finalizeAction

オプション

none | delete

なし

ファイナライズ・アクションでOracle Cloud Infrastructureデータ・ファイルを残す場合は、noneに設定します。ファイナライズ・アクションでOracle Cloud Infrastructureデータ・ファイルを削除する場合は、deleteに設定します。

gg.eventhandler.name.eventHandler

オプション

子イベント・ハンドラを相互参照する一意の文字列識別子。

イベント・ハンドラは構成されません。

ファイル・ロール・イベントで呼び出されるイベント・ハンドラを設定します。イベント・ハンドラは、S3へのファイルのロード、ParquetまたはORCフォーマットへの変換、HDFSへのファイルのロード、Oracle Cloud Infrastructure Storage Classicへのファイルのロード、Oracle Cloud Infrastructureへのファイルのロードなどのファイル・ロール・イベント・アクションを実行できます。
gg.eventhandler.name.proxyServer オプション プロキシ・サーバーのホスト名。 なし OCI接続でプロキシ・サーバーを介したルーティングが必要な場合は、プロキシ・サーバーのホスト名に設定します。
gg.eventhandler.name.proxyPort オプション プロキシ・サーバーのポート番号。 なし OCI接続でプロキシ・サーバーを介したルーティングが必要な場合は、プロキシ・サーバーのポート番号に設定します。
gg.eventhandler.name.proxyProtocol オプション HTTP | HTTPS HTTP セキュリティ・レベルの追加のためにプロキシ・サーバーへのプロキシ・プロトコル接続を設定します。プロキシ・サーバーの大部分はHTTPをサポートしています。プロキシ・サーバーがHTTPSをサポートし、HTTPSが必要な場合にのみこれを設定します。
gg.eventhandler.name.proxyUsername オプション プロキシ・サーバーのユーザー名。 なし 資格証明が必要な場合、プロキシ・サーバーに接続するためのユーザー名を設定します。ほとんどのプロキシ・サーバーでは、資格証明は必要ありません。
gg.eventhandler.name.proxyPassword オプション プロキシ・サーバーのパスワード。 なし 資格証明が必要な場合、プロキシ・サーバーに接続するためのパスワードを設定します。ほとんどのプロキシ・サーバーでは、資格証明は必要ありません。

サンプル構成

gg.eventhandler.oci.type=oci
gg.eventhandler.oci.configFilePath=~/.oci/config
gg.eventhandler.oci.profile=DEFAULT
gg.eventhandler.oci.namespace=dwcsdemo
gg.eventhandler.oci.region=us-ashburn-1
gg.eventhandler.oci.compartmentID=ocid1.compartment.oc1..aaaaaaaajdg6iblwgqlyqpegf6kwdais2gyx3guspboa7fsi72tfihz2wrba
gg.eventhandler.oci.pathMappingTemplate=${schemaName}
gg.eventhandler.oci.bucketMappingTemplate=${schemaName}
gg.eventhandler.oci.fileNameMappingTemplate=${tableName}_${currentTimestamp}.txt
gg.eventhandler.oci.finalizeAction=NONE
goldengate.userexit.writers=javawriter

親トピック: Oracle Cloud Infrastructureイベント・ハンドラの使用

9.4 Oracle Cloud Infrastructureの資格証明の構成

Java SDKが機能するには、ユーザー資格証明などの基本構成情報およびOracle Cloud InfrastructureのテナントOracle Cloud ID (OCID)が必要です。https://docs.cloud.oracle.com/iaas/Content/General/Concepts/identifiers.htmを参照してください。

理想的な構成ファイルには、user、fingerprint、key_file、tenancyおよびregionの各キーとそれぞれの値が含まれます。デフォルトの構成ファイルの名前と場所は、~/.oci/configです。

次のように、configファイルを作成します。

  1. Oracle GoldenGate for Big Dataホーム・ディレクトリに.ociというディレクトリを作成します。

  2. テキスト・ファイルを作成し、configと名前を付けます。

  3. 次のプロパティの値を取得します。

    user

    1. Oracle Cloud Infrastructureコンソール(https://console.us-ashburn-1.oraclecloud.com)にログインします。

    2. 「Username」をクリックします。

    3. 「User Settings」をクリックします。

      ユーザーのOCIDが表示され、これがキー・ユーザーの値です。

    tenancy

    テナントIDがコンソール・ページの下部に表示されます。

    region

    コンソールのヘッダー・セッション・ドロップダウン・メニューでリージョンが表示されます。

    fingerprint

    フィンガープリントを生成するには、次のキーのフィンガープリントの取得方法の手順に従います。

    https://docs.cloud.oracle.com/iaas/Content/API/Concepts/apisigningkey.htm

    key_file

    Oracle Cloud Infrastructureとの接続を確立するには、公開キーと秘密キーを共有する必要があります。キーを生成するには、次のAPI署名キーの生成方法に従います。

    https://docs.cloud.oracle.com/iaas/Content/API/Concepts/apisigningkey.htm

構成ファイルの例

user=ocid1.user.oc1..aaaaaaaat5nvwcna5j6aqzqedqw3rynjq
fingerprint=20:3b:97:13::4e:c5:3a:34
key_file=~/.oci/oci_api_key.pem
tenancy=ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr44h25vqstifs

親トピック: Oracle Cloud Infrastructureイベント・ハンドラの使用

9.5 テンプレート文字列の使用

テンプレート文字列には、実行時に動的に解決されるリテラルとキーワードの組合せを含めることができます。このイベント・ハンドラは、テンプレート文字列を大量に使用して、Oracle Cloud Infrastructureディレクトリ名、データ・ファイル名およびOracle Cloud Infrastructureバケット名を生成します。これらの文字列によって、データ・ファイルおよびデータ・ファイルの名前を書き込む場所を柔軟に選択できます。ファイルおよびディレクトリの名前を選択する場合は、異常終了の原因となる可能性があるファイル命名の競合を回避するように注意する必要があります。

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

キーワード 説明
${fullyQualifiedTableName}

ピリオド(.)で区切られた完全修飾ソース表名。たとえば、MYCATALOG.MYSCHEMA.MYTABLE。

${catalogName}

個々のソース・カタログ名。たとえば、MYCATALOG。

${schemaName}

個々のソース・スキーマ名。たとえば、MYSCHEMA。

${tableName}

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

${groupName}

Replicatプロセスの名前(調整された適用を使用する場合は、スレッド番号を含む)。
${emptyString}

空の文字列になります。たとえば、""
${operationCount}

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

${insertCount}

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

${updateCount}

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

${deleteCount}

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

${truncateCount}

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

${currentTimestamp}

現在のタイムスタンプ。日時のデフォルトの出力形式はyyyy-MM-dd_HH-mm-ss.SSSです。たとえば、2017-07-05_04-31-23.123。または、次のように角カッコ内に形式を挿入して、現在のタイムスタンプの形式をカスタマイズできます。

${currentTimestamp[MM-dd_HH]}

この形式は、JavaのSimpleDateFormatクラスで定義された構文を使用します。https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.htmlを参照してください。

${toUpperCase[]}

角カッコ内のコンテンツを大文字に変換します。たとえば、${toUpperCase[${fullyQualifiedTableName}]}。

${toLowerCase[]}

角カッコ内のコンテンツを小文字に変換します。たとえば、${toLowerCase[${fullyQualifiedTableName}]}。

テンプレート文字列の構成では、キーワードおよび静的文字列の組合せを使用して、実行時にパスとデータ・ファイル名を構成できます。

パスの構成例 
/usr/local/${fullyQualifiedTableName}
データ・ファイルの構成例 
${fullyQualifiedTableName}_${currentTimestamp}_${groupName}.txt

要件

テンプレートを使用して生成されたディレクトリ名およびファイル名は、書込み先のシステム上で有効である必要があります。ファイル名の競合を避けるために、ファイル名は一意である必要があります。${currentTimestamp}キーワードを使用して、現在のタイムスタンプを追加すると、競合を回避できます。調整された適用を使用している場合は、データ・ファイル名に${groupName}を追加することをお薦めします。

親トピック: Oracle Cloud Infrastructureイベント・ハンドラの使用

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

接続の問題

オンプレミスで実行していて、OCIイベント・ハンドラがOCIオブジェクト・ストレージに接続できない場合は、プロキシ・サーバーによってパブリック・インターネットへの接続が保護されている可能性が高くなります。プロキシ・サーバーは、企業のプライベート・ネットワークとパブリック・インターネットとの間のゲートウェイとして機能します。プロキシ・サーバーのURLを取得するには、ネットワーク管理者に問い合せてください。

OCIへのOracle GoldenGate for Big Dataの接続は、次の構成プロパティを設定することで、プロキシ・サーバーを介してルーティングできます。

gg.eventhandler.name.proxyServer={insert your proxy server name}
gg.eventhandler.name.proxyPort={insert your proxy server port number}

ClassNotFoundExceptionエラー

最も一般的な初期エラーは、必要なすべてのクライアント・ライブラリが含まれていない正しくないクラスパスで、これによりClassNotFoundExceptionエラーが発生します。Oracle Cloud Infrastructure Java SDKの必要なJARファイルをすべて含めるためにgg.classpath変数を指定します。機能の詳細を参照してください。

親トピック: Oracle Cloud Infrastructureイベント・ハンドラの使用