Operações em Lote para Arquivos na Nuvem

Sobre operações de arquivo em massa

As operações de arquivo em massa DBMS_CLOUD suportam o download e o upload de arquivos no Autonomous Database, incluindo suporte para copiar, mover e excluir arquivos entre Armazenamentos de Objetos na Nuvem, dentro do mesmo provedor de Armazenamento de Objetos ou entre provedores de Armazenamento de Objetos.

As operações de arquivo em massa suportam paralelismo e fornecem desempenho ideal para upload, download, cópia e movimentação de arquivos. O paralelismo para operações de arquivo em massa é tratado especificando uma prioridade para uma operação. As prioridades apoiadas são:

HIGH: Use a contagem de computação de CPU da instância do Autonomous Database para determinar o número de arquivos paralelos processados.
MEDIUM: Use o limite de simultaneidade do serviço Medium para determinar o paralelismo.
LOW: Processa arquivos em ordem serial (sem simultaneidade).

A execução de operações em massa com prioridade mais alta usa mais recursos e operações de banco de dados completos mais rapidamente quando o paralelismo pode acelerar a operação. Uma prioridade mais baixa consome menos recursos de banco de dados e as operações levam mais tempo para serem concluídas quando o paralelismo pode acelerar a operação. Quando operações em massa envolvem um pequeno número de arquivos que contêm poucos dados, a especificação de prioridade mais alta pode não alterar o desempenho.

Para aumentar o paralelismo para operações de arquivos em massa, use a prioridade HIGH e aumente o número de CPUs designadas à sua instância do Autonomous Database. O máximo de operações de arquivo simultâneas suportadas é limitado a 64 para operações de arquivo em massa.

A prioridade padrão é MEDIUM, que especifica que as operações de arquivo em massa usam o limite de simultaneidade definido para o grupo de consumidores MEDIUM.

Consulte DBMS_CLOUD para Gerenciamento de Arquivos em Massa para obter detalhes sobre como usar o parâmetro format para especificar o priority com operações de arquivo em massa.

Nos subprogramas DBMS_CLOUD discutidos abaixo, credential_name, source_credential_name ou target_credential_name podem ser NULL para URI de bucket público, Pré-autenticado ou Pré-assinado.

Copiar Arquivos em Massa no Cloud Object Storage

Use o procedimento DBMS_CLOUD.BULK_COPY para copiar em massa arquivos de um bucket ou pasta do Object Store para outro bucket ou pasta.

Crie um objeto de credencial para acessar o local de origem.

Por padrão, o nome da credencial de origem, conforme especificado com o parâmetro source_credential_name, também é usado como a credencial do local de destino.

Consulte CREATE_CREDENTIAL para obter mais informações.
Quando a origem e o destino estiverem em Armazenamentos de Objetos distintos ou tiverem contas diferentes com o mesmo provedor de nuvem, crie uma credencial para acessar o local de destino e inclua o parâmetro target_credential_name.
Execute o procedimento DBMS_CLOUD.BULK_COPY para copiar arquivos em paralelo de um bucket ou pasta do Object Store para outro bucket ou pasta que possa estar entre provedor de nuvem, contas e buckets. Para executar o procedimento, você deve fazer log-in como usuário ADMIN ou ter o privilégio EXECUTE em DBMS_CLOUD.
```
BEGIN 
DBMS_CLOUD.BULK_COPY (
      source_credential_name => 'OCI_CRED',
      source_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/o',
      target_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/o',
      format                 => JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKOP')
);
END;
/
```
Este exemplo copia em massa arquivos de um bucket do Oracle Cloud Infrastructure Object Storage para outro.

Consulte BULK_COPY Procedimento para obter mais informações.

Consulte DBMS_CLOUD Formatos de URI do Serviço File Cloud Object Storage para obter mais informações.

Por exemplo, use DBMS_CLOUD.BULK_COPY para copiar arquivos do Amazon S3 para o Oracle Cloud Infrastructure Object Storage.

BEGIN
DBMS_CLOUD.BULK_COPY(      
      source_credential_name  => 'AWS_CRED',
      source_location_uri     => 'https://bucketname.s3-us-west-2.amazonaws.com/',
      target_credential_name  => 'OCI_CRED',
      target_location_uri     => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/o',
      format                  =>  JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKOP')
);
END;
/

Mover Arquivos em Massa pelo Cloud Object Storage

Use o procedimento DBMS_CLOUD.BULK_MOVE para mover arquivos em massa de um local do Cloud Object Storage para outro.

O primeiro passo para mover arquivos é copiá-los para o local de destino. Depois que os arquivos forem copiados com sucesso, eles serão excluídos do local de origem.

Os arquivos serão renomeados em vez de copiados se o Armazenamento de Objetos permitir a renomeação de operações entre locais de origem e destino.

Crie um objeto de credencial para acessar o local de origem.

Por padrão, o nome da credencial de origem, conforme especificado com o parâmetro source_credential_name, também é usado como a credencial do local de destino.

Consulte CREATE_CREDENTIAL para obter mais informações.
Quando a origem e o destino estiverem em Armazenamentos de Objetos distintos ou tiverem contas diferentes com o mesmo provedor de nuvem, crie uma credencial para acessar o local de destino e inclua o parâmetro target_credential_name.
Execute o procedimento DBMS_CLOUD.BULK_MOVE para mover arquivos em massa de um local do Cloud Object Storage para outro. Para executar o procedimento, você deve fazer log-in como usuário ADMIN ou ter o privilégio EXECUTE em DBMS_CLOUD.
```
BEGIN 
DBMS_CLOUD.BULK_MOVE (    
     source_credential_name => 'OCI_CRED',
     source_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/o',
     target_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/o',
     format                 => JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKMOVE')
);
END;
/
```
Este exemplo em massa move arquivos de um local do Oracle Cloud Infrastructure Object Storage para outro.

Consulte BULK_MOVE Procedimento para obter mais informações.

Consulte DBMS_CLOUD Formatos de URI do Serviço File Cloud Object Storage para obter mais informações.

Por exemplo, use DBMS_CLOUD.BULK_MOVE para mover arquivos do Amazon S3 para o Oracle Cloud Infrastructure Object Storage.

BEGIN
DBMS_CLOUD.BULK_MOVE(      
      source_credential_name  => 'AWS_CRED',
      source_location_uri     => 'https://bucketname.s3-us-west-2.amazonaws.com/',
      target_credential_name  => 'OCI_CRED',
      target_location_uri     => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/o',
      format                  =>  JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKOP')
);
END;
/

Download em Massa de Arquivos do Cloud Object Storage

Use o procedimento DBMS_CLOUD.BULK_DOWNLOAD para fazer download em massa de arquivos do local do Armazenamento de Objetos na Nuvem para o objeto de diretório em um Autonomous Database.

Crie uma credencial para acessar o Cloud Object Storage.

O nome da credencial é especificado com o parâmetro credential_name.

Consulte CREATE_CREDENTIAL para obter mais informações.
Execute o procedimento DBMS_CLOUD.BULK_DOWNLOAD para fazer download de arquivos em um diretório do Autonomous Database do Cloud Object Storage. Para executar o procedimento, você deve fazer log-in como usuário ADMIN ou ter o privilégio EXECUTE em DBMS_CLOUD.
```
BEGIN
DBMS_CLOUD.BULK_DOWNLOAD (
     credential_name => 'OCI_CRED',
     location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o',
     directory_name  => 'BULK_TEST',
     format          => JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKOP')
 );
END;
/
```
Este exemplo faz download em massa de arquivos do URI do local do Armazenamento de Objetos do Oracle Cloud Infrastructure para o objeto de diretório em um Autonomous Database.

Observação:
Para gravar os arquivos no objeto de diretório de destino, você deve ter o privilégio WRITE no objeto de diretório.

Consulte BULK_DOWNLOAD Procedimento para obter mais informações.

Consulte DBMS_CLOUD Formatos de URI do Serviço File Cloud Object Storage para obter mais informações.

Upload em Massa de Arquivos para o Cloud Object Storage

Use o procedimento DBMS_CLOUD.BULK_UPLOAD para fazer upload em massa de arquivos de um objeto de diretório no banco de dados para um local do Cloud Object Store.

Crie uma credencial para acessar o Cloud Object Storage.

O nome da credencial é especificado com o parâmetro credential_name.

Consulte CREATE_CREDENTIAL para obter mais informações.
Execute o procedimento DBMS_CLOUD.BULK_UPLOAD para copiar arquivos para o Cloud Object Storage de um diretório de banco de dados na instância do Autonomous Database. Para executar o procedimento, você deve fazer log-in como usuário ADMIN ou ter o privilégio EXECUTE em DBMS_CLOUD.
```
BEGIN
DBMS_CLOUD.BULK_UPLOAD (    
     credential_name => 'OCI_CRED',
     location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o',
     directory_name  => 'BULK_TEST',
     format          => JSON_OBJECT ('logretention' value 5, 'logprefix' value 'BULKUPLOAD')
 );
END;
/
```
Este exemplo faz upload em massa de arquivos de um objeto de diretório, conforme especificado com o parâmetro directory_name para o URI do local do Armazenamento de Objetos do Oracle Cloud Infrastructure.

Observação:
Para ler os arquivos de origem no objeto de diretório, você deve ter o privilégio READ no objeto de diretório.

Consulte BULK_UPLOAD Procedimento para obter mais informações.

Exclusão em Massa de Arquivos do Cloud Object Storage

Use o procedimento DBMS_CLOUD.BULK_DELETE para excluir arquivos em massa do Cloud Object Storage.

Crie uma credencial para acessar o Cloud Object Storage.

O nome da credencial é especificado com o parâmetro credential_name.

O credential_name pode ser NULL para URI de bucket público, Pré-autenticado ou Pré-assinado.

Consulte CREATE_CREDENTIAL para obter mais informações.
Execute o procedimento DBMS_CLOUD.BULK_DELETE para excluir arquivos do Armazenamento de Objetos na Nuvem. Para executar o procedimento, você deve fazer log-in como usuário ADMIN ou ter o privilégio EXECUTE em DBMS_CLOUD.
```
BEGIN
DBMS_CLOUD.BULK_DELETE (    
     credential_name => 'OCI_CRED',
     location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o',
     format          => JSON_OBJECT ('logretention' value 5, 'logprefix' value 'BULKDEL')
);
END;
/
```
Este exemplo exclui em massa arquivos do Armazenamento de Objetos do Oracle Cloud Infrastructure.

Consulte BULK_DELETE Procedimento para obter mais informações.

Consulte DBMS_CLOUD Formatos de URI do Serviço File Cloud Object Storage para obter mais informações.

Monitorar e Solucionar Problemas de Cargas de Arquivos em Massa

Todas as operações de carregamento de dados DBMS_CLOUD são registradas nas views dba_load_operations e user_load_operations.

Você pode usar as seguintes exibições para monitorar e solucionar problemas de cargas de arquivos em massa:

dba_load_operations: mostra todas as operações de carga.
user_load_operations: mostra as operações de carga no seu esquema.

Consulte essas exibições para ver informações sobre operações de arquivo em massa em andamento e concluídas. Por exemplo, a seguinte instrução SELECT com um predicado de cláusula WHERE em TYPE mostra operações DOWNLOAD:


SELECT owner_name, type, status, start_time, update_time, status_table, rows_loaded 
   FROM user_load_operations WHERE type = 'DOWNLOAD';

OWNER_NAME TYPE     STATUS    START_TIME               UPDATE_TIME              STATUS_TABLE ROWS_LOADED 
---------- -------- --------- ------------------------ ------------------------ ------------ ----------- 
"ADMIN"    DOWNLOAD COMPLETED 2022-10-17T20:42:19.498Z 2022-10-17T20:42:21.054Z DWN$2_STATUS           4 
"ADMIN"    DOWNLOAD FAILED    2022-10-17T20:40:54.348Z 2022-10-17T20:40:55.679Z DWN$1_STATUS

A coluna STATUS_TABLE mostra o nome da tabela que você pode consultar para verificar informações detalhadas de log da operação de download em massa. Por exemplo:

DESCRIBE DWN$2_STATUS
Name          Null?    Type                        
------------- -------- --------------------------- 
ID            NOT NULL NUMBER                      
NAME                   VARCHAR2(4000)              
BYTES                  NUMBER                      
CHECKSUM               VARCHAR2(128)               
LAST_MODIFIED          TIMESTAMP(6) WITH TIME ZONE 
STATUS                 VARCHAR2(30)                
ERROR_CODE             NUMBER                      
ERROR_MESSAGE          VARCHAR2(4000)              
START_TIME             TIMESTAMP(6) WITH TIME ZONE 
END_TIME               TIMESTAMP(6) WITH TIME ZONE 
SID                    NUMBER                      
SERIAL#                NUMBER                      
ROWS_LOADED            NUMBER                      

SELECT id, name, bytes, status, error_message, start_time, end_time FROM DWN$2_STATUS;
ID NAME       BYTES STATUS    ERROR_MESSAGE START_TIME               END_TIME                 
-- ---------- ----- --------- ------------- ------------------------ ------------------------ 
 1 trees.txt     58 COMPLETED               2022-10-17T20:42:19.998Z 2022-10-17T20:42:20.421Z 
 2 trees1.txt    58 COMPLETED               2022-10-17T20:42:20.425Z 2022-10-17T20:42:20.533Z 
 3 trees2.txt    58 COMPLETED               2022-10-17T20:42:20.535Z 2022-10-17T20:42:20.894Z 
 4 trees3.txt    58 COMPLETED               2022-10-17T20:42:20.896Z 2022-10-17T20:42:21.043Z

A tabela de status mostra cada nome de arquivo e seu status para a operação em massa.

O número de erro e a mensagem relevantes serão registrados na tabela de status se uma operação em um arquivo específico falhar.

Para operações concluídas, o tempo necessário para cada operação pode ser calculado usando o tempo reportado START_TIME e END_TIME.

A coluna STATUS da operação de arquivo pode ter um dos seguintes valores:

Status do Arquivo	Descrição
`COMPLETED`	Operação de arquivo concluída com sucesso.
`FAILED`	Falha na operação do arquivo. Uma nova tentativa pode ser feita duas vezes.
`PENDING`	A operação do arquivo ainda não foi iniciada.
`RUNNING`	A operação de arquivo está em andamento atualmente.
`SKIPPED`	Operação de arquivo ignorada.

Se qualquer operação de arquivo falhar após duas tentativas de repetição, a operação em massa será marcada como com falha e um erro será gerado. Por exemplo:

ORA-20003: Operation failed, please query table DOWNLOAD$2_STATUS for error details

Quando você usa uma operação de arquivo em massa DBMS_CLOUD, há opções de parâmetro format que controlam tabelas de status:

logretention: Especifica um valor inteiro que determina a duração em dias em que a tabela de status é retida. O valor padrão é 2 dias.

logprefix: Especifica um valor de string que determina o prefixo de nome da tabela de status da operação em massa.

Cada operação em lote tem seu próprio valor padrão para a opção logprefix:

Procedimento	Valor Padrão para `logprefix`
`DBMS_CLOUD.BULK_COPY`	`COPYOBJ`
`DBMS_CLOUD.BULK_DELETE`	`DELETE`
`DBMS_CLOUD.BULK_DOWNLOAD`	`DOWNLOAD`
`DBMS_CLOUD.BULK_MOVE`	`MOVE`
`DBMS_CLOUD.BULK_UPLOAD`	`UPLOAD`

Consulte Procedimento DELETE_ALL_OPERATIONS para obter informações sobre como limpar a tabela user_load_operations.