Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Mentransfer file antara Amazon RDS for Oracle dan bucket Amazon S3
Untuk mentransfer file antara instans DB RDS for Oracle dan bucket Amazon S3, Anda dapat menggunakan paket `rdsadmin_s3_tasks` Amazon RDS. Anda dapat mengompres file dengan GZIP saat mengunggahnya, dan membuka kompresinya saat mengunduh.
**Topics**
+ [Persyaratan dan batasan transfer file](#oracle-s3-integration.using.reqs)
+ [Mengunggah file dari instans DB RDS for Oracle ke bucket Amazon S3](#oracle-s3-integration.using.upload)
+ [Mengunduh file dari bucket Amazon S3 ke instans DB Oracle](#oracle-s3-integration.using.download)
+ [Memantau status transfer file](#oracle-s3-integration.using.task-status)
## Persyaratan dan batasan transfer file
Sebelum mentransfer file antara instans DB Anda dan bucket Amazon S3, perhatikan hal-hal berikut:
+ Paket `rdsadmin_s3_tasks` mentransfer file yang berada di dalam satu direktori. Anda tidak dapat menyertakan subdirektori dalam transfer.
+ Ukuran objek maksimum dalam bucket Amazon S3 adalah 5 TB.
+ Tugas yang dibuat oleh `rdsadmin_s3_tasks` dijalankan secara asinkron.
+ Anda dapat mengunggah file dari direktori Data Pump, seperti `DATA_PUMP_DIR`, atau direktori lain yang dibuat oleh pengguna. Anda tidak dapat mengunggah file dari direktori yang digunakan oleh proses latar belakang Oracle, seperti direktori `adump`, `bdump`, atau `trace`.
+ Batas pengunduhan adalah 2.000 file per panggilan prosedur untuk `download_from_s3`. Jika Anda perlu mengunduh lebih dari 2.000 file dari Amazon S3, bagi unduhan menjadi beberapa tindakan terpisah, dengan tidak lebih dari 2.000 file per panggilan prosedur.
+ Jika terdapat file dengan nama yang sama di folder unduhan Anda, `download_from_s3` tidak akan memproses pengunduhan. Untuk menghapus file dari direktori download, gunakan PL/SQL prosedur [UTL\$1FILE.FREMOVE](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/UTL_FILE.html#GUID-09B09C2A-2C21-4F70-BF04-D0EEA7B59CAF).
## Mengunggah file dari instans DB RDS for Oracle ke bucket Amazon S3
Untuk mengunggah file dari instans DB Anda ke bucket Amazon S3, gunakan prosedur `rdsadmin.rdsadmin_s3_tasks.upload_to_s3`. Misalnya, Anda dapat mengunggah file cadangan Oracle Recovery Manager (RMAN) atau file Oracle Data Pump. Untuk informasi selengkapnya tentang penggunaan objek, lihat [Panduan Pengguna Amazon Simple Storage Service](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingObjects.html). Untuk informasi selengkapnya tentang proses pencadangan RMAN, lihat [Melakukan tugas RMAN umum untuk instans DB Oracle](Appendix.Oracle.CommonDBATasks.RMAN.md).
Prosedur `rdsadmin.rdsadmin_s3_tasks.upload_to_s3` memiliki parameter berikut.
****
| Nama parameter | Jenis data | Default | Wajib | Deskripsi |
| --- | --- | --- | --- | --- |
| `p_bucket_name` | VARCHAR2 | – | wajib | Nama bucket Amazon S3 tempat file diunggah. |
| `p_directory_name` | VARCHAR2 | – | wajib | Nama objek direktori Oracle asal file yang akan diunggah. Direktori dapat berupa objek direktori yang dibuat pengguna atau direktori Data Pump, seperti `DATA_PUMP_DIR`. Anda tidak dapat mengunggah file dari direktori yang digunakan oleh proses latar belakang, seperti `adump`, `bdump`, dan `trace`. Anda hanya dapat mengunggah file dari direktori yang ditentukan. Anda tidak dapat mengunggah file di subdirektori dalam direktori yang ditentukan. |
| `p_s3_prefix` | VARCHAR2 | – | wajib | Awalan nama file Amazon S3 tempat file diunggah. Awalan kosong mengunggah semua file ke tingkat teratas di bucket Amazon S3 yang ditentukan dan tidak menambahkan awalan pada nama file. Misalnya, jika prefiksnya adalah `folder_1/oradb`, file akan diunggah ke `folder_1`. Dalam hal ini, prefiks `oradb` ditambahkan ke setiap file. |
| `p_prefix` | VARCHAR2 | – | wajib | Prefiks nama file yang harus sama dengan nama file yang akan diunggah. Prefiks kosong akan mengunggah semua file dalam direktori yang ditentukan. |
| `p_compression_level` | ANGKA | `0` | opsional | Tingkat kompresi GZIP. Nilai yang valid berkisar dari `0` sampai `9`: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/AmazonRDS/latest/UserGuide/oracle-s3-integration.using.html) |
| `p_bucket_owner_full_control` | VARCHAR2 | – | opsional | Pengaturan kontrol akses untuk bucket. Satu-satunya nilai yang valid adalah null atau `FULL_CONTROL`. Pengaturan ini diperlukan hanya jika Anda mengunggah file dari satu akun (akun A) ke dalam sebuah bucket milik akun yang berbeda (akun B), dan akun B memerlukan kontrol penuh atas file tersebut. |
Nilai yang dikembalikan untuk prosedur `rdsadmin.rdsadmin_s3_tasks.upload_to_s3` adalah ID tugas.
Contoh berikut mengunggah semua file di `DATA_PUMP_DIR` direktori ke bucket Amazon S3 bernama *amzn-s3-demo-bucket*. File tidak dikompresi.
```
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;
```
Contoh berikut mengunggah semua file dengan prefiks `db` dalam direktori `DATA_PUMP_DIR` ke bucket Amazon S3 bernama `amzn-s3-demo-bucket`. Amazon RDS menerapkan tingkat kompresi GZIP tertinggi ke file.
```
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;
```
Contoh berikut mengunggah semua file di `DATA_PUMP_DIR` direktori ke bucket Amazon S3 bernama `amzn-s3-demo-bucket`. File tersebut diunggah ke folder `dbfiles`. Dalam contoh ini, tingkat kompresi GZIP adalah*1*, yang merupakan tingkat kompresi tercepat.
```
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;
```
Contoh berikut mengunggah semua file di direktori `DATA_PUMP_DIR` ke bucket Amazon S3 bernama `amzn-s3-demo-bucket`. File tersebut diunggah ke folder `dbfiles` dan `ora` ditambahkan ke awal setiap nama file. Tidak ada kompresi yang diterapkan.
```
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;
```
Contoh berikut ini mengasumsikan bahwa perintah dijalankan di akun A, tetapi akun B memerlukan kontrol penuh atas konten bucket. Perintah `rdsadmin_s3_tasks.upload_to_s3` mentransfer semua file dalam direktori `DATA_PUMP_DIR` ke bucket bernama `s3bucketOwnedByAccountB`. Kontrol akses diatur ke `FULL_CONTROL` agar akun B dapat mengakses file di bucket. Tingkat kompresi GZIP adalah*6*, yang menyeimbangkan kecepatan dan ukuran file.
```
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;
```
Di setiap contoh, pernyataan `SELECT` mengembalikan ID tugas dalam jenis data `VARCHAR2`.
Anda dapat melihat hasilnya dengan menampilkan file output tugas.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));
```
Ganti *`task-id`* dengan ID tugas yang dikembalikan oleh prosedur.
**catatan**
Tugas dijalankan secara asinkron.
## Mengunduh file dari bucket Amazon S3 ke instans DB Oracle
Untuk mengunduh file dari bucket Amazon S3 ke instans RDS for Oracle, gunakan prosedur `rdsadmin.rdsadmin_s3_tasks.download_from_s3` Amazon RDS.
Prosedur `download_from_s3` memiliki parameter berikut.
****
| Nama parameter | Jenis data | Default | Wajib | Deskripsi |
| --- | --- | --- | --- | --- |
| `p_bucket_name` | VARCHAR2 | – | Diperlukan | Nama bucket Amazon S3 asal unduhan file. |
| `p_directory_name` | VARCHAR2 | – | Diperlukan | Nama objek direktori Oracle untuk menyimpan unduhan file. Direktori dapat berupa objek direktori yang dibuat pengguna atau direktori Data Pump, seperti `DATA_PUMP_DIR`. |
| `p_error_on_zero_downloads` | VARCHAR2 | SALAH | Opsional | Tanda yang menentukan apakah tugas akan memunculkan kesalahan jika tidak ada objek di bucket Amazon S3 yang cocok dengan prefiks. Jika parameter ini tidak diatur atau diatur ke SALAH (default), tugas akan mencetak pesan bahwa objek tidak ditemukan, tetapi tidak memunculkan pengecualian atau gagal. Jika parameter ini BENAR, tugas akan memunculkan pengecualian dan gagal. Contoh spesifikasi prefiks yang dapat menggagalkan uji kecocokan adalah spasi pada prefiks, seperti pada `' import/test9.log'`, dan ketidakcocokan huruf besar/kecil, seperti pada `test9.log` dan `test9.LOG`. |
| `p_s3_prefix` | VARCHAR2 | – | Diperlukan | Prefiks nama file yang harus sama dengan nama file yang akan diunduh. Prefiks kosong akan mengunduh semua file tingkat atas dalam bucket Amazon S3 yang ditentukan, tetapi tidak akan mengunduh file di folder di dalam bucket. Prosedur ini mengunduh objek Amazon S3 hanya dari folder tingkat pertama yang cocok dengan prefiks. Struktur direktori bersarang yang cocok dengan prefiks yang ditentukan tidak akan diunduh. Sebagai contoh, misal bucket Amazon S3 memiliki struktur folder `folder_1/folder_2/folder_3`. Prefiks yang Anda gunakan adalah `'folder_1/folder_2/'`. Dalam hal ini, hanya file di dalam `folder_2` yang akan diunduh, bukan file di `folder_1` atau `folder_3`. Sebaliknya, jika Anda menggunakan prefiks `'folder_1/folder_2'`, semua file di `folder_1` yang cocok dengan prefiks `'folder_2'` akan diunduh, dan file di `folder_2` tidak akan diunduh satu pun. |
| `p_decompression_format` | VARCHAR2 | – | Opsional | Format dekompresi. Nilai yang valid untuk tanpa dekompresi adalah `NONE`, dan `GZIP` untuk dekompresi. |
Nilai yang dikembalikan untuk prosedur `rdsadmin.rdsadmin_s3_tasks.download_from_s3` adalah ID tugas.
Contoh berikut mengunduh semua file di bucket Amazon S3 bernama `amzn-s3-demo-bucket` ke direktori `DATA_PUMP_DIR`. File tidak dikompresi, jadi tidak ada dekompresi yang diterapkan.
```
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;
```
Contoh berikut mengunduh semua file dengan prefiks `db` di bucket Amazon S3 bernama `amzn-s3-demo-bucket` ke direktori `DATA_PUMP_DIR`. File dikompresi dengan GZIP, sehingga dekompresi diterapkan. Parameter `p_error_on_zero_downloads` mengaktifkan pemeriksaan kesalahan prefiks, jadi jika prefiks tidak cocok dengan file di dalam bucket, tugas akan memunculkan pengecualian dan gagal.
```
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;
```
Contoh berikut mengunduh semua file dalam folder `myfolder/` di bucket Amazon S3 bernama `amzn-s3-demo-bucket` ke direktori `DATA_PUMP_DIR`. Gunakan parameter `p_s3_prefix` untuk menentukan folder Amazon S3. File yang diunggah akan dikompresi dengan GZIP, tetapi tidak didekompresi selama pengunduhan.
```
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;
```
Contoh berikut mengunduh file `mydumpfile.dmp` di bucket Amazon S3 bernama `amzn-s3-demo-bucket` ke direktori `DATA_PUMP_DIR`. Tidak ada dekompresi yang diterapkan.
```
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;
```
Di setiap contoh, pernyataan `SELECT` mengembalikan ID tugas dalam jenis data `VARCHAR2`.
Anda dapat melihat hasilnya dengan menampilkan file output tugas.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));
```
Ganti *`task-id`* dengan ID tugas yang dikembalikan oleh prosedur.
**catatan**
Tugas dijalankan secara asinkron.
Anda dapat menggunakan prosedur `UTL_FILE.FREMOVE` Oracle untuk menghapus file dari direktori. Untuk informasi selengkapnya, lihat [FREMOVE procedure](https://docs.oracle.com/database/121/ARPLS/u_file.htm#ARPLS70924) dalam dokumentasi Oracle.
## Memantau status transfer file
Tugas transfer file menerbitkan peristiwa Amazon RDS saat dimulai dan selesai. Pesan peristiwa berisi ID tugas untuk transfer file. Untuk informasi tentang cara melihat peristiwa, lihat [Melihat RDS acara Amazon](USER_ListEvents.md).
Anda dapat melihat status tugas yang sedang berlangsung di file bdump. File bdump terletak di direktori `/rdsdbdata/log/trace`. Setiap nama file bdump memiliki format berikut.
```
dbtask-task-id.log
```
Ganti `task-id` dengan ID tugas yang ingin Anda pantau.
**catatan**
Tugas dijalankan secara asinkron.
Anda dapat menggunakan prosedur tersimpan `rdsadmin.rds_file_util.read_text_file` untuk melihat konten file bdump. Misalnya, kueri berikut mengembalikan konten file bdump `dbtask-1234567890123-1234.log`.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-1234567890123-1234.log'));
```
Contoh berikut menunjukkan file log untuk transfer yang gagal.
```
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.
```