# Transferir arquivos entre o Amazon RDS para Oracle e um bucket do Amazon S3
É possível usar um pacote `rdsadmin_s3_tasks` do Amazon RDS para transferir arquivos entre uma instância de banco de dados do RDS para Oracle e um bucket do Amazon S3. É possível compactar arquivos com o GZIP ao carregá-los e descompactá-los ao baixar.
**Topics**
+ [Requisitos e limitações das transferências de arquivos](#oracle-s3-integration.using.reqs)
+ [Carregar arquivos de uma instância de banco de dados do RDS para Oracle para um bucket do Amazon S3](#oracle-s3-integration.using.upload)
+ [Baixar arquivos de um bucket do Amazon S3 para uma instância de banco de dados Oracle](#oracle-s3-integration.using.download)
+ [Monitorar o status de uma transferência de arquivo](#oracle-s3-integration.using.task-status)
## Requisitos e limitações das transferências de arquivos
Antes de transferir arquivos entre a instância de banco de dados e um bucket do Amazon S3, observe o seguinte:
+ O pacote `rdsadmin_s3_tasks` transfere arquivos localizados em um único diretório. Não é possível incluir subdiretórios em uma transferência.
+ O tamanho máximo do objeto em um bucket do Amazon S3 é 5 TB.
+ Tarefas criadas por `rdsadmin_s3_tasks` são executadas de forma assíncrona.
+ É possível fazer upload de arquivos do diretório Data Pump, como `DATA_PUMP_DIR`, ou de qualquer diretório criado pelo usuário. Não é possível fazer upload de arquivos de um diretório usado pelos processos em segundo plano da Oracle, como os diretórios `adump`, `bdump` ou `trace`.
+ O limite de download é de 2 mil arquivos por chamada de procedimento para `download_from_s3`. Se você precisar baixar mais de 2.000 arquivos do Amazon S3, divida o download em ações separadas, com no máximo 2.000 arquivos por chamado do procedimento.
+ Se já existir um arquivo na pasta de download e você tentar baixar um arquivo com o mesmo nome, `download_from_s3` vai ignorar o download. Para remover um arquivo do diretório de downloads, use o procedimento 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).
## Carregar arquivos de uma instância de banco de dados do RDS para Oracle para um bucket do Amazon S3
Para carregar arquivos da instância de banco de dados para um bucket do Amazon S3, use o procedimento `rdsadmin.rdsadmin_s3_tasks.upload_to_s3`. Por exemplo, você pode carregar arquivos de backup do Oracle Recovery Manager (RMAN) ou arquivos do Oracle Data Pump. Para ter mais informações sobre como trabalhar com objetos, consulte o [Guia do usuário do Amazon Simple Storage Service](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingObjects.html). Para ter mais informações sobre como executar backups do RMAN, consulte [Realização de tarefas comuns do RMAN para instâncias de banco de dados Oracle](Appendix.Oracle.CommonDBATasks.RMAN.md).
O procedimento `rdsadmin.rdsadmin_s3_tasks.upload_to_s3` tem os seguintes parâmetros.
****
| Nome do parâmetro | Tipo de dados | Padrão | Obrigatório | Descrição |
| --- | --- | --- | --- | --- |
| `p_bucket_name` | VARCHAR2 | – | obrigatório | O nome do bucket do Amazon S3 no qual fazer o upload de arquivos. |
| `p_directory_name` | VARCHAR2 | – | obrigatório | O nome do objeto de diretório Oracle do qual carregar arquivos. O diretório pode ser qualquer objeto de diretório criado pelo usuário ou o diretório Data Pump, como `DATA_PUMP_DIR`. Não é possível fazer upload de arquivos de um diretório usado pelos processos em segundo plano, como `adump`, `bdump` e `trace`. Você só pode fazer o upload de arquivos do diretório especificado. Não é possível fazer upload de arquivos em subdiretórios no diretório especificado. |
| `p_s3_prefix` | VARCHAR2 | – | obrigatório | Um prefixo de nome de arquivo do Amazon S3 no qual os arquivos são carregados. Um prefixo vazio faz upload de todos os arquivos para o nível superior no bucket do Amazon S3 especificado e não adiciona um prefixo aos nomes de arquivos. Por exemplo, se o prefixo for `folder_1/oradb`, os arquivos serão enviados em `folder_1`. Nesse caso, o prefixo `oradb` é adicionado a cada arquivo. |
| `p_prefix` | VARCHAR2 | – | obrigatório | Um prefixo de nome de arquivo ao qual os nomes de arquivo devem corresponder para serem transferidos por upload. Um prefixo vazio faz upload de todos os arquivos no diretório especificado. |
| `p_compression_level` | NUMBER | `0` | optional | O nível de compactação do GZIP. O intervalo de valores válidos varia de `0` a `9`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/UserGuide/oracle-s3-integration.using.html) |
| `p_bucket_owner_full_control` | VARCHAR2 | – | opcional | A configuração de controle de acesso do bucket. Os únicos valores válidos são nulo ou `FULL_CONTROL`. Essa configuração será necessária somente se você carregar arquivos de uma conta (conta A) em um bucket de propriedade de uma conta diferente (conta B), e a conta B precisar ter controle total dos arquivos. |
O valor de retorno do procedimento `rdsadmin.rdsadmin_s3_tasks.upload_to_s3` é um ID de tarefa.
O exemplo a seguir faz upload de todos os arquivos do diretório `DATA_PUMP_DIR` no bucket do Amazon S3 chamado *amzn-s3-demo-bucket*. Os arquivos não são compactados.
```
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;
```
O exemplo a seguir faz upload todos os arquivos com o prefixo `db` no diretório `DATA_PUMP_DIR` para o bucket do Amazon S3 denominado `amzn-s3-demo-bucket`. O Amazon RDS aplica o nível mais alto de compactação GZIP aos arquivos.
```
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;
```
O exemplo a seguir carrega todos os arquivos do diretório `DATA_PUMP_DIR` no bucket do Amazon S3 chamado `amzn-s3-demo-bucket`. Os arquivos são carregados em uma pasta `dbfiles`. Neste exemplo, o nível de compactação GZIP é *1*, que é o nível de compactação mais 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;
```
O exemplo a seguir faz upload todos os arquivos no diretório `DATA_PUMP_DIR` para o bucket do Amazon S3 denominado `amzn-s3-demo-bucket`. Os arquivos são carregados em uma pasta `dbfiles` e `ora` é adicionado ao início de cada nome de arquivo. Nenhuma compactação é aplicada.
```
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;
```
O exemplo a seguir pressupõe que o comando é executado na conta A, mas a conta B requer o controle total do conteúdo do bucket. O comando `rdsadmin_s3_tasks.upload_to_s3` transfere todos os arquivos no diretório `DATA_PUMP_DIR` para o bucket chamado`s3bucketOwnedByAccountB`. O controle de acesso está definido como `FULL_CONTROL` para que a conta B possa acessar os arquivos no bucket. O nível de compactação GZIP é *6*, o que equilibra a velocidade e o tamanho do arquivo.
```
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;
```
Em cada exemplo, a instrução `SELECT` retorna o ID da tarefa em um tipo de dados `VARCHAR2`.
Você pode visualizar o resultado exibindo o arquivo de saída da tarefa.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));
```
Substitua *`task-id`* pelo ID da tarefa retornado pelo procedimento.
**nota**
As tarefas são executadas de forma assíncrona.
## Baixar arquivos de um bucket do Amazon S3 para uma instância de banco de dados Oracle
Para baixar arquivos de um bucket do Amazon S3 para uma instância do RDS para Oracle, use o procedimento `rdsadmin.rdsadmin_s3_tasks.download_from_s3` do Amazon RDS.
O procedimento `download_from_s3` tem os seguintes parâmetros.
****
| Nome do parâmetro | Tipo de dados | Padrão | Obrigatório | Descrição |
| --- | --- | --- | --- | --- |
| `p_bucket_name` | VARCHAR2 | – | Obrigatório | O nome do bucket do Amazon S3 do qual baixar arquivos. |
| `p_directory_name` | VARCHAR2 | – | Obrigatório | O nome do objeto de diretório Oracle no qual baixar arquivos. O diretório pode ser qualquer objeto de diretório criado pelo usuário ou o diretório Data Pump, como `DATA_PUMP_DIR`. |
| `p_error_on_zero_downloads` | VARCHAR2 | FALSE | Opcional | Um sinalizador que determina se a tarefa gera um erro quando nenhum objeto no bucket do Amazon S3 corresponde ao prefixo. Se esse parâmetro não estiver definido ou estiver definido como FALSE (padrão), a tarefa imprimirá uma mensagem de que nenhum objeto foi encontrado, mas não vai gerar uma exceção nem uma falha. Se esse parâmetro for TRUE, a tarefa vai gerar uma exceção e ocorrerá uma falha. Exemplos de especificações de prefixo que podem falhar nos testes de correspondência são espaços em prefixos, como em `' import/test9.log'`, e incompatibilidade de maiúsculas e minúsculas, como em `test9.log` e `test9.LOG`. |
| `p_s3_prefix` | VARCHAR2 | – | Obrigatório | Um prefixo de nome de arquivo ao qual os nomes de arquivo devem corresponder para serem baixados. Um prefixo vazio baixa todos os arquivos de nível superior no bucket do Amazon S3 especificado, mas não os arquivos nas pastas do bucket. O procedimento baixa objetos Amazon S3 somente da pasta de primeiro nível que corresponde ao prefixo. Estruturas de diretório aninhadas que correspondem ao prefixo especificado não são baixados. Por exemplo, suponha que um bucket do Amazon S3 tenha a estrutura de pastas `folder_1/folder_2/folder_3`. Especifique o prefixo `'folder_1/folder_2/'`. Nesse caso, somente os arquivos em `folder_2` são baixados, e não os arquivos em `folder_1` ou `folder_3`. Em vez disso, se você especificar o prefixo `'folder_1/folder_2'`, todos os arquivos em `folder_1` que correspondem ao prefixo `'folder_2'` são baixados, e nenhum arquivo em `folder_2` é baixado. |
| `p_decompression_format` | VARCHAR2 | – | Opcional | O formato da descompactação. Os valores válidos são `NONE` para sem descompactação e `GZIP` para descompactação. |
O valor de retorno do procedimento `rdsadmin.rdsadmin_s3_tasks.download_from_s3` é um ID de tarefa.
O exemplo a seguir baixa todos os arquivos no bucket do Amazon S3 denominado `amzn-s3-demo-bucket` para o diretório `DATA_PUMP_DIR`. Os arquivos não são compactados, portanto, nenhuma descompactação é aplicada.
```
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;
```
O exemplo a seguir baixa todos os arquivos com o prefixo `db` no bucket do Amazon S3 denominado `amzn-s3-demo-bucket` para o diretório `DATA_PUMP_DIR`. Os arquivos são compactados com GZIP, portanto, nenhuma descompactação é aplicada. O parâmetro `p_error_on_zero_downloads` ativa a verificação de erros de prefixo, portanto, se o prefixo não corresponder a nenhum arquivo no bucket, a tarefa vai gerar uma exceção e ocorrerá uma falha.
```
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;
```
O exemplo a seguir baixa todos os arquivos da pasta `myfolder/` no bucket do Amazon S3 denominado `amzn-s3-demo-bucket` para o diretório `DATA_PUMP_DIR`. Use o parâmetro `p_s3_prefix` para especificar a pasta Amazon S3. Os arquivos carregados são compactados com o GZIP, mas não são descompactados durante o download.
```
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;
```
O exemplo a seguir baixa o arquivo `mydumpfile.dmp` no bucket do Simple Storage Service (Amazon S3) denominado `amzn-s3-demo-bucket` para o diretório `DATA_PUMP_DIR`. Nenhuma descompactação é aplicada.
```
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;
```
Em cada exemplo, a instrução `SELECT` retorna o ID da tarefa em um tipo de dados `VARCHAR2`.
Você pode visualizar o resultado exibindo o arquivo de saída da tarefa.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));
```
Substitua *`task-id`* pelo ID da tarefa retornado pelo procedimento.
**nota**
As tarefas são executadas de forma assíncrona.
Você pode usar o procedimento `UTL_FILE.FREMOVE` do Oracle para remover arquivos de um diretório. Para ter mais informações, consulte [Procedimento FREMOVE](https://docs.oracle.com/database/121/ARPLS/u_file.htm#ARPLS70924) na documentação da Oracle.
## Monitorar o status de uma transferência de arquivo
Tarefas de transferência de arquivo de publicar eventos do Amazon RDS quando eles começam e quando são concluídos. A mensagem do evento contém o ID da tarefa para a transferência de arquivos. Para obter informações sobre como visualizar eventos, consulte [Visualizar eventos do Amazon RDS](USER_ListEvents.md).
Você pode visualizar o status de uma tarefa em andamento em um arquivo bdump. Os arquivos bdump estão localizados no diretório `/rdsdbdata/log/trace`. Cada nome de arquivo bdump está no seguinte formato.
```
dbtask-task-id.log
```
Substitua `task-id` pelo ID da tarefa que você deseja monitorar.
**nota**
As tarefas são executadas de forma assíncrona.
Você pode usar o procedimento armazenado `rdsadmin.rds_file_util.read_text_file` para ver o conteúdo dos arquivos bdump. Por exemplo, a consulta a seguir retorna o conteúdo do arquivo bdump `dbtask-1234567890123-1234.log`.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-1234567890123-1234.log'));
```
O exemplo a seguir mostra o arquivo de log de uma falha na transferência.
```
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.
```