ファイル転送の要件と制限 RDS for Oracle DB インスタンスから Amazon S3 バケットにファイルをアップロードする Amazon S3 バケットから Oracle DB インスタンスにファイルをダウンロードするファイル転送のステータスをモニタリングする

Amazon RDS for Oracle と Amazon S3 バケットの間でファイルを転送する

RDS for Oracle DB インスタンスと Amazon S3 バケット間でファイルを転送するには、Amazon RDS パッケージ rdsadmin_s3_tasks を使用できます。アップロード時に GZIP でファイルを圧縮し、ダウンロード時に解凍することができます。

トピック

ファイル転送の要件と制限
RDS for Oracle DB インスタンスから Amazon S3 バケットにファイルをアップロードする
Amazon S3 バケットから Oracle DB インスタンスにファイルをダウンロードする
ファイル転送のステータスをモニタリングする

ファイル転送の要件と制限

DB インスタンスと Amazon S3 バケットの間でファイルを転送する前に、次の点に注意してください。

rdsadmin_s3_tasks パッケージは、単一のディレクトリにあるファイルを転送します。転送にサブディレクトリを含めることはできません。
Amazon S3 バケット内の最大オブジェクトサイズは 5 TB です。
rdsadmin_s3_tasks によって作成されたタスクは非同期的に実行されます。
DATA_PUMP_DIR などの Data Pump ディレクトリ、またはユーザーが作成したディレクトリからファイルをアップロードできます。adump、bdump、または trace ディレクトリなど、Oracle バックグラウンドプロセスで使用されるディレクトリからファイルをアップロードすることはできません。
ダウンロードできるファイル数は、download_from_s3 の場合、プロシージャコールあたり 2000 ファイルに制限されています。Amazon S3 から 2000 を超えるファイルをダウンロードする必要がある場合は、ダウンロードを別々のアクションに分割し、1 回のプロシージャコールあたりのファイル数が 2000 を超えないようにしてください。
ダウンロードフォルダにファイルが存在し、同じ名前のファイルをダウンロードしようとすると、download_from_s3 ではダウンロードをスキップします。ダウンロードディレクトリからファイルを削除するには、PL/SQL プロシージャ UTL_FILE.FREMOVE を使用します。

RDS for Oracle DB インスタンスから Amazon S3 バケットにファイルをアップロードする

DB インスタンスから Amazon S3 バケットにファイルをアップロードするには、プロシージャ rdsadmin.rdsadmin_s3_tasks.upload_to_s3 を使用します。例えば、Oracle Recovery Manager (RMAN) のバックアップファイルまたは Oracle Data Pump ファイルをアップロードすることができます。オブジェクトの操作方法の詳細については、Amazon Simple Storage Service ユーザーガイドを参照してください。RMAN バックアップの詳細については、「Oracle DB インスタンスの一般的な RMAN タスクの実行」を参照してください。

rdsadmin.rdsadmin_s3_tasks.upload_to_s3 プロシージャには以下のパラメータがあります。

パラメータ名	データ型	デフォルト	必須	説明
`p_bucket_name`	VARCHAR2	–	必須	ファイルをアップロードする Amazon S3 バケットの名前。
`p_directory_name`	VARCHAR2	–	必須	ファイルのアップロード元の Oracle ディレクトリオブジェクトの名前。ディレクトリは、ユーザーが作成した任意のディレクトリオブジェクト、または Data Pump ディレクトリ (例: `DATA_PUMP_DIR`) です。`adump`、`bdump`、または `trace` など、バックグラウンドプロセスで使用されるディレクトリからファイルをアップロードすることはできません。注記ファイルは、指定したディレクトリからのみアップロードできます。指定したディレクトリのサブディレクトリにファイルをアップロードすることはできません。
`p_s3_prefix`	VARCHAR2	–	必須	ファイルをアップロードする Amazon S3 ファイル名のプレフィックス。プレフィックスが空の場合は、指定された Amazon S3 バケットの最上位レベルにすべてのファイルがアップロードされますが、そのファイル名にプレフィックスは付加されません。例えば、プレフィックスが `folder_1/oradb` の場合、ファイルは `folder_1` にアップロードされます。この場合、ファイルにはそれぞれ `oradb` プレフィックスが追加されます。
`p_prefix`	VARCHAR2	–	必須	アップロードするファイル名が一致する必要があるファイル名のプレフィックス。プレフィックスが空の場合は、指定されたディレクトリ内のファイルがすべてアップロードされます。
`p_compression_level`	NUMBER	`0`	オプション	GZIP 圧縮のレベル。有効な値の範囲は `0`～`9` です。 `0` – 圧縮なし `1` – 最速圧縮 `9` – 最高圧縮
`p_bucket_owner_full_control`	VARCHAR2	–	optional	バケットのアクセスコントロールリスト。有効な値は、null と `FULL_CONTROL` のみです。この設定は、あるアカウント (アカウント A) から別のアカウント (アカウント B) が所有するバケットにファイルをアップロードし、アカウント B がファイルを完全に制御する必要がある場合にのみ必要です。

