# Amazon RDS for Oracle と Amazon S3 バケットの間でファイルを転送する
RDS for Oracle DB インスタンスと Amazon S3 バケット間でファイルを転送するには、Amazon RDS パッケージ `rdsadmin_s3_tasks` を使用できます。アップロード時に GZIP でファイルを圧縮し、ダウンロード時に解凍することができます。
**Topics**
+ [ファイル転送の要件と制限](#oracle-s3-integration.using.reqs)
+ [RDS for Oracle DB インスタンスから Amazon S3 バケットにファイルをアップロードする](#oracle-s3-integration.using.upload)
+ [Amazon S3 バケットから Oracle DB インスタンスにファイルをダウンロードする](#oracle-s3-integration.using.download)
+ [ファイル転送のステータスをモニタリングする](#oracle-s3-integration.using.task-status)
## ファイル転送の要件と制限
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\$1FILE.FREMOVE](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/UTL_FILE.html#GUID-09B09C2A-2C21-4F70-BF04-D0EEA7B59CAF) を使用します。
## 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 ユーザーガイド](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingObjects.html)を参照してください。RMAN バックアップの詳細については、「[Oracle DB インスタンスの一般的な RMAN タスクの実行](Appendix.Oracle.CommonDBATasks.RMAN.md)」を参照してください。
`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` です。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/AmazonRDS/latest/UserGuide/oracle-s3-integration.using.html) |
| `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 プロシージャ](https://docs.oracle.com/database/121/ARPLS/u_file.htm#ARPLS70924)」を参照してください。
## ファイル転送のステータスをモニタリングする
ファイル転送タスクでは、スタート時と完了時に Amazon RDS イベントが発行されます。イベントメッセージには、ファイル転送のタスク ID が含まれています。イベントの表示の詳細については、「[Amazon RDS イベントの表示](USER_ListEvents.md)」を参照してください。
実行中のタスクのステータスは 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.
```