本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 在 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\_FILE.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/en/database/oracle/oracle-database/19/arpls/UTL_FILE.html)。 ## 監控檔案傳輸狀態 檔案傳輸作業會在開始及完成時發佈 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. ```