rdsadmin.rdsadmin_s3_tasks.upload_to_s3 プロシージャの戻り値はタスク ID です。

次の例では、DATA_PUMP_DIR ディレクトリ内のすべてのファイルを amzn-s3-demo-bucket という名前の Amazon S3 バケットにアップロードします。ファイルは圧縮されません。


SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
      p_bucket_name    =>  'amzn-s3-demo-bucket',
      p_prefix         =>  '', 
      p_s3_prefix      =>  '', 
      p_directory_name =>  'DATA_PUMP_DIR') 
   AS TASK_ID FROM DUAL;

次の例では、db ディレクトリ内のプレフィックス DATA_PUMP_DIR のついたすべてのファイルを、amzn-s3-demo-bucket という名前の Amazon S3 バケットにアップロードします。Amazon RDS は、最高レベルの GZIP 圧縮をファイルに適用します。


SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
      p_bucket_name       =>  'amzn-s3-demo-bucket', 
      p_prefix            =>  'db', 
      p_s3_prefix         =>  '', 
      p_directory_name    =>  'DATA_PUMP_DIR',
      p_compression_level =>  9) 
   AS TASK_ID FROM DUAL;

次の例では、DATA_PUMP_DIR ディレクトリのすべてのファイルを、amzn-s3-demo-bucket という名前の Amazon S3 バケットにアップロードします。ファイルは、dbfiles フォルダにアップロードされます。この例では、GZIP 圧縮レベルは 1 です。これは最も速い圧縮レベルです。


SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
      p_bucket_name       =>  'amzn-s3-demo-bucket', 
      p_prefix            =>  '', 
      p_s3_prefix         =>  'dbfiles/', 
      p_directory_name    =>  'DATA_PUMP_DIR',
      p_compression_level =>  1) 
   AS TASK_ID FROM DUAL;

次の例では、DATA_PUMP_DIR ディレクトリのすべてのファイルを、amzn-s3-demo-bucket という名前の Amazon S3 バケットにアップロードします。ファイルは dbfiles フォルダにアップロードされ、各ファイル名の先頭には ora が付加されます。圧縮は適用されません。


SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
      p_bucket_name    =>  'amzn-s3-demo-bucket', 
      p_prefix         =>  '', 
      p_s3_prefix      =>  'dbfiles/ora', 
      p_directory_name =>  'DATA_PUMP_DIR') 
   AS TASK_ID FROM DUAL;

次の例では、コマンドはアカウント A で実行されるものの、アカウント B でバケットの内容を完全に制御する必要があることを前提としています。コマンド rdsadmin_s3_tasks.upload_to_s3 は、s3bucketOwnedByAccountB という名前のバケットに DATA_PUMP_DIR ディレクトリ内のすべてのファイルを転送します。アクセスコントロールは、アカウント B がバケット内のファイルにアクセスできるように、FULL_CONTROL に設定されています。GZIP 圧縮レベルは 6 で、速度とファイルサイズのバランスが取れています。


SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
      p_bucket_name               =>  's3bucketOwnedByAccountB', 
      p_prefix                    =>  '', 
      p_s3_prefix                 =>  '', 
      p_directory_name            =>  'DATA_PUMP_DIR',
      p_bucket_owner_full_control =>  'FULL_CONTROL',
      p_compression_level         =>  6) 
   AS TASK_ID FROM DUAL;

それぞれの例では、SELECT ステートメントでは、タスクの ID が VARCHAR2 データ型で返ります。

タスクの出力ファイルを表示すると、結果を確認できます。


SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));

task-id は、この手順で返されたタスク ID に置き換えます。

注記

タスクは非同期的に実行されます。

Amazon S3 バケットから Oracle DB インスタンスにファイルをダウンロードする

Amazon S3 バケットから RDS for Oracle インスタンスにファイルをダウンロードするには、Amazon RDS プロシージャ (rdsadmin.rdsadmin_s3_tasks.download_from_s3) を使用します。

download_from_s3 プロシージャには以下のパラメータがあります。

パラメータ名	データ型	デフォルト	必須	説明
`p_bucket_name`	VARCHAR2	–	必須	ファイルのダウンロード元の Amazon S3 バケットの名前。
`p_directory_name`	VARCHAR2	–	必須	ファイルをダウンロードする Oracle ディレクトリオブジェクトの名前。ディレクトリは、ユーザーが作成した任意のディレクトリオブジェクト、または Data Pump ディレクトリ (例: `DATA_PUMP_DIR`) です。
`p_error_on_zero_downloads`	VARCHAR2	FALSE	オプションです。	Amazon S3 バケット内のどのオブジェクトもプレフィックスと一致しない場合に、タスクによってエラーを発生させるかどうかを決定するフラグ。このパラメータが設定されていないか、FALSE (デフォルト) に設定されている場合、タスクはオブジェクトが見つからなかったというメッセージを出力しますが、例外が発生したり、エラーになったりすることはありません。このパラメータが TRUE の場合、タスクでは例外が発生し、エラーになります。一致テストでエラーになる可能性のあるプレフィックス仕様の例としては、`' import/test9.log'` のようにプレフィックスにスペースが入るもの、または `test9.log` や `test9.LOG` のように大文字と小文字が一致しないものがあります。
`p_s3_prefix`	VARCHAR2	–	必須	ダウンロードするファイル名が一致する必要があるファイル名のプレフィックス。プレフィックスを空にすると、指定された Amazon S3 バケット内の最上位ファイルがすべてダウンロードされますが、バケットのフォルダ内のファイルはダウンロードされません。この手順では、プレフィックスと一致する初期のレベルのフォルダからのみ、Amazon S3 オブジェクトをダウンロードします。指定されたプレフィックスに一致する多層のディレクトリはダウンロードされません。例えば、Amazon S3 バケットのフォルダ構造が `folder_1/folder_2/folder_3` とします。`'folder_1/folder_2/'` プレフィックスを指定します。この場合、`folder_2` のファイルのみダウンロードされ、`folder_1` または `folder_3` のファイルはダウンロードされません。その代わりに、`'folder_1/folder_2'` を指定する場合、`folder_1` プレフィックスに一致する、`'folder_2'` のファイルはすべてダウンロードされますが、`folder_2` のファイルはダウンロードされません。
`p_decompression_format`	VARCHAR2	–	オプションです。	解凍形式。有効な値は、解凍しない場合は `NONE`、解凍する場合は `GZIP` です。

rdsadmin.rdsadmin_s3_tasks.download_from_s3 プロシージャの戻り値はタスク ID です。

次の例では、amzn-s3-demo-bucket という名前の Amazon S3 バケットのファイルをすべて、DATA_PUMP_DIR ディレクトリにダウンロードします。ファイルは圧縮されていないため、解凍は適用されません。


SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
      p_bucket_name    =>  'amzn-s3-demo-bucket',
      p_directory_name =>  'DATA_PUMP_DIR') 
   AS TASK_ID FROM DUAL;

以下の例では、db という名前の Amazon S3 バケット内にある、プレフィックス amzn-s3-demo-bucket がついたファイルをすべて、DATA_PUMP_DIR ディレクトリにダウンロードします。ファイルは GZIP で圧縮されているため、解凍が適用されます。p_error_on_zero_downloads パラメータはプレフィックスエラーチェックを有効にするため、プレフィックスがバケット内のどのファイルとも一致しない場合、タスクでは例外が発生し、エラーになります。


SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
      p_bucket_name               =>  'amzn-s3-demo-bucket', 
      p_s3_prefix                 =>  'db', 
      p_directory_name            =>  'DATA_PUMP_DIR',
      p_decompression_format      =>  'GZIP',
      p_error_on_zero_downloads   =>  'TRUE') 
   AS TASK_ID FROM DUAL;

以下の例では、myfolder/ という名前の Amazon S3 バケット内にある amzn-s3-demo-bucket フォルダ内のファイルをすべて、DATA_PUMP_DIR ディレクトリにダウンロードします。Amazon S3 フォルダを指定するには、p_s3_prefix パラメータを使用します。アップロードされたファイルは GZIP で圧縮されますが、ダウンロード中は解凍されません。


SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
      p_bucket_name          =>  'amzn-s3-demo-bucket', 
      p_s3_prefix            =>  'myfolder/', 
      p_directory_name       =>  'DATA_PUMP_DIR',
      p_decompression_format =>  'NONE')
   AS TASK_ID FROM DUAL;

次の例では、DATA_PUMP_DIR ディレクトリに amzn-s3-demo-bucket という名前の Amazon S3 バケット内のファイル mydumpfile.dmp をダウンロードします。解凍は適用されません。


SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
      p_bucket_name    =>  'amzn-s3-demo-bucket', 
      p_s3_prefix      =>  'mydumpfile.dmp', 
      p_directory_name =>  'DATA_PUMP_DIR') 
   AS TASK_ID FROM DUAL;

それぞれの例では、SELECT ステートメントでは、タスクの ID が VARCHAR2 データ型で返ります。

タスクの出力ファイルを表示すると、結果を確認できます。


SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));

task-id は、この手順で返されたタスク ID に置き換えます。

注記

タスクは非同期的に実行されます。

ディレクトリからファイルを削除するには、Oracle プロシージャ UTL_FILE.FREMOVE を使用できます。詳細については、Oracle ドキュメントの「FREMOVE プロシージャ」を参照してください。

ファイル転送のステータスをモニタリングする

ファイル転送タスクでは、スタート時と完了時に Amazon RDS イベントが発行されます。イベントメッセージには、ファイル転送のタスク ID が含まれています。イベントの表示の詳細については、「Amazon RDS イベントの表示」を参照してください。

実行中のタスクのステータスは bdump ファイルで確認できます。bdump ファイルは /rdsdbdata/log/trace ディレクトリにあります。bdump ファイルの名前形式は、以下のとおりです。


dbtask-task-id.log

task-id を、モニタリングするタスクの ID に置き換えます。

注記

タスクは非同期的に実行されます。

bdump ファイルの中身を表示するには、rdsadmin.rds_file_util.read_text_file ストアドプロシージャを使用します。例えば、次のクエリでは、bdump ファイル (dbtask-1234567890123-1234.log) の中身が返ります。


SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-1234567890123-1234.log'));

次のサンプルは、転送が失敗したときのログファイルを示しています。


TASK_ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
1234567890123-1234


TEXT                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
2023-04-17 18:21:33.993 UTC [INFO ] File #1: Uploading the file /rdsdbdata/datapump/A123B4CDEF567890G1234567890H1234/sample.dmp to Amazon S3 with bucket name amzn-s3-demo-bucket and key sample.dmp.
2023-04-17 18:21:34.188 UTC [ERROR] RDS doesn't have permission to write to Amazon S3 bucket name amzn-s3-demo-bucket and key sample.dmp.
2023-04-17 18:21:34.189 UTC [INFO ] The task failed.

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

オプションの追加

オプションの削除