# Transferencia de archivos entre Amazon RDS para Oracle y un bucket de Amazon S3
Para transferir archivos entre una instancia de base de datos de RDS para Oracle y un bucket Amazon S3, puede utilizar el paquete `rdsadmin_s3_tasks` de Amazon RDS. Puede comprimir archivos con GZIP al cargarlos y descomprimirlos durante la descarga.
**Topics**
+ [Requisitos y limitaciones de la transferencia de archivos](#oracle-s3-integration.using.reqs)
+ [Carga de archivos desde la instancia de base de datos de RDS para Oracle en un bucket de Amazon S3](#oracle-s3-integration.using.upload)
+ [Descarga de archivos desde un bucket de Amazon S3 en una instancia de base de datos de Oracle](#oracle-s3-integration.using.download)
+ [Monitoreo del estado de una transferencia de archivos](#oracle-s3-integration.using.task-status)
## Requisitos y limitaciones de la transferencia de archivos
Antes de transferir archivos entre una instancia de base de datos y un bucket de Amazon S3, tenga en cuenta lo siguiente:
+ El paquete `rdsadmin_s3_tasks` transfiere los archivos que se encuentran en un único directorio. No puede incluir subdirectorios en una transferencia.
+ El tamaño máximo de objeto en un bucket de Amazon S3 es de 5 TB.
+ Las tareas creadas por `rdsadmin_s3_tasks` se ejecutan de forma asíncrona.
+ Puede cargar archivos desde el directorio de Data Pump, como `DATA_PUMP_DIR`, o desde cualquier directorio creado por el usuario. No puede cargar archivos desde un directorio que utilizan los procesos en segundo plano de Oracle, como los directorios `adump`, `bdump` o `trace`.
+ El límite de descargas es de 2000 archivos por llamada a procedimiento para `download_from_s3`. Si necesita descargar más de 2000 archivos de Amazon S3, divida la descarga en acciones independientes, con un máximo de 2000 archivos por llamada al procedimiento.
+ Si existe un archivo en la carpeta de descargas e intenta descargar un archivo con el mismo nombre, `download_from_s3` omite la descarga. Para quitar un archivo del directorio de descarga, utilice el procedimiento 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).
## Carga de archivos desde la instancia de base de datos de RDS para Oracle en un bucket de Amazon S3
Para cargar archivos desde una instancia de base de datos en un bucket de Amazon S3, use el procedimiento `rdsadmin.rdsadmin_s3_tasks.upload_to_s3`. Por ejemplo, puede cargar archivos de copia de seguridad de Oracle Recovery Manager (RMAN) o archivos de Oracle Data Pump. Para obtener información acerca del uso de objetos, consulte [Guía del usuario de Amazon Simple Storage Service](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingObjects.html). Para obtener más información acerca de cómo realizar copias de seguridad de RMAN, consulte [Realización de tareas RMAN comunes para instancias de base de datos de Oracle](Appendix.Oracle.CommonDBATasks.RMAN.md).
El procedimiento `rdsadmin.rdsadmin_s3_tasks.upload_to_s3` tiene los siguientes parámetros.
****
| Nombre del parámetro | Tipo de datos | Valor predeterminado | Obligatorio | Descripción |
| --- | --- | --- | --- | --- |
| `p_bucket_name` | VARCHAR2 | – | obligatorio | Nombre del bucket de Amazon S3 en el que cargar archivos. |
| `p_directory_name` | VARCHAR2 | – | obligatorio | Nombre del objeto de directorio de Oracle desde el que cargar archivos. El directorio puede ser cualquier objeto de directorio creado por el usuario o el directorio Data Pump, como `DATA_PUMP_DIR`. No puede cargar archivos desde un directorio que utilizan los procesos en segundo plano, como `adump`, `bdump` y `trace`. Solo puede cargar archivos desde el directorio especificado. No puede cargar archivos en subdirectorios en el directorio especificado. |
| `p_s3_prefix` | VARCHAR2 | – | obligatorio | Prefijo del nombre de archivo de Amazon S3 en el que se cargan los archivos. Un prefijo vacío carga todos los archivos en el nivel superior en el bucket de Amazon S3 especificado y no añade un prefijo a los nombres de archivo. Por ejemplo, si el prefijo es `folder_1/oradb`, los archivos se cargan en `folder_1`. En este caso, el prefijo `oradb` se añade a cada archivo. |
| `p_prefix` | VARCHAR2 | – | obligatorio | Prefijo del nombre de archivo con el que deben coincidir los nombres de archivo para cargarse. Un prefijo vacío carga todos los archivos en el directorio especificado. |
| `p_compression_level` | NUMBER | `0` | opcional | El nivel de compresión GZIP. Los valores válidos van de `0` a:`9` [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/AmazonRDS/latest/UserGuide/oracle-s3-integration.using.html) |
| `p_bucket_owner_full_control` | VARCHAR2 | – | opcional | Configuración de control de acceso para el bucket. Los únicos valores válidos son null o `FULL_CONTROL`. Esta configuración solo es obligatoria si carga archivos de una cuenta (cuenta A) en un bucket propiedad de otra cuenta (cuenta B) y la cuenta B necesita el control total de los archivos. |
El valor devuelto para el procedimiento `rdsadmin.rdsadmin_s3_tasks.upload_to_s3` es un ID de tarea.
En el siguiente ejemplo, se cargan todos los archivos del directorio `DATA_PUMP_DIR` en el bucket de Amazon S3 denominado *amzn-s3-demo-bucket*. Los archivos no están comprimidos.
```
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;
```
En el siguiente ejemplo se cargan todos los archivos con el prefijo `db` del directorio `DATA_PUMP_DIR` en el bucket de Amazon S3 denominado `amzn-s3-demo-bucket`. Amazon RDS aplica el nivel más alto de compresión GZIP a los archivos.
```
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;
```
En el siguiente ejemplo se cargan todos los archivos del directorio `DATA_PUMP_DIR` en el bucket de Amazon S3 denominado `amzn-s3-demo-bucket`. Los archivos se cargan en una carpeta `dbfiles`. En este ejemplo, el nivel de compresión GZIP es *1*, que es el nivel de compresión más rápido.
```
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;
```
En el siguiente ejemplo se cargan todos los archivos del directorio `DATA_PUMP_DIR` en el bucket de Amazon S3 denominado `amzn-s3-demo-bucket`. Los archivos se cargan en una carpeta `dbfiles` y `ora` se añade al principio de cada nombre de archivo. No se aplica compresión.
```
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;
```
En el ejemplo siguiente se supone que el comando se ejecuta en la cuenta A, pero la cuenta B requiere un control total del contenido del bucket. El comando `rdsadmin_s3_tasks.upload_to_s3` transfiere todos los archivos del directorio `DATA_PUMP_DIR` al bucket denominado `s3bucketOwnedByAccountB`. El control de acceso está configurado en `FULL_CONTROL` para que la cuenta B pueda acceder a los archivos del bucket. El nivel de compresión GZIP es *6*, que equilibra la velocidad y el tamaño del archivo.
```
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;
```
En cada ejemplo, la instrucción `SELECT` devuelve el identificador de la tarea en un tipo de datos `VARCHAR2`.
Para ver el resultado, visualice el archivo de salida de la tarea.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));
```
Reemplace *`task-id`* con el ID de tarea devuelto por el procedimiento.
**nota**
Las tareas se ejecutan de forma asíncrona.
## Descarga de archivos desde un bucket de Amazon S3 en una instancia de base de datos de Oracle
Para descargar archivos desde un bucket de Amazon S3 en una instancia de RDS para Oracle, use el procedimiento de Amazon RDS `rdsadmin.rdsadmin_s3_tasks.download_from_s3`.
El procedimiento `download_from_s3` tiene los siguientes parámetros.
****
| Nombre del parámetro | Tipo de datos | Valor predeterminado | Obligatorio | Descripción |
| --- | --- | --- | --- | --- |
| `p_bucket_name` | VARCHAR2 | – | Obligatorio | Nombre del bucket de Amazon S3 desde el que descargar archivos. |
| `p_directory_name` | VARCHAR2 | – | Obligatorio | Nombre del directorio de Oracle en el que descargar archivos. El directorio puede ser cualquier objeto de directorio creado por el usuario o el directorio Data Pump, como `DATA_PUMP_DIR`. |
| `p_error_on_zero_downloads` | VARCHAR2 | FALSO | Opcional | Indicador que determina si la tarea genera un error cuando ningún objeto del bucket de Amazon S3 coincide con el prefijo. Si este parámetro no está establecido o se establece en FALSE (predeterminado), la tarea imprime un mensaje en el que se indica que no se ha encontrado ningún objeto, pero no genera ninguna excepción ni se produce un error. Si este parámetro es TRUE, la tarea genera una excepción y se produce un error. Algunos ejemplos de especificaciones de prefijos que no superan las pruebas de coincidencia son los espacios en los prefijos, como en `' import/test9.log'`, y los desajustes de mayúsculas y minúsculas, como en `test9.log` y `test9.LOG`. |
| `p_s3_prefix` | VARCHAR2 | – | Obligatorio | Prefijo del nombre de archivo con el que deben coincidir los nombres de archivo para descargarse. Un prefijo vacío descarga todos los archivos de nivel superior en el bucket de Amazon S3 especificado pero no los archivos en las carpetas en el bucket. El procedimiento descarga objetos de Amazon S3 solo desde la primera carpeta de nivel que coincide con el prefijo. Las estructuras de directorios anidados que coinciden con el prefijo especificado no se descargan. Por ejemplo, supongamos que un bucket de Amazon S3 tiene la estructura de carpetas `folder_1/folder_2/folder_3`. Especifique el prefijo `'folder_1/folder_2/'`. En este caso, solo se descargan los archivos de `folder_2`, no los archivos de `folder_1` ni de `folder_3`. Si, de lo contrario, especifico el prefijo `'folder_1/folder_2'`, se descargan todos los archivos en `folder_1` que coincidan con el prefijo `'folder_2'` y no se descarga ningún archivo en `folder_2`. |
| `p_decompression_format` | VARCHAR2 | – | Opcional | El formato de compresión. Los valores válidos son `NONE` sin descompresión y `GZIP` para descompresión. |
El valor devuelto para el procedimiento `rdsadmin.rdsadmin_s3_tasks.download_from_s3` es un ID de tarea.
En el siguiente ejemplo se descargan todos los archivos del bucket de Amazon S3 denominado `amzn-s3-demo-bucket` en el directorio `DATA_PUMP_DIR`. Los archivos no están comprimidos, por lo que no se aplica descompresión.
```
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;
```
En el siguiente ejemplo se descargan todos los archivos con el prefijo `db` del bucket de Amazon S3 denominado `amzn-s3-demo-bucket` en el directorio `DATA_PUMP_DIR`. Los archivos están comprimidos con GZIP, por lo que se aplica descompresión. El parámetro `p_error_on_zero_downloads` activa la comprobación de errores de prefijos, de modo que si el prefijo no coincide con ningún archivo del bucket, la tarea generará una excepción y fallará.
```
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;
```
En el siguiente ejemplo se descargan todos los archivos de la carpeta `myfolder/` del bucket de Amazon S3 denominado `amzn-s3-demo-bucket` en el directorio `DATA_PUMP_DIR`. Use el parámetro `p_s3_prefix` para especificar la carpeta de Amazon S3. Los archivos cargados se comprimen con GZIP, pero no se descomprimen durante la descarga.
```
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;
```
El siguiente ejemplo descarga el archivo `mydumpfile.dmp` en el bucket de Simple Storage Service (Amazon S3) con el nombre `amzn-s3-demo-bucket` del directorio `DATA_PUMP_DIR`. No se aplica descompresión.
```
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;
```
En cada ejemplo, la instrucción `SELECT` devuelve el identificador de la tarea en un tipo de datos `VARCHAR2`.
Para ver el resultado, visualice el archivo de salida de la tarea.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));
```
Reemplace *`task-id`* con el ID de tarea devuelto por el procedimiento.
**nota**
Las tareas se ejecutan de forma asíncrona.
Puede utilizar el procedimiento `UTL_FILE.FREMOVE` de Oracle para eliminar archivos de un directorio. Para más información, consulte [FREMOVE Procedure](https://docs.oracle.com/database/121/ARPLS/u_file.htm#ARPLS70924) en la documentación de Oracle.
## Monitoreo del estado de una transferencia de archivos
Las tareas de transferencia de archivos publican eventos de Amazon RDS al comenzar y al completarse. El mensaje de evento contiene el identificador de la tarea para la transferencia del archivo. Para obtener información acerca de cómo ver los eventos, consulte [Consulta de eventos de Amazon RDS](USER_ListEvents.md).
Puede ver el estado de una tarea continua en un archivo bdump. Los archivos bdump están ubicados en el directorio `/rdsdbdata/log/trace`. El nombre del archivo bdump está en el siguiente formato.
```
dbtask-task-id.log
```
Reemplace `task-id` por el ID de la tarea que desea monitorizar.
**nota**
Las tareas se ejecutan de forma asíncrona.
Puede utilizar el procedimiento almacenado `rdsadmin.rds_file_util.read_text_file` para ver el contenido de los archivos bdump. Por ejemplo, la siguiente consulta devuelve el contenido del archivo bdump `dbtask-1234567890123-1234.log`.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-1234567890123-1234.log'));
```
A continuación, se muestra un ejemplo de archivo de registro de una transferencia fallida.
```
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.
```