本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在 Amazon RDS for Oracle 和 Amazon S3 儲存貯體之間傳輸檔案
如要在 RDS for Oracle 資料庫執行個體和 Amazon S3 儲存貯體之間傳輸檔案，您可以使用 Amazon RDS 套件 `rdsadmin_s3_tasks`。您可在上傳檔案時裡用 GZIP 壓縮文件，並在下載時對其進行解壓縮。
**Topics**
+ [檔案傳輸的需求和限制](#oracle-s3-integration.using.reqs)
+ [將檔案從 RDS for Oracle 資料庫執行個體上傳至 Amazon S3 儲存貯體](#oracle-s3-integration.using.upload)
+ [將檔案從 Amazon S3 儲存貯體下載至 Oracle 資料庫執行個體](#oracle-s3-integration.using.download)
+ [監控檔案傳輸狀態](#oracle-s3-integration.using.task-status)
## 檔案傳輸的需求和限制
在資料庫執行個體與 Amazon S3 儲存貯體之間傳輸檔案之前，請注意下列事項：
+ `rdsadmin_s3_tasks` 套件會傳輸位於單一目錄中的檔案。您無法在傳輸中包含子目錄。
+ Amazon S3 儲存貯體中的物件大小上限為 5 TB。
+ 由 `rdsadmin_s3_tasks` 建立的任務會以非同步方式執行。
+ 您可以從 Data Pump 目錄 (例如 `DATA_PUMP_DIR`) 或任何使用者建立的目錄上傳檔案。您無法從 Oracle 背景程序使用的目錄 (例如 `adump`、`bdump` 或 `trace` 目錄) 上傳檔案。
+ 下載限制為每次 `download_from_s3` 程序呼叫 2000 個檔案。如果您需要從 Amazon S3 下載 2000 個以上的檔案，請將您的下載分割為不同的動作，每次程序呼叫不超過 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 資料庫執行個體上傳至 Amazon S3 儲存貯體
如要從資料庫執行個體上傳檔案至 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 資料庫執行個體的一般 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/zh_tw/AmazonRDS/latest/UserGuide/oracle-s3-integration.using.html) |
| `p_bucket_owner_full_control` | VARCHAR2 | – | 選擇性 | 儲存貯體的存取控制設定。唯一有效值為 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` 會將 `DATA_PUMP_DIR` 目錄中的所有檔案傳輸至名為 `s3bucketOwnedByAccountB` 的儲存貯體。存取控制設定為 `FULL_CONTROL`，則帳戶 B 可存取儲存貯體中的檔案。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` 陳述式以 `VARCHAR2` 資料類型傳回任務 ID。
您可以透過顯示任務的輸出檔案來檢視結果。
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));
```
以程序傳回的任務 ID 取代 *`task-id`*。
**注意**
任務是以非同步方式執行。
## 將檔案從 Amazon S3 儲存貯體下載至 Oracle 資料庫執行個體
若要從 Amazon S3 儲存貯體下載檔案至 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` 目錄。使用 `p_s3_prefix` 參數，指定 Amazon S3 資料夾。上傳的檔案使用 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;
```
以下範例將名為 `amzn-s3-demo-bucket` 的 Amazon S3 儲存貯體中的檔案 `mydumpfile.dmp` 下載至 `DATA_PUMP_DIR` 目錄。未套用任何解壓縮。
```
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` 陳述式以 `VARCHAR2` 資料類型傳回任務 ID。
您可以透過顯示任務的輸出檔案來檢視結果。
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));
```
以程序傳回的任務 ID 取代 *`task-id`*。
**注意**
任務是以非同步方式執行。
您可使用 `UTL_FILE.FREMOVE` Oracle 程序由目錄移除檔案。如需詳細資訊，請參閱 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。
**注意**
任務是以非同步方式執行。
您可以使用 `rdsadmin.rds_file_util.read_text_file` 預存程序檢視 bdump 檔案內容。例如以下查詢會傳回 `dbtask-1234567890123-1234.log` bdump 檔案的內容。
```
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.
```