11 S3イベント・ハンドラの使用

Amazon S3 Webサービスへのインタフェースを提供するS3イベント・ハンドラを使用する方法について学習します。

• 概要
  
• 機能の詳細
  
• S3イベント・ハンドラの構成
  

11.1 概要

Amazon S3は、Amazonクラウドでホストされているオブジェクト・ストレージです。S3イベント・ハンドラの目的は、ファイル・ライター・ハンドラによって生成されたデータ・ファイルをAmazon S3にロードすることです。https://aws.amazon.com/s3/を参照してください。

ファイル・ライター・ハンドラの任意の形式を使用できます。「ファイル・ライター・ハンドラの使用」を参照してください。

11.2 機能の詳細

S3イベント・ハンドラには、ファイルをS3オブジェクト・ストレージに移動するためにAmazon Web Services (AWS) Java SDKが必要です。Oracle GoldenGate for Big Dataには、AWS Java SDKが含まれていません。AWS Java SDKを次のサイトからダウンロードしてインストールする必要があります。

https://aws.amazon.com/sdk-for-java/

次に、AWS Java SDKのJARファイルが含まれ、2つのディレクトリに分割されるようにgg.classpath変数を構成する必要があります。両方のディレクトリが、次のようにgg.classpathにある必要があります。

gg.classpath=/usr/var/aws-java-sdk-1.11.240/lib/*:/usr/var/aws-java-sdk-1.11.240/third-party/lib/

• クライアントIDとシークレットの構成
  
• AWS S3バケットについて
  
• テンプレート文字列の使用
  
• トラブルシューティング
  

11.2.1 クライアントIDとシークレットの構成

クライアントIDおよびシークレットは、S3イベント・ハンドラがAmazon S3とやりとりするために必要な資格証明です。クライアントIDおよびシークレットは、Amazon AWSのWebサイトを使用して生成されます。これらの資格証明の取得とS3サーバーへの提示は、AWS Java SDKによってクライアント側で実行されます。AWS Java SDKにより、実行時にクライアントIDおよびシークレットを解決できる複数の方法が提供されます。

クライアントIDおよびシークレットは、Javaアダプタ・プロパティ・ファイルでJavaプロパティとして次のように1行で設定できます。

javawriter.bootoptions=-Xmx512m -Xms32m -Djava.class.path=ggjava/ggjava.jar -Daws.accessKeyId=your_access_key -Daws.secretKey=your_secret_key

これにより、ローカル・マシン上のAmazon Elastic Compute Cloud (Amazon EC2) AWS_ACCESS_KEY_IDおよびAWS_SECRET_ACCESS_KEY変数を使用して環境変数が設定されます。

11.2.2 AWS S3バケットについて

AWSでは、S3ストレージをバケットと呼ばれる個別のファイル・システムに分割します。S3イベント・ハンドラは、事前作成されたバケットに書き込むことができます。または、S3バケットが存在しない場合、S3イベント・ハンドラは、指定されたS3バケットを作成しようとします。AWSでは、S3バケット名を小文字にする必要があります。Amazon S3バケット名はグローバルに一意である必要があります。Amazonアカウントにすでに存在するS3バケットを作成しようとすると、S3イベント・ハンドラが異常終了します。

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

テンプレート文字列には、実行時に動的に解決されるリテラルとキーワードの組合せを含めることができます。S3イベント・ハンドラは、テンプレート文字列を多用して、S3ディレクトリ名、データ・ファイル名およびS3バケット名を生成します。これにより、データ・ファイルおよびデータ・ファイルの名前を書き込む場所を柔軟に選択できます。

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

キーワード	説明
${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

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

接続の問題

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

Oracle GoldenGateは、プロキシ・サーバーを使用可能にする次のパラメータを使用して、プロキシ・サーバーとともに使用できます。

• gg.handler.name.proxyServer=

• gg.handler.name.proxyPort=80

資格証明および次の構成パラメータを使用して、プロキシ・サーバーへのアクセスを保護できます。

• gg.handler.name.proxyUsername=username
• gg.handler.name.proxyPassword=password

サンプル構成:

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.proxyProtocol=HTTP
gg.eventhandler.s3.bucketMappingTemplate=yourbucketname
gg.eventhandler.s3.pathMappingTemplate=thepath
gg.eventhandler.s3.finalizeAction=none
goldengate.userexit.writers=javawriter

11.3 S3イベント・ハンドラの構成

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

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

表11-1 S3イベント・ハンドラの構成プロパティ

プロパティ	必須/オプション	有効な値	デフォルト	説明
gg.eventhandler.name.type	必須	s3	なし	Replicatで使用するS3イベント・ハンドラを選択します。
gg.eventhandler.name.region	必須	S3インスタンスをホストしているAWSリージョン名。	なし	有効なAWSリージョン名の設定は必須です。
gg.eventhandler.name.cannedACL	オプション	次のいずれかの値が有効です。 private public-read public-read-write aws-exec-read authenticated-read bucket-owner-read bucket-owner-full-control log-delivery-write	なし	Amazon S3では、規定アクセス制御リストという一連の事前定義済許可がサポートされています。規定ACLごとに、一連の権限受領者とアクセス権限が事前定義されています。詳細は、ACLを使用したアクセスの管理に関する項を参照してください。
gg.eventhandler.name.proxyServer	オプション	プロキシ・サーバーのホスト名。	なし	プロキシ・サーバーを使用したAWSへの接続が必要な場合は、プロキシ・サーバーのホスト名を設定します。
gg.eventhandler.name.proxyPort	オプション	プロキシ・サーバーのポート番号。	なし	プロキシ・サーバーを使用したAWSへの接続が必要な場合は、プロキシ・サーバーのポート番号を設定します。
gg.eventhandler.name.proxyUsername	オプション	プロキシ・サーバーのユーザー名。	なし	プロキシ・サーバーを使用したAWSへの接続が必要で、かつ、プロキシ・サーバーによって資格証明が要求される場合は、プロキシ・サーバーのユーザー名を設定します。
gg.eventhandler.name.proxyPassword	オプション	プロキシ・サーバーのパスワード。	なし	プロキシ・サーバーを使用したAWSへの接続が必要で、かつ、プロキシ・サーバーによって資格証明が要求される場合は、プロキシ・サーバーのユーザー名のパスワードを設定します。
gg.eventhandler.name.bucketMappingTemplate	必須	ファイルを書き込むS3バケットのパスを動的に生成するために使用される、解決可能なキーワードと定数を含む文字列。	なし	実行時にS3バケット名を動的に生成するために使用される、解決可能なキーワードと定数を使用します。S3バケットが存在しない場合、ハンドラはS3バケットを作成しようとします。AWSでは、バケット名はすべて小文字にする必要があります。大文字を使用したバケット名によって、実行時例外が発生します。
gg.eventhandler.name.pathMappingTemplate	必須	ファイルを書き込むS3バケットのパスを動的に生成するために使用される、解決可能なキーワードと定数を含む文字列。	なし	定数とともにインタレースされるキーワードを使用して、一意のS3パス名を実行時に動的に生成します。通常パス名は、ogg/data/${groupName}/${fullyQualifiedTableName}の形式に従います。S3の規則では、先頭にバックスラッシュ(/)を使用しません。これは、""のルート・ディレクトリになるためです。
gg.eventhandler.name.fileNameMappingTemplate	オプション	実行時にS3ファイル名を動的に生成するために使用される、解決可能なキーワードと定数を含む文字列。	なし	実行時にS3データ・ファイル名を動的に生成するために使用される、解決可能なキーワードと定数を使用します。設定しない場合、アップストリームのファイル名が使用されます。
gg.eventhandler.name.finalizeAction	オプション	none | delete	なし	ファイナライズ・アクションでS3データ・ファイルをそのままにするには、noneを設定します。ファイナライズ・アクションでS3データ・ファイルを削除するには、deleteを設定します。
gg.eventhandler.name.eventHandler	オプション	子イベント・ハンドラを相互参照する一意の文字列識別子。	イベント・ハンドラは構成されない。	ファイル・ロール・イベントで呼び出されるイベント・ハンドラを設定します。イベント・ハンドラは、S3へのファイルのロード、ParquetまたはORC形式への変換、HDFSへのファイルのロードなどのファイル・ロール・イベントのアクションを実行できます。
gg.eventhandler.name.url	オプション (Dell ECS以外の場合は必須)	クラウド・ストレージに接続するための有効なURL。	なし	Amazon AWS S3の場合、不要です。Dell ECSの場合、必須です。クラウド・ストレージに接続するためのURLを設定します。
gg.eventhandler.name.proxyProtocol	オプション	HTTP | HTTPS	HTTP	セキュリティ・レベルの追加のためにプロキシ・サーバーへのプロキシ・プロトコル接続を設定します。クライアントは最初にプロキシ・サーバーとのSSLハンドシェイクを実行し、次にAmazon AWSとのSSLハンドシェイクを実行します。この機能はバージョン1.11.396のAmazon SDKに追加されたため、このプロパティを使用するには少なくともこのバージョンを使用する必要があります。
gg.eventhandler.name.SSEAlgorithm	オプション	AES256 | aws:kms	空	S3サーバー側暗号化を有効にする場合にのみ設定します。パラメータを使用して、S3のサーバー側暗号化のアルゴリズムを設定します。
gg.eventhandler.name.AWSKmsKeyId	オプション	有効なAWSキー管理システムのサーバー側の管理キー、またはそのキーを表す別名。	空	S3サーバー側暗号化を有効にし、S3アルゴリズムがaws:kmsである場合にのみ設定します。これは、AWS Identity and Access ManagementのWebページで設定した暗号化キーまたは暗号化別名のいずれかです。別名の先頭にalias/が付加されます。
gg.eventhandler.name.enableSTS	オプション	true | false	false	S3イベント・ハンドラがAWSセキュリティ・トークン・サービスからS3資格証明にアクセスできるようにするには、trueに設定します。このプロパティをtrueに設定する場合は、AWSセキュリティ・トークン・サービスを有効にする必要があります。
gg.eventhandler.name.STSAssumeRole	オプション	AWSユーザーおよびロール({user arn}:role/{role name}の形式)	なし	別のユーザー/ロールを想定する場合は、構成を設定します。STSが有効な場合にのみ有効です。
gg.eventhandler.name.STSAssumeRoleSessionName	オプション	任意の文字列。	AssumeRoleSession1	想定されるロールには、セッション・ロギング用のセッション名が必要です。ただし、これには任意の値を指定できます。gg.eventhandler.name.enableSTS=trueとgg.eventhandler.name.STSAssumeRoleの両方が構成されている場合にのみ有効です。
gg.eventhandler.name.STSRegion	オプション	任意の有効なAWSリージョン指定子。	リージョンは、gg.eventhandler.name.regionプロパティから取得されます。	STSコールのリージョンを解決するために使用します。gg.eventhandler.name.enableSTSプロパティがtrueに設定されている場合にのみ有効です。STSからの資格証明を解決するために、構成されているS3リージョンとは異なるAWSリージョンを設定できます。
gg.eventhandler.name.enableBucketAdmin	オプション	true | false	true	S3バケットが存在するかどうかの確認と、バケットが存在しない場合のバケットの自動作成を無効にする場合は、falseに設定します。この機能を使用するには、S3バケットに対するS3の管理権限が必要ですが、一部の顧客はこの権限を付与することを望まない場合もあります。
gg.eventhandler.name.accessKeyId	オプション	有効なAWSアクセス・キー。	なし	このパラメータを設定することで、明示的にAWSのアクセス・キーを設定します。このパラメータは、gg.eventhandler.name.enableSTSがtrueに設定されている場合は効果がありません。このプロパティが設定されていない場合、資格証明の解決はAWSのデフォルト資格証明プロバイダ・チェーンに戻されます。
gg.eventhandler.name.secretKey	オプション	有効なAWSシークレット・キー。	なし	このパラメータを設定することで、明示的にAWSのシークレット・キーを設定します。このパラメータは、gg.eventhandler.name.enableSTSがtrueに設定されている場合は効果がありません。このプロパティが設定されていない場合、資格証明の解決はAWSのデフォルト資格証明プロバイダ・チェーンに戻されます。