8.2.4 Amazon S3

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

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

8.2.4.1 概要

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

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

8.2.4.2 機能の詳細

ファイルをS3オブジェクト・ストレージに転送するために、S3イベント・ハンドラにはAmazon Web Services (AWS) Java SDKが必要です。Oracle GoldenGate for Big Dataには、AWS Java SDKが含まれていません。AWS Java SDKバージョン1.xはサポートされなくなり、2.28.11以上を使用することをお薦めします。AWS Java SDKを次のサイトからダウンロードしてインストールする必要があります。

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

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

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

• AWS資格証明の解決
  
• AWS S3バケットについて
  
• トラブルシューティング
  

8.2.4.2.1 AWS資格証明の解決

• Amazon Web Services Simple Storage Serviceクライアント認証
  S3イベント・ハンドラはAmazon Web Services (AWS) Simple Storage Service (S3)クラウド・サービスへのクライアント接続です。S3とのインタフェースを成功させるため、AWSクラウドはAWSクライアントを正常に認証できる必要があります。

8.2.4.2.1.1 Amazon Web Services Simple Storage Serviceクライアント認証

S3イベント・ハンドラはAmazon Web Services (AWS) Simple Storage Service (S3)クラウド・サービスへのクライアント接続です。S3とのインタフェースを成功させるため、AWSクラウドはAWSクライアントを正常に認証できる必要があります。

S3イベント・ハンドラに追加された認証オプションが増えたことで、AWSクライアント認証は複雑化しています。このトピックでは、AWSクライアント認証の様々なユースケースについて説明します。

• クライアントIDおよびシークレットの明示的な構成
  一般に、クライアントIDおよびシークレットはS3イベント・ハンドラがAmazon S3とやりとりするために必要な資格証明です。クライアントIDおよびシークレットは、Amazon AWSのWebサイトを使用して生成されます。
• AWSのデフォルトの資格証明プロバイダ・チェーンの使用
  gg.eventhandler.name.accessKeyIdおよびgg.eventhandler.name.secretKeyが設定されていない場合、資格証明の解決はAWSのデフォルトの資格証明プロバイダ・チェーンに戻ります。AWSのデフォルトの資格証明プロバイダ・チェーンは、AWS資格証明を解決するための様々な方法を提供します。
• AWSフェデレーテッド・ログイン
  ユースケースはオンプレミス・システム・ログインをAWSと統合する場合です。つまり、オンプレミス・マシンにログインすると、AWSにもログインするということです。

8.2.4.2.1.1.1 クライアントIDとシークレットの明示的な構成

一般に、クライアントIDおよびシークレットはS3イベント・ハンドラがAmazon S3とやりとりするために必要な資格証明です。クライアントIDおよびシークレットは、Amazon AWSのWebサイトを使用して生成されます。

これらの資格証明は、次のようにJavaアダプタ・プロパティ・ファイルで明示的に構成できます。

gg.eventhandler.name.accessKeyId=
gg.eventhandler.name.secretKey=

また、Oracle Walletの機能を使用してこれらの資格証明を暗号化できます。

8.2.4.2.1.1.2 AWSのデフォルトの資格証明プロバイダ・チェーンの使用

gg.eventhandler.name.accessKeyIdおよびgg.eventhandler.name.secretKeyが設定されていない場合、資格証明の解決はAWSのデフォルトの資格証明プロバイダ・チェーンに戻ります。AWSのデフォルトの資格証明プロバイダ・チェーンは、AWS資格証明を解決するための様々な方法を提供します。

デフォルトの資格証明プロバイダ・チェーンおよびAWS資格証明解決の操作の順序の詳細は、AWS資格証明の使用を参照してください。

Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)がAWS Elastic Compute Cloud (EC2)インスタンスで実行される場合の一般的なユースケースは、EC2メタデータ・サービスからの資格証明の解決です。AWSのデフォルトの資格証明プロバイダ・チェーンはオプションの1つとして、EC2メタデータ・サービスからの資格証明の解決を提供します。

8.2.4.2.1.1.3 AWSフェデレーテッド・ログイン

ユースケースはオンプレミス・システム・ログインをAWSと統合する場合です。つまり、オンプレミス・マシンにログインすると、AWSにもログインするということです。

このユースケースでは、次のようになります。

• クライアントIDおよびシークレットを生成しない場合があります。(一部のユーザーはAWSポータルでこの機能を無効にしています)。
• S3に対してプログラムによる呼出しを実行するため、クライアントAWSアプリケーションはAWS Security Token Service (STS)と対話して認証トークンを取得する必要があります。

この機能を有効にするには、gg.eventhandler.name.enableSTS=trueを設定します。

8.2.4.2.2 AWS S3バケットについて

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

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

接続の問題

オンプレミスで実行していて、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

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

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

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

表8-6 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のデフォルトの資格証明プロバイダ・チェーンに戻ります。
gg.eventhandler.s3.enableAccelerateMode	オプション	true | false	false	Amazon S3 Transfer Accelerationを有効化/無効化すると、クライアントとS3バケットの間で長距離にわたってファイルが迅速かつ安全に転送されます。