# 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 버킷의 최대 객체 크기는 5TB입니다.
+ `rdsadmin_s3_tasks`에서 생성한 작업은 비동기적으로 실행됩니다.
+ Data Pump 디렉터리(예: `DATA_PUMP_DIR` 또는 사용자 생성 디렉터리)에서 파일을 업로드할 수 있습니다. Oracle 백그라운드 프로세스에서 사용하는 디렉터리(예: `adump`, `bdump`, 또는 `trace` 디렉터리)에서는 파일을 업로드할 수 없습니다.
+ 다운로드 제한은 `download_from_s3`의 프로시저 직접 호출당 파일 2,000개입니다. Amazon S3에서 2,000개 이상의 파일을 다운로드해야 하는 경우 프로시저 호출당 2,000개 이하의 파일로 다운로드를 개별 작업으로 분할하세요.
+ 다운로드 폴더에 파일이 있고 같은 이름의 파일을 다운로드하려고 하면 `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`\$1`9`입니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/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'));
```
*`task-id`*를 절차에서 반환된 작업 ID로 대체합니다.
**참고**
작업은 비동기식으로 실행됩니다.
## Amazon S3 버킷의 파일을 Oracle DB 인스턴스로 다운로드
RDS for Oracle 인스턴스로 Amazon S3 버킷의 파일을 다운로드하려면 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'));
```
*`task-id`*를 절차에서 반환된 작업 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.
```