Operações em Lote para Arquivos na Nuvem

As operações de arquivo em massa suportam paralelismo e fornecem desempenho ideal para upload, download, cópia e movimentação de arquivos. 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 para o serviço Médio para determinar o paralelismo.
• LOW: Processar arquivos em ordem serial (sem simultaneidade).

A execução de operações em massa com prioridade mais alta usa mais recursos de banco de dados e as operações são concluídas com mais rapidez quando o paralelismo pode acelerar a operação. Uma prioridade mais baixa consome menos recursos de banco de dados e as operações demoram mais para serem concluídas quando o paralelismo pode acelerar a operação. Quando operações em massa envolvem pequenos números de arquivos que contêm poucos dados, especificar prioridade mais alta pode não alterar o desempenho.

Para aumentar o paralelismo das operações de arquivo 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 Gerenciar Simultaneidade e Prioridades no Autonomous Database para obter mais informações.

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

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.

1. 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 Procedures para obter mais informações.

2. Quando a origem e o destino estiverem em Áreas de Armazenamento de Objetos distintas 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.
3. 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 pode ser entre provedor de nuvem, contas e buckets. Para executar o procedimento, você deve estar conectado 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 arquivos em massa de um bucket do Oracle Cloud Infrastructure Object Storage para outro.

   Consulte BULK_COPY Procedures para obter mais informações.

   Consulte DBMS_CLOUD Formatos de URI para obter mais informações.

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;
/

1. 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 Procedures para obter mais informações.

2. Quando a origem e o destino estiverem em Áreas de Armazenamento de Objetos distintas 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.
3. 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 estar conectado 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 move arquivos em massa de um local do Oracle Cloud Infrastructure Object Storage para outro.

   Consulte BULK_MOVE Procedures para obter mais informações.

   Consulte DBMS_CLOUD Formatos de URI para obter mais informações.

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;
/

Use o procedimento DBMS_CLOUD.BULK_DOWNLOAD para fazer download em massa de arquivos do local do Cloud Object Store para o objeto de diretório em um Autonomous Database.

1. Crie uma credencial para acessar seu Cloud Object Storage.

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

   Consulte CREATE_CREDENTIAL Procedures para obter mais informações.

2. Execute o procedimento DBMS_CLOUD.BULK_DOWNLOAD para fazer download de arquivos em um diretório do Autonomous Database no Cloud Object Storage. Para executar o procedimento, você deve estar conectado 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 de arquivos em massa do URI do local do Oracle Cloud Infrastructure Object Store para o objeto de diretório em um Autonomous Database.

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

   Consulte BULK_DOWNLOAD Procedures para obter mais informações.

   Consulte DBMS_CLOUD Formatos de URI para obter mais informações.

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.

1. Crie uma credencial para acessar seu Cloud Object Storage.

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

   Consulte CREATE_CREDENTIAL Procedures para obter mais informações.

2. Execute o procedimento DBMS_CLOUD.BULK_UPLOAD para copiar arquivos para o Cloud Object Storage de um diretório de banco de dados na sua instância do Autonomous Database. Para executar o procedimento, você deve estar conectado 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 de local do Oracle Cloud Infrastructure Object Store.

   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 Procedures para obter mais informações.

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

1. Crie uma credencial para acessar seu 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 ou Pré-autenticado ou Pré-assinado.

   Consulte CREATE_CREDENTIAL Procedures para obter mais informações.

2. Execute o procedimento DBMS_CLOUD.BULK_DELETE para excluir arquivos do Cloud Object Store. Para executar o procedimento, você deve estar conectado 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 Oracle Cloud Infrastructure Object Store.

   Consulte BULK_DELETE Procedures para mais informações.

   Consulte DBMS_CLOUD Formatos de URI para obter mais informações.

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 views para monitorar e solucionar problemas de carregamentos 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 views para ver informações sobre operações de arquivos em massa em andamento e concluídas. Por exemplo, a seguinte instrução SELECT com um predicado de cláusula WHERE na 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 de log detalhadas 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 relevante e a mensagem são gravados 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 START_TIME e END_TIME relatados.

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

Se qualquer operação de arquivo falhar após duas tentativas de repetição, a operação em massa será marcada como 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 as tabelas de status:

• logretention: Especifica um valor inteiro que determina a duração em dias da retenção da tabela de status. O valor default é 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 massa 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.

Fornece observações para as credenciais que você usa com operações de arquivo em massa.

• Você pode especificar principais como o parâmetro credential_name, source_credential_name ou target_credential_name para acessar recursos da nuvem com segurança sem armazenar credenciais do usuário. Os principais suportados são:

  • Principais de Recursos do Oracle Cloud Infrastructure
  • Nomes de recursos (ARN) da AWS Amazon
  • Controlador de serviços do Azure
  • Conta do Google Service

  Consulte Configurar Políticas e Atribuições para Acessar Recursos para obter mais informações.

• O credential_name, o source_credential_name ou o target_credential_name podem ser NULL para URI de bucket público, Pré-autenticado ou Pré-assinado.