Use credenciais de serviço de nuvem armazenadas para acessar o serviço de nuvem para carregamento de dados, para consulta de dados externos residentes na nuvem ou para outros casos ao usar procedimentos DBMS_CLOUD com um parâmetro credential_name. Este procedimento é sobrecarregado:

• Use os parâmetros relacionados ao Oracle Cloud Infrastructure, incluindo: user_ocid, tenancy_ocid, private_key e fingerprint somente quando estiver usando a autenticação Chaves de Assinatura do Oracle Cloud Infrastructure.

• Use o parâmetro params para uma das seguintes opções:

  • Credenciais de ARNs (Amazon Resource Names)

  • Credenciais do Google Analytics ou do Google BigQuery

  • Credenciais de segredo do vault para uso com um vault suportado:

    • Oracle Cloud Infrastructure Vault
    • Vault Principal do Azure
    • AWS Secrets Manager
    • Gerenciador de segredos do GCP

Sintaxe

DBMS_CLOUD.CREATE_CREDENTIAL (
      credential_name   IN VARCHAR2,
      username          IN VARCHAR2,
      password          IN VARCHAR2 DEFAULT NULL,
      comments          IN VARCHAR2 DEFAULT NULL);


DBMS_CLOUD.CREATE_CREDENTIAL (
      credential_name   IN VARCHAR2,
      user_ocid         IN VARCHAR2,
      tenancy_ocid      IN VARCHAR2,
      private_key       IN VARCHAR2,
      fingerprint       IN VARCHAR2,
      comments          IN VARCHAR2 DEFAULT NULL);


DBMS_CLOUD.CREATE_CREDENTIAL (
      credential_name  IN VARCHAR2,
      params           IN CLOB DEFAULT);

Parâmetros

Observações de Uso

• Esta operação armazena as credenciais no banco de dados em um formato criptografado.

• Você pode ver as credenciais no seu esquema consultando a tabela user_credentials.

• Você pode ver os comentários da credencial no seu esquema consultando a tabela user_credentials. Por exemplo:

  SELECT comments FROM user_credentials
          WHERE credential_name = 'MY_CRED';

• O usuário ADMIN pode ver todas as credenciais consultando a tabela dba_credentials.

• Você só precisa criar credenciais uma vez, a menos que suas credenciais de serviço de nuvem mudem. Depois de armazenar as credenciais, você poderá usar o mesmo nome de credencial para procedimentos DBMS_CLOUD que exigem um parâmetro credential_name.

• Este procedimento é sobrecarregado. Se você fornecer um dos atributos de autenticação baseados em chave, user_ocid, tenancy_ocid, private_key ou fingerprint, será considerado que que a chamada é uma credencial baseada na Chave de Assinatura do Oracle Cloud Infrastructure.

• Você pode listar credenciais na view ALL_CREDENTIALS. Por exemplo, execute o seguinte comando para listar credenciais:

  SELECT credential_name, username, comments FROM all_credentials;

Credenciais do Oracle Cloud Infrastructure (Tokens de Autenticação)

Para o Oracle Cloud Infrastructure, o username é o seu nome de usuário do Oracle Cloud Infrastructure. A password é o seu token de autenticação do Oracle Cloud Infrastructure. Consulte Como Trabalhar com Tokens de Autenticação.

Por exemplo:

BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'DEF_CRED_NAME',
    username => 'adb_user@example.com',
    password => 'password' );
END;
/

Use credenciais baseadas em Token de Autenticação ao autenticar chamadas para o OCI Object Storage. Para chamadas para qualquer outro tipo de serviço de nuvem do Oracle Cloud Infrastructure, use Credenciais Baseadas em Chave de Assinatura do Oracle Cloud Infrastructure.

Para o OCI Object Storage, o valor do parâmetro username deve incluir o domínio de Identidades e o nome de usuário do seu perfil. Você pode encontrar o domínio de Identidades associado a um usuário na Console do Oracle Cloud Infrastructure.

Por exemplo:

oracleidentitycloudservice/adb_user@example.com

Com o domínio de Identidades padrão, você não precisa incluir o nome de domínio Default. Por exemplo:

adb_user@example.com

Credenciais Baseadas em Chave de Assinatura do Oracle Cloud Infrastructure

Use os parâmetros relacionados à chave de assinatura do Oracle Cloud Infrastructure, incluindo: user_ocid, tenancy_ocid, private_key e fingerprint com a autenticação de Chaves de Assinatura do Oracle Cloud Infrastructure.

Por exemplo:

BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL (
       credential_name => ‘OCI_KEY_CRED’,
       user_ocid       => ‘ocid1.user.oc1..aaaaaaaauq54mi7zdyfhw33ozkwuontjceel7fok5nq3bf2vwetkpqsoa’,
       tenancy_ocid    => ‘ocid1.tenancy.oc1..aabbbbbbaafcue47pqmrf4vigneebgbcmmoy5r7xvoypicjqqge32ewnrcyx2a’,
       private_key     => ‘MIIEogIBAAKCAQEAtUnxbmrekwgVac6FdWeRzoXvIpA9+0r1.....wtnNpESQQQ0QLGPD8NM//JEBg=’,
       fingerprint     => ‘f2:db:f9:18:a4:aa:fc:94:f4:f6:6c:39:96:16:aa:27’);
END;
/

Não há suporte para chaves privadas geradas com uma frase-senha. É necessário gerar a chave privada sem uma frase-senha. Consulte Como Gerar uma Chave de Assinatura de API para obter mais informações.

Credenciais do Oracle Cloud Infrastructure Object Storage Classic

Se seus arquivos de origem residirem no Oracle Cloud Infrastructure Object Storage Classic, username será seu nome de usuário do Oracle Cloud Infrastructure Classic e password será sua senha do Oracle Cloud Infrastructure Classic.

Credenciais do Amazon Web Services (AWS)

Se seus arquivos de origem residirem no Amazon S3 ou você estiver chamando uma API da AWS, username será seu ID da chave de acesso da AWS e password será sua chave de acesso secreta da AWS. Consulte AWS Identity and Access Management.

Credenciais do Microsoft Azure

Se seus arquivos de origem residirem no Armazenamento de Blobs do Azure ou no Armazenamento do Data Lake do Azure ou você estiver chamando uma API do Azure, username será o nome da conta de armazenamento do Azure e password será uma chave de acesso à conta de armazenamento do Azure. Consulte Sobre contas de armazenamento do Azure.

Credenciais Compatíveis com o Amazon S3

Credenciais do ARN (Amazon Resource Names) da AWS

Se seus arquivos de origem residirem no Amazon S3 ou você estiver chamando uma API da AWS, use params para especificar os parâmetros do ARN (Amazon Resource Names).

Por exemplo:

BEGIN DBMS_CLOUD.CREATE_CREDENTIAL(
        credential_name      => 'MY_CRED',
        params               => JSON_OBJECT(
               'aws_role_arn'      value 'arn:aws:iam::123456:role/AWS_ROLE_ARN',
               'external_id_type'  value 'database_ocid'));
END;
/

GitHub Token de Acesso Pessoal

Se seus arquivos de origem residirem em um repositório GitHub ou você estiver chamando uma API GitHub, username será seu e-mail GitHub e password será seu token de acesso pessoal GitHub. Consulte Criando um token de acesso pessoal para obter mais informações.

Por exemplo:

BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'MY_GITHUB_CRED',
    username => 'user@example.com',
    password => 'your_personal_access_token' );
END;
/

Credenciais do Google Analytics ou do Google BigQuery

Se você estiver acessando o Google Analytics ou o Google BigQuery, use o parâmetro params para especificar os parâmetros de credencial OAuth 2.0 do Google.

Por exemplo:

BEGIN DBMS_CLOUD.CREATE_CREDENTIAL(
      credential_name => 'GOOGLE_BIGQUERY_CRED',
      params => JSON_OBJECT('gcp_oauth2' value 
                                  JSON_OBJECT(
                                       'client_id'     value 'client_id',
                                       'client_secret' value 'client_secret',
                                       'refresh_token' value 'refresh_token' )));
END;
/

Credenciais de Segredo do Vault com o Oracle Cloud Infrastructure Vault

Para criar credenciais de segredo do vault com o Oracle Cloud Infrastructure Vault, use o parâmetro params para especificar os parâmetros necessários:

• username: Especifica o nome de usuário de qualquer tipo de credencial de nome de usuário/senha, como o nome de usuário da senha Swift do OCI. Por exemplo, se você tiver uma credencial Swift com o nome de usuário "scott" e a senha como "password", forneça "scott" como o parâmetro username.

• secret_id: É o ID do segredo do vault. Especifique o valor secret_id como o OCID do segredo do vault. Consulte Visão Geral do Vault para obter mais informações.

• region: É um parâmetro opcional que especifica o identificador da região do oracle cloud. A região, quando especificada, indica o local onde o segredo do Oracle Cloud Infrastructure Vault está localizado.

  Por padrão, CREATE_CREDENTIAL usa o region mapeado da chave de região no secret_id. Um exemplo de região é us-ashburn-1.

  Consulte Regiões e Domínios de Disponibilidade para obter uma lista completa de regiões.

Por exemplo:

BEGIN DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'OCI_SECRET_CRED',
    params => JSON_OBJECT( 
                'username'   value 'scott',
                'region'     value 'us-ashburn-1',
                'secret_id'  value 'ocid1.vaultsecret.co1.ap-mumbai-1.example..aaaaaaaauq5ok5nq3bf2vwetkpqsoa'));
END;
/

Observações sobre o uso de um segredo do Oracle Cloud Infrastructure Vault para armazenar segredos do vault:

• Ao usar um Oracle Cloud Infrastructure Vault, na instância do Autonomous Database, você deve ativar a autenticação principal com DBMS_CLOUD_ADMIN.ENABLE_RESOURCE_PRINCIPAL.

• No Oracle Cloud Infrastructure, você deve especificar uma política para que o controlador de recursos acesse o segredo.

Para criar uma credencial secreta do vault, você deve ter o privilégio EXECUTE no pacote DBMS_CLOUD.

Credenciais de Segredo do Vault com o Azure Key Vault

Para criar credenciais do Azure Key Vault, use o parâmetro params para especificar os parâmetros necessários:

• username: Especifica o nome de usuário associado à chave.

• secret_id: Especifica o nome do segredo.

• azure_vault_name: Especifica o nome do vault no qual o segredo está localizado.

Consulte Criar um vault de chaves para obter mais informações.

Para criar uma credencial secreta do vault, você deve ter o privilégio EXECUTE no pacote DBMS_CLOUD.

Credenciais de Segredo do Vault com o AWS Secrets Manager

Para criar credenciais de segredo do vault com o AWS Secrets Manager, use o parâmetro params para especificar os parâmetros necessários:

• username: Especifica a chave de acesso do AWS Secrets Manager.

• secret_id: O AWS Secrets Manager é o AWS ARN.

• region: (Opcional) Especifica a região de serviço da AWS na qual o vault e o segredo estão localizados. Um exemplo da região da AWS é "us-east-2". O region padrão é a região especificada com o ARN no parâmetro secret_id.

  Consulte Gerenciando Regiões da AWS para obter mais informações.

  Para criar uma credencial secreta do vault, você deve ter o privilégio EXECUTE no pacote DBMS_CLOUD.

Credenciais de Segredo do Vault com o GCP Secret Manager

Para criar credenciais do GCP Secret Manager, use o parâmetro params para especificar os parâmetros necessários:

• username: Especifica o nome de usuário associado ao segredo.

• secret_id: É o nome do segredo.

• gcp_project_id: Especifica o ID do projeto no qual o segredo está localizado.

Consulte Gerenciador de Segredos para obter mais informações.

Para criar uma credencial secreta do vault, você deve ter o privilégio EXECUTE no pacote DBMS_CLOUD.

Sintaxe

DBMS_CLOUD.DROP_CREDENTIAL (
   credential_name     IN VARCHAR2);

Parâmetros

Este procedimento permite que você atualize imediatamente o segredo do vault de uma credencial de segredo do vault para obter a versão mais recente do segredo do vault para o credential_name especificado.

Sintaxe

DBMS_CLOUD.REFRESH_VAULT_CREDENTIAL (
    credential_name   IN VARCHAR2);

Parâmetros

Observações de Uso

• O usuário ADMIN pode ver todas as credenciais consultando a tabela dba_credentials.

• Você pode listar credenciais na view ALL_CREDENTIALS. Por exemplo, execute o seguinte comando para listar credenciais:

  SELECT credential_name, username, comments FROM all_credentials;

Exemplo

BEGIN
  DBMS_CLOUD.REFRESH_VAULT_CREDENTIAL(
     credential_name => 'AZURE_SECRET_CRED'); 
END;
/

Use credenciais armazenadas para carregamento de dados, para consultar dados externos que residem na Nuvem ou sempre que usar procedimentos DBMS_CLOUD com o parâmetro credential_name.

Sintaxe

DBMS_CLOUD.UPDATE_CREDENTIAL (
    credential_name   IN VARCHAR2,
    attribute         IN VARCHAR2,
    value             IN VARCHAR2);

Parâmetros

Observações de Uso

• O valor do nome do usuário faz distinção entre maiúsculas e minúsculas. Ele não pode conter aspas duplas ou espaços.

• O usuário ADMIN pode ver todas as credenciais consultando dba_credentials.

• Você só precisa criar credenciais uma vez, a menos que suas credenciais de serviço de nuvem mudem. Depois de armazenar as credenciais, você poderá usar o mesmo nome de credencial para procedimentos DBMS_CLOUD que exigem um parâmetro credential_name.

• Você pode listar credenciais na view ALL_CREDENTIALS. Por exemplo, execute o seguinte comando para listar credenciais:

  SELECT credential_name, username, comments FROM all_credentials;

Exemplos

BEGIN
  DBMS_CLOUD.UPDATE_CREDENTIAL(
     credential_name => 'OBJ_STORE_CRED',
     attribute => 'PASSWORD',
     value => 'password'); 
END;
/

BEGIN
  DBMS_CLOUD.UPDATE_CREDENTIAL(
     credential_name => 'ARN_CRED',
     attribute => 'aws_role_arn',
     value => 'NEW_AWS_ARN'); 
END;
/

Sintaxe

DBMS_CLOUD.COPY_COLLECTION (
    collection_name   IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    format            IN CLOB     DEFAULT NULL
);

DBMS_CLOUD.COPY_COLLECTION (
    collection_name   IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    format            IN CLOB     DEFAULT NULL,
    operation_id      OUT NOCOPY NUMBER
);

Parâmetros

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

Exemplo

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(
            credential_name => 'OBJ_STORE_CRED',
            username        => 'user_name@oracle.com',
            password        => 'password'
            );

    DBMS_CLOUD.COPY_COLLECTION(
            collection_name => 'myCollection',
            credential_name => 'OBJ_STORE_CRED',
            file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/adbexample/b/json/o/myCollection.json'  
            );
END;
/

Sintaxe

DBMS_CLOUD.COPY_DATA (
    table_name        IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    schema_name       IN VARCHAR2,
    field_list        IN CLOB,
    format            IN CLOB);

DBMS_CLOUD.COPY_DATA (
    table_name        IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB DEFAULT NULL,
    schema_name       IN VARCHAR2 DEFAULT NULL,
    field_list        IN CLOB DEFAULT NULL,
    format            IN CLOB DEFAULT NULL
    operation_id      OUT NOCOPY NUMBER);

Parâmetros

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

Nota de Uso

O limite de registro padrão é detected newline. Com detected newline, o DBMS_CLOUD tenta localizar automaticamente o caractere correto de nova linha a ser usado como delimitador de registro. O DBMS_CLOUD primeiro procura o caractere de nova linha do Windows \r\n. Se encontrar o caractere de nova linha do Windows, ele será usado como delimitador de registro para todos os arquivos do procedimento. Se um caractere de nova linha do Windows não for encontrado, o DBMS_CLOUD procurará o \n do UNIX/Linux e, caso encontre um, ele usará \n como delimitador para todos os arquivos do procedimento. Se os arquivos de origem usarem uma combinação de diferentes delimitadores de registro, você poderá encontrar um erro como, "KUP-04020: found record longer than buffer size supported". Nesse caso, modifique os arquivos de origem para usar o mesmo delimitador de registro ou só especifique arquivos de origem que utilizem o mesmo delimitador de registro.

Consulte DBMS_CLOUD Package Format Options para obter informações sobre a opção de formato recorddelmiter.

Exemplos

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(
            credential_name => 'DEF_CRED_NAME',
            username        => 'user_name@oracle.com',
            password        => 'password'
            );
END;
/

BEGIN
 DBMS_CLOUD.COPY_DATA(
    table_name =>'CHANNELS',
    credential_name =>'DEF_CRED_NAME',
    file_uri_list =>'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/channels.txt',
    format => json_object('delimiter' value ',')
 );
END;
/

BEGIN
    DBMS_CLOUD.COPY_DATA(
            table_name      => 'ORDERS',
            schema_name     => 'TEST_SCHEMA',
            credential_name => 'DEF_CRED_NAME',
	     file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/adbexample/b/json/o/orde[r]s.tbl.1'
            format          =>  json_object('ignoreblanklines' value TRUE,
                                            'rejectlimit' value '0',
                                            'dateformat' value 'yyyy-mm-dd',
                                            'regexuri' value TRUE)
            );
END;
/

Sintaxe

DBMS_CLOUD.COPY_DATA (
    table_name        IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    schema_name       IN VARCHAR2 DEFAULT,
    field_list        IN CLOB DEFAULT,
    format            IN CLOB DEFAULT);

Parâmetros

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

Observações de Uso

• Assim como com outros arquivos de dados, as cargas de dados Avro, ORC e Parquet geram logs que podem ser visualizados nas tabelas dba_load_operations e user_load_operations. Cada operação de carga adiciona um registro a dba[user]_load_operations que indica a tabela que contém os logs.

  A tabela de log fornece informações resumidas sobre a carga.

• Para Avro, ORC ou Parquet, quando o parâmetro format type é definido com o valor avro, orc ou parquet, a tabela BADFILE_TABLE fica sempre vazia.

  • Para arquivos Parquet, erros de restrição PRIMARY KEY geram um erro ORA.

  • Se os dados de uma coluna encontrarem um erro de conversão, por exemplo, a coluna de destino não for grande o suficiente para conter o valor convertido, o valor da coluna será definido como NULL. Isso não gera um registro rejeitado.

O bucket ou pasta de origem e destino pode estar no mesmo provedor de armazenamento do Cloud Object ou em outro provedor.

Quando a origem e o destino estão em Armazenamentos de Objetos distintos ou têm contas diferentes com o mesmo provedor de nuvem, você pode fornecer nomes de credenciais separados para os locais de origem e destino.

Por padrão, o nome da credencial de origem também é usado pelo local de destino quando o nome da credencial de destino não é fornecido.

Sintaxe

DBMS_CLOUD.COPY_OBJECT (
    source_credential_name  IN  VARCHAR2 DEFAULT NULL,
    source_object_uri       IN  VARCHAR2,
    target_object_uri       IN  VARCHAR2,
    target_credential_name  IN  VARCHAR2 DEFAULT NULL
);

Parâmetros

Exemplo

BEGIN 
DBMS_CLOUD.COPY_OBJECT (
    source_credential_name => 'OCI_CRED',
    source_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/bgfile.csv',
    target_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/myfile.csv'
);
END;
/

Sintaxe

DBMS_CLOUD.CREATE_CLOUD_TABLE (
    table_name       IN VARCHAR2,
    column_list      IN CLOB,
    params           IN CLOB);

Parâmetros

Observações de Uso

• Atributos DEFAULT: O column_list pode incluir a cláusula DEFAULT, que funciona como a cláusula DEFAULT em um CREATE TABLE comum. Consulte CREATE TABLE para obter informações sobre o comportamento da cláusula DEFAULT.

• Use DROP TABLE para eliminar uma Tabela da Nuvem. As Tabelas da Nuvem não suportam a lixeira.

  Por exemplo:

  DROP TABLE CLOUD_TAB1; 

• Você pode conceder privilégios SELECT, INSERT e UPDATE para uma Tabela da Nuvem. Nenhum outro privilégio pode ser concedido a uma Tabela da Nuvem.

  Consulte Configurando Autorização de Privilégio e Função para obter mais informações.

Exemplos

EXEC DBMS_CLOUD.CREATE_CLOUD_TABLE( 'CLOUD_TAB1', 'I INTEGER, J INTEGER' );

BEGIN
  DBMS_CLOUD.CREATE_CLOUD_TABLE(
   table_name  => 'CLOUD_TABLE_WITH_DEFAULT',
   column_list => 'I INTEGER,
                   A VARCHAR2(32) DEFAULT ''ABC''' );
END;
/

Sintaxe

DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE (
    table_name           IN VARCHAR2,
    credential_name      IN VARCHAR2,
    partitioning_clause  IN CLOB,
    column_list          IN CLOB,
    field_list           IN CLOB DEFAULT,
    format               IN CLOB DEFAULT);


DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE (
    table_name           IN VARCHAR2,
    credential_name      IN VARCHAR2,
    file_uri_list        IN VARCHAR2,
    column_list          IN CLOB,
    field_list           IN CLOB DEFAULT,
    format               IN CLOB DEFAULT);

Parâmetros

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

Observações de Uso

• Você não pode chamar esse procedimento com os parâmetros partitioning_clause e file_uri_list.

• A especificação do parâmetro column_list é opcional com arquivos de dados estruturados, incluindo arquivos de dados Avro, Parquet ou ORC. Se column_list não for especificado, a opção partition_columns do parâmetro format deverá incluir name e type.

• O parâmetro column_list é obrigatório com arquivos de dados não estruturados, como arquivos de texto CSV.

• O procedimento DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE suporta arquivos particionados externos nos serviços de armazenamento de objetos na nuvem suportados, que incluem:

  • Oracle Cloud Infrastructure Object Storage

  • Azure Blob Storage ou Azure Data Lake Storage

  • Amazon S3

  • Compatível com Amazon S3, incluindo: Oracle Cloud Infrastructure Object Storage, Google Cloud Storage e Wasabi Hot Cloud Storage.

  • GitHub Repositório

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

• O procedimento DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE suporta arquivos particionados externos em diretórios, seja em um sistema de arquivos local ou em um sistema de arquivos de rede.

• Quando você chama DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE com o parâmetro file_uri_list, os tipos das colunas especificadas no nome do arquivo do Armazenamento de Objetos na Nuvem devem ser um destes:

  VARCHAR2(n)
  NUMBER(n)
  NUMBER(p,s)
  NUMBER
  DATE
  TIMESTAMP(9)

• O limite de registro padrão é detected newline. Com detected newline, o DBMS_CLOUD tenta localizar automaticamente o caractere correto de nova linha a ser usado como delimitador de registro. O DBMS_CLOUD primeiro procura o caractere de nova linha do Windows \r\n. Se encontrar o caractere de nova linha do Windows, ele será usado como delimitador de registro para todos os arquivos do procedimento. Se um caractere de nova linha do Windows não for encontrado, o DBMS_CLOUD procurará o \n do UNIX/Linux e, caso encontre um, ele usará \n como delimitador para todos os arquivos do procedimento. Se os arquivos de origem usarem uma combinação de diferentes delimitadores de registro, você poderá encontrar um erro como, "KUP-04020: found record longer than buffer size supported". Nesse caso, modifique os arquivos de origem para usar o mesmo delimitador de registro ou só especifique arquivos de origem que utilizem o mesmo delimitador de registro.

  Consulte DBMS_CLOUD Package Format Options para obter informações sobre a opção de formato recorddelmiter.

• As tabelas particionadas externas criadas com DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE incluem duas colunas invisíveis file$path e file$name. Essas colunas ajudam a identificar de qual arquivo um registro está vindo.

  • file$path: Especifica o texto do caminho do arquivo até o início do nome do objeto.

  • file$name: Especifica o nome do objeto, incluindo todo o texto que segue o nome do bucket.

Exemplos

Exemplo usando o parâmetro partitioning_clause:

BEGIN  
   DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
      table_name =>'PET1',  
      credential_name =>'OBJ_STORE_CRED',
      format => json_object('delimiter' value ',', 'recorddelimiter' value 'newline', 'characterset' value 'us7ascii'),
      column_list => 'col1 number, col2 number, col3 number',
      partitioning_clause => 'partition by range (col1)
                                (partition p1 values less than (1000) location
                                    ( ''&base_URL//file_11.txt'')
                                 ,
                                 partition p2 values less than (2000) location
                                    ( ''&base_URL/file_21.txt'')
                                 ,
                                 partition p3 values less than (3000) location 
                                    ( ''&base_URL/file_31.txt'')
                                 )'
     );
   END;
/  


BEGIN
    DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
       table_name          => 'PET',
       format              => json_object('delimiter'value ','),
       column_list         => 'name varchar2(20), gender varchar2(10), salary number',
       partitioning_clause => 'partition by range (salary)
              (   -- Use test1.csv in the DEFAULT DIRECTORY DATA_PUMP_DIR 
                  partition p1 values less than (100) LOCATION (''test1.csv''),
                   -- Use test2.csv in a specified directory MY_DIR
                  partition p2 values less than (300) DEFAULT DIRECTORY MY_DIR LOCATION (''test2.csv'')        )'   );                       
END;                     
/

Exemplo usando os parâmetros file_uri_list e column_list com arquivos de dados não estruturados:

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
   table_name => 'MYSALES',
   credential_name => 'DEF_CRED_NAME',
   file_uri_list     => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/*.csv', 
   column_list       => 'product varchar2(100), units number, country varchar2(100), year number, month varchar2(2)', 
   field_list        => 'product, units', --[Because country, year and month are not in the file, they are not listed in the field list]
   format            => '{"type":"csv", "partition_columns":["country","year","month"]}');
END;
/ 

Exemplo usando o file_uri_list sem o parâmetro column_list com arquivos de dados estruturados:

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
  table_name => 'MYSALES',
  credential_name => 'DEF_CRED_NAME',
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
    table_name      => 'MYSALES',
    credential_name => 'DEF_CRED_NAME',
    file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/*.parquet',
    format          => 
        json_object('type' value 'parquet', 'schema' value 'first',
                    'partition_columns' value 
                          json_array(
                                json_object('name' value 'country', 'type' value 'varchar2(100)'),
                                json_object('name' value 'year', 'type' value 'number'),
                                json_object('name' value 'month', 'type' value 'varchar2(2)')
                          )
         )
    );
END;
/

Sintaxe

DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
    table_name       IN VARCHAR2,
    credential_name  IN VARCHAR2 DEFAULT NULL,
    file_uri_list    IN CLOB,
    column_list      IN CLOB,
    field_list       IN CLOB DEFAULT,
    format           IN CLOB DEFAULT);

Parâmetros

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

Observações de Uso

• O procedimento DBMS_CLOUD.CREATE_EXTERNAL_TABLE suporta arquivos particionados externos nas origens de armazenamento de objetos na nuvem compatíveis, incluindo:

  • Oracle Cloud Infrastructure Object Storage

  • Azure Blob Storage ou Azure Data Lake Storage

  • Amazon S3

  • Compatível com Amazon S3, incluindo: Oracle Cloud Infrastructure Object Storage, Google Cloud Storage e Wasabi Hot Cloud Storage.

  • GitHub Repositório

  • Oracle Cloud Infrastructure Object Storage com URLs de Hiperlink de Tabela

  A credencial é uma propriedade em nível de tabela; portanto, os arquivos externos devem estar no mesmo armazenamento de objetos.

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

• O limite de registro padrão é detected newline. Com detected newline, o DBMS_CLOUD tenta localizar automaticamente o caractere correto de nova linha a ser usado como delimitador de registro. O DBMS_CLOUD primeiro procura o caractere de nova linha do Windows \r\n. Se encontrar o caractere de nova linha do Windows, ele será usado como delimitador de registro para todos os arquivos do procedimento. Se um caractere de nova linha do Windows não for encontrado, o DBMS_CLOUD procurará o \n do UNIX/Linux e, caso encontre um, ele usará \n como delimitador para todos os arquivos do procedimento. Se os arquivos de origem usarem uma combinação de diferentes delimitadores de registro, você poderá encontrar um erro como, "KUP-04020: found record longer than buffer size supported". Nesse caso, modifique os arquivos de origem para usar o mesmo delimitador de registro ou só especifique arquivos de origem que utilizem o mesmo delimitador de registro.

  Consulte DBMS_CLOUD Package Format Options para obter informações sobre a opção de formato recorddelimiter.

Exemplo

BEGIN  
   DBMS_CLOUD.CREATE_EXTERNAL_TABLE(   
      table_name =>'WEATHER_REPORT_DOUBLE_DATE',   
      credential_name =>'OBJ_STORE_CRED',   
      file_uri_list =>'&base_URL/Charlotte_NC_Weather_History_Double_Dates.csv',
      format => json_object('type' value 'csv', 'skipheaders' value '1'),   
      field_list => 'REPORT_DATE DATE''mm/dd/yy'',                   
                     REPORT_DATE_COPY DATE ''yyyy-mm-dd'',
                     ACTUAL_MEAN_TEMP,                 
                     ACTUAL_MIN_TEMP,                 
                     ACTUAL_MAX_TEMP,                 
                     AVERAGE_MIN_TEMP,                    
                     AVERAGE_MAX_TEMP,     
                     AVERAGE_PRECIPITATION',   
      column_list => 'REPORT_DATE DATE,   
                     REPORT_DATE_COPY DATE,
                     ACTUAL_MEAN_TEMP NUMBER,  
                     ACTUAL_MIN_TEMP NUMBER,  
                     ACTUAL_MAX_TEMP NUMBER,  
                     AVERAGE_MIN_TEMP NUMBER,   
                     AVERAGE_MAX_TEMP NUMBER,                  
                     AVERAGE_PRECIPITATION NUMBER');
   END;
/ 

SELECT * FROM WEATHER_REPORT_DOUBLE_DATE where         
   actual_mean_temp > 69 and actual_mean_temp < 74

Para obter uma descrição das configurações suportadas, consulte Sobre a consulta de tabelas do Apache Iceberg.

Sintaxe

DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
    table_name       IN VARCHAR2,
    credential_name  IN VARCHAR2 DEFAULT NULL,
    file_uri_list    IN CLOB,
    column_list      IN CLOB DEFAULT NULL,
    field_list       IN CLOB DEFAULT NULL,
    format           IN CLOB DEFAULT NULL
);

Parâmetros

Exemplo de tabelas AWS Iceberg usando um catálogo AWS Glue

O parâmetro format ao criar tabelas em uma tabela do AWS Iceberg usando um AWS Glue Catalog é o seguinte:

format => json_object('access_protocol' value
       json_object('protocol_type' value 'iceberg',
                   'protocol_config' value
                    json_object('iceberg_catalog_type' value 'aws_glue',
                                'iceberg_glue_region'  value 'glue region',
                                'iceberg_table_path'   value 'database_name.table_name'))); 

Exemplo de tabela AWS Iceberg usando um URI de arquivo de metadados

format => json_object('access_protocol' value
       json_object('protocol_type' value 'iceberg')

Exemplo de tabela Iceberg do OCI usando o catálogo HadoopCatalog

format => json_object('access_protocol' value
       json_object('protocol_type'   value 'iceberg',
                   'protocol_config' value
                   json_object('iceberg_catalog_type'  value 'hadoop',
                               'iceberg_warehouse'     value '<OCI folder URI>',
                               'iceberg_table_path'    value 'database_name.table_name')));

Exemplo de tabela Iceberg do OCI usando o URI do arquivo de metadados

format => json_object('access_protocol' value
       json_object('protocol_type' value 'iceberg')

Sintaxe

DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
    table_name       IN VARCHAR2,
    credential_name  IN VARCHAR2 DEFAULT NULL,
    file_uri_list    IN CLOB,
    column_list      IN CLOB,
    field_list       IN CLOB DEFAULT,
    format           IN CLOB DEFAULT);

Parâmetros

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.parquet'

Exemplos de ORC

Exemplos de Avro

Exemplos de Parquet

Mapeamento de Nome de Coluna Avro, ORC ou Parquet para Nomes de Coluna Oracle

Consulte DBMS_CLOUD Mapeamento de Nome de Coluna Avro, ORC e Parquet para Oracle do Pacote para obter informações sobre mapeamento de nome de coluna e uso de conversão de nome de coluna no Oracle SQL.

O procedimento CREATE_EXTERNAL_TEXT_INDEX cria índice de texto nos arquivos do serviço Object Storage especificados no local location_uri. O índice é atualizado em intervalos regulares, para quaisquer novas adições ou exclusões feitas com arquivos no URI do local.

Sintaxe

DBMS_CLOUD.CREATE_EXTERNAL_TEXT_INDEX (
      credential_name  IN  VARCHAR2 DEFAULT NULL,
      location_uri     IN  VARCHAR2,
      index_name       IN  VARCHAR2,
      format           IN  CLOB     DEFAULT NULL
);

Parâmetros

Exemplo

BEGIN 
DBMS_CLOUD.CREATE_EXTERNAL_TEXT_INDEX (
        credential_name => 'DEFAULT_CREDENTIAL',
        location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/ts_data/'
        index_name      => 'EMP',
        format          => JSON_OBJECT ('refresh_rate' value 10)
);
END;
/

Sintaxe

DBMS_CLOUD.CREATE_HYBRID_PART_TABLE (
    table_name           IN VARCHAR2,
    credential_name      IN VARCHAR2,
    partitioning_clause  IN CLOB,
    column_list          IN CLOB,
    field_list           IN CLOB DEFAULT,
    format               IN CLOB DEFAULT);

Parâmetros

partitioning_clause => 'partition by range (col1)
                                (partition p1 values less than (1000) external location
				    ( ''https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.txt''),….

Observações de Uso

• O procedimento DBMS_CLOUD.CREATE_HYBRID_PART_TABLE suporta arquivos particionados externos nos serviços de armazenamento de objetos na nuvem suportados, que incluem:

  • Oracle Cloud Infrastructure Object Storage

  • Azure Blob Storage ou Azure Data Lake Storage

  • Amazon S3

  • Compatível com Amazon S3, incluindo: Oracle Cloud Infrastructure Object Storage, Google Cloud Storage e Wasabi Hot Cloud Storage.

  • GitHub Repositório

  A credencial é uma propriedade em nível de tabela; portanto, os arquivos externos devem estar no mesmo armazenamento de objetos.

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

• O procedimento DBMS_CLOUD.CREATE_HYBRID_PART_TABLE suporta arquivos particionados híbridos em diretórios, seja em um sistema de arquivos local ou em um sistema de arquivos de rede.

• As tabelas particionadas externas criadas com DBMS_CLOUD.CREATE_HYBRID_PART_TABLE incluem duas colunas invisíveis file$path e file$name. Essas colunas ajudam a identificar de qual arquivo um registro está vindo.

  • file$path: Especifica o texto do caminho do arquivo até o início do nome do objeto.

  • file$name: Especifica o nome do objeto, incluindo todo o texto que segue o nome do bucket.

Exemplos

BEGIN  
   DBMS_CLOUD.CREATE_HYBRID_PART_TABLE(
      table_name =>'HPT1',  
      credential_name =>'OBJ_STORE_CRED',  
      format => json_object('delimiter' value ',', 'recorddelimiter' value 'newline', 'characterset' value 'us7ascii'),  
      column_list => 'col1 number, col2 number, col3 number',
      partitioning_clause => 'partition by range (col1)
                                (partition p1 values less than (1000) external location
                                    ( ''&base_URL/file_11.txt'')
                                 ,
                                 partition p2 values less than (2000) external location
                                    ( ''&base_URL/file_21.txt'')
                                 ,
                                 partition p3 values less than (3000)
                                 )'
     );
   END;
/ 


BEGIN
   DBMS_CLOUD.CREATE_HYBRID_PART_TABLE(
    table_name  => 'HPT1',
    format      => json_object('delimiter'value ',', 'recorddelimiter'value 'newline'),
    column_list => 'NAME VARCHAR2(30), GENDER VARCHAR2(10), BALANCE number',
    partitioning_clause => 'partition by range (B  2  ALANCE)
               (partition p1 values less than (1000) external DEFAULT DIRECTORY DATA_PUMP_DIR LOCATION (''Scott_male_1000.csv''),
                partition p2 values less than (2000) external DEFAULT DIRECTORY DATA_PUMP_DIR LOCATION (''Mary_female_3000.csv''),
                partition p3 values less than (3000))' );
END;
/

Sintaxe

DBMS_CLOUD.DELETE_ALL_OPERATIONS (
	type      IN VARCHAR DEFAULT NULL);

Parâmetros

Observações de Uso

• Este procedimento não exclui operações em execução no momento (operações com status "Em Execução").

• Este procedimento exclui todas as tabelas de log e arquivos de log associados às operações.

Sintaxe

 DBMS_CLOUD.DELETE_FILE ( 
       directory_name     IN VARCHAR2,
       file_name          IN VARCHAR2,
       force              IN BOOLEAN DEFAULT FALSE); 

Parâmetros

GRANT WRITE ON DIRECTORY data_pump_dir TO adb_user;

Exemplo

BEGIN
   DBMS_CLOUD.DELETE_FILE(
      directory_name =>  'DATA_PUMP_DIR',
      file_name => 'exp1.dmp' );
   END;
/ 

Sintaxe

DBMS_CLOUD.DELETE_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       force                IN BOOLEAN DEFAULT FALSE);

Parâmetros

Exemplo

BEGIN
   DBMS_CLOUD.DELETE_OBJECT(
       credential_name => 'DEF_CRED_NAME',
       object_uri => 'https://objectstorage.us-ashburn-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.dmp' );
   END;
/ 

Sintaxe

DBMS_CLOUD.DELETE_OPERATION (
	id      IN NUMBER);

Parâmetros

Nota de Uso

• Este procedimento exclui todas as tabelas de log e arquivos de log associados ao ID de operação especificado na entrada.

Exemplo

SELECT id FROM user_load_operations WHERE type LIKE '%BAD%';
EXEC DBMS_CLOUD.DELETE_OPERATION(id);

O procedimento DROP_EXTERNAL_TEXT_INDEX elimina o índice especificado criado com o procedimento CREATE_EXTERNAL_TEXT_INDEX.

Sintaxe

DBMS_CLOUD.DROP_EXTERNAL_TEXT_INDEX (
      index_name       IN  VARCHAR2,
);

Parâmetros

Exemplo

BEGIN 
DBMS_CLOUD.DROP_EXTERNAL_TEXT_INDEX (
        index_name => 'EMP',
);
END;
/

Sintaxe

DBMS_CLOUD.EXPORT_DATA (
      credential_name   IN VARCHAR2 DEFAULT NULL,
      file_uri_list     IN CLOB,
      format            IN CLOB,
      query             IN CLOB);

DBMS_CLOUD.EXPORT_DATA (
      credential_name   IN VARCHAR2 DEFAULT NULL,
      file_uri_list     IN CLOB DEFAULT NULL,
      format            IN CLOB DEFAULT NULL,
      query             IN CLOB DEFAULT NULL,
      operation_id      OUT NOCOPY NUMBER);

Parâmetros

Observações de Uso:

• O valor do parâmetro query fornecido pode ser uma consulta avançada, se necessário, como uma consulta que inclui junções ou subconsultas.

• Dependendo do parâmetro de formato especificado, o DBMS_CLOUD.EXPORT_DATA gera os resultados da consulta especificada no Armazenamento de Objetos na Nuvem ou em um local de diretório em um destes formatos:

  • Arquivos CSV, JSON, Parquet ou XML.

    Consulte Exportar Dados para o Armazenamento de Objetos como Texto e Exportar Dados para um Diretório para obter mais informações sobre o uso de DBMS_CLOUD.EXPORT_DATA com arquivos de saída CSV, JSON, Parquet ou XML.

  • Usando o driver de acesso ORACLE_DATAPUMP para gravar dados em um arquivo de dump.

• Para saída CSV, JSON ou XML, por padrão, quando um arquivo gerado contém 10 MB de dados, um novo arquivo de saída é criado. No entanto, se você tiver menos de 10 MB de dados de resultado, poderá ter vários arquivos de saída, dependendo do serviço de banco de dados e do número de ECPUs (OCPUs, se o seu banco de dados usar OCPUs) da instância do Autonomous Database.

  Consulte Nomenclatura de Arquivo para Saída de Texto (CSV, JSON, Parquet ou XML) para obter mais informações.

  O tamanho do arquivo de saída padrão é 10 MB para CSV, JSON ou XML. Você pode alterar esse valor com a opção maxfilesize do parâmetro format. Consulte DBMS_CLOUD Package Format Options para EXPORT_DATA para obter mais informações.

• Para saída Parquet, cada arquivo gerado tem menos de 128 MB e vários arquivos de saída podem ser gerados. No entanto, se você tiver menos de 128 MB de dados de resultado, poderá ter vários arquivos de saída, dependendo do serviço de banco de dados e do número de ECPUs (OCPUs, se o seu banco de dados usar OCPUs) da instância do Autonomous Database.

  Consulte Nomenclatura de Arquivo para Saída de Texto (CSV, JSON, Parquet ou XML) para obter mais informações.

Observações de Uso para a Saída ORACLE_DATAPUMP (DBMS_CLOUD.EXPORT_DATA com o parâmetro format type opção datapump):

• EXPORT_DATA usa DATA_PUMP_DIR como o diretório de log padrão. Portanto, o privilégio de gravação em DATA_PUMP_DIR é necessário ao usar a saída ORACLE_DATAPUMP.

• A exportação do Autonomous Database usando DBMS_CLOUD.EXPORT_DATA com o parâmetro format, a opção type, datapump só suporta os armazenamentos de objetos Oracle Cloud Infrastructure Object Storage, Oracle Cloud Infrastructure Object Storage Classic ou a saída de diretório.

• Quando você especifica DBMS_CLOUD.EXPORT_DATA com a opção type do parâmetro format datapump, o valor do parâmetro credential_name não pode ser um controlador de recursos do OCI.

• O Oracle Data Pump divide cada parte do arquivo de dump em chunks menores para a obtenção de uploads mais rápidos. A console do Oracle Cloud Infrastructure Object Storage mostra vários arquivos para cada parte do arquivo de dump que você exporta. O tamanho dos arquivos de dump reais será exibido como 0 (zero) e seus chunks de arquivos relacionados como 10 MB ou menos. Por exemplo:

  exp01.dmp
  exp01.dmp_aaaaaa
  exp02.dmp
  exp02.dmp_aaaaaa

  O download do arquivo de dump de zero byte na console do Oracle Cloud Infrastructure ou usando a CLI do Oracle Cloud Infrastructure não fornecerá a você os arquivos de dump completos. Para fazer download dos arquivos de dump completos do Object Store, use uma ferramenta que suporte Swift, como curl, e forneça seu log-in de usuário e token de autenticação Swift.

  curl -O -v -X GET -u 'user1@example.com:auth_token' \
     https://swiftobjectstorage.us-ashburn-1.oraclecloud.com/v1/namespace-string/bucketname/exp01.dmp

  Se você importar um arquivo com os procedimentos DBMS_CLOUD que suportam o parâmetro format type com o valor 'datapump', só será necessário fornecer o nome do arquivo principal. Os procedimentos que suportam o tipo de formato 'datapump' descobrem e fazem download automaticamente dos chunks.

  Quando você usa DBMS_CLOUD.DELETE_OBJECT, o procedimento descobre e exclui automaticamente os chunks quando o procedimento exclui o arquivo principal.

• O procedimento DBMS_CLOUD.EXPORT_DATA cria o(s) arquivo(s) de dump com base nos valores file_uri_list especificados por você, da seguinte maneira:

  • Conforme mais arquivos são necessários, o procedimento cria arquivos adicionais usando file_uri_list.

  • O procedimento não substitui arquivos. Se um arquivo de dump no file_uri_list existir, o DBMS_CLOUD.EXPORT_DATA reportará um erro.

  • O DBMS_CLOUD.EXPORT_DATA não cria buckets.

• O número de arquivos de dump que o DBMS_CLOUD.EXPORT_DATA gera é determinado quando o procedimento é executado. O número de arquivos de dump gerados depende do número de nomes de arquivos fornecidos no parâmetro file_uri_list, bem como do número de OCPUs do Autonomous Database disponíveis para a instância, do nível de serviço e do tamanho dos dados.

  Por exemplo, se você usar uma instância do Autonomous Database com 1 OCPU ou o serviço low, um único arquivo de dump será exportado sem paralelismo, mesmo que você forneça vários nomes de arquivo. Se você usar uma instância do Autonomous Database com 4 OCPUs com o serviço medium ou high, os jobs poderão ser executados em paralelo e vários arquivos de dump serão exportados se você fornecer vários nomes de arquivo.

• Os arquivos de dump criados com DBMS_CLOUD.EXPORT_DATA não podem ser importados usando o impdp do Oracle Data Pump. Dependendo do banco de dados, você pode usar esses arquivos da seguinte forma:

  • Em um Autonomous Database, você pode usar os arquivos de dump com os procedimentos DBMS_CLOUD que suportam o parâmetro format type com o valor 'datapump'. Você pode importar os arquivos de dump usando DBMS_CLOUD.COPY_DATA ou pode chamar DBMS_CLOUD.CREATE_EXTERNAL_TABLE para criar uma tabela externa.

  • Em qualquer outro Oracle Database, como o Oracle Database 19c on-premises, você pode importar os arquivos de dump criados com o procedimento DBMS_CLOUD.EXPORT_DATA usando o driver de acesso ORACLE_DATAPUMP. Consulte Unloading and Loading Data with the ORACLE_DATAPUMP Access Driver para obter mais informações.

• O valor do parâmetro query fornecido pode ser uma consulta avançada, se necessário, como uma consulta que inclui junções ou subconsultas.

Observações de Uso de DBMS_CLOUD.EXPORT_DATA com Saída para um Diretório

• O diretório fornecido deve existir e você deve estar conectado como o usuário ADMIN ou ter acesso WRITE ao diretório.

• O DBMS_CLOUD.EXPORT_DATA não cria diretórios.

• O procedimento não substitui arquivos. Por exemplo, se um arquivo de dump no file_uri_list existir, o DBMS_CLOUD.EXPORT_DATA reportará um erro como:

  ORA-31641: unable to create dump file  "/u02/exports/123.dmp"
  ORA-27038: created file already exists

Exemplos

O exemplo a seguir mostra DBMS_CLOUD.EXPORT_DATA com o parâmetro de formato type com o valor datapump:

BEGIN  
   DBMS_CLOUD.EXPORT_DATA(
      credential_name =>'OBJ_STORE_CRED',
      file_uri_list =>'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.dmp',
      format => json_object('type' value 'datapump', 'compression' value 'basic', 'version' value 'latest'),
      query => 'SELECT warehouse_id, quantity FROM inventories'
     );
   END;
/  

Neste exemplo, namespace-string corresponde ao namespace do armazenamento de objetos do Oracle Cloud Infrastructure e bucketname corresponde ao nome do bucket. Consulte Noções Básicas de Namespaces do serviço Object Storage para obter mais informações.

O exemplo a seguir mostra DBMS_CLOUD.EXPORT_DATA com o parâmetro de formato type com o valor json:

BEGIN  
   DBMS_CLOUD.EXPORT_DATA(
      credential_name => 'OBJ_STORE_CRED',
      file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.json', 
      query           => 'SELECT * FROM DEPT',
      format          => JSON_OBJECT('type' value 'json', 'compression' value 'gzip'));
     );
   END;
/  

O exemplo a seguir mostra DBMS_CLOUD.EXPORT_DATA com o parâmetro de formato type com o valor xml:

BEGIN  
   DBMS_CLOUD.EXPORT_DATA(
      credential_name => 'OBJ_STORE_CRED',
      file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.xml', 
      query           => 'SELECT * FROM DEPT',
      format          => JSON_OBJECT('type' value 'xml', 'compression' value 'gzip'));
     );
   END;
/

O exemplo a seguir mostra DBMS_CLOUD.EXPORT_DATA com o parâmetro de formato type com o valor csv:

BEGIN  
   DBMS_CLOUD.EXPORT_DATA(
      credential_name => 'OBJ_STORE_CRED',
      file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp.csv', 
      query           => 'SELECT * FROM DEPT',
      format          => JSON_OBJECT('type' value 'csv', 'delimiter' value '|', 'compression' value 'gzip', 'header' value true, 'encryption' value ('user_defined_function' value 'ADMIN.decryption_callback')));
     );
   END;
/  

O exemplo a seguir mostra DBMS_CLOUD.EXPORT_DATA exportando dados para um local de diretório com o parâmetro type com o valor datapump:

BEGIN
 DBMS_CLOUD.EXPORT_DATA(
    file_uri_list => 'export_dir:sales.dmp',
    format        => json_object('type' value 'datapump'),
    query         => 'SELECT * FROM sales'
 );
END;
/

Sintaxe

DBMS_CLOUD.GET_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       directory_name       IN VARCHAR2,
       file_name            IN VARCHAR2 DEFAULT  NULL,
       startoffset          IN NUMBER DEFAULT  0,
       endoffset            IN NUMBER DEFAULT  0,
       compression          IN VARCHAR2 DEFAULT  NULL);


DBMS_CLOUD.GET_OBJECT(
       credential_name      IN VARCHAR2 DEFAULT NULL,
       object_uri           IN VARCHAR2,
       startoffset          IN NUMBER DEFAULT  0,
       endoffset            IN NUMBER DEFAULT  0,
       compression          IN VARCHAR2 DEFAULT  NULL)
RETURN BLOB;

Parâmetros

^{Nota de rodapé 1}

GRANT WRITE ON DIRECTORY data_pump_dir TO adb_user;

Retornar Valores

O form de função é lido no Armazenamento de Objetos e DBMS_CLOUD.GET_OBJECT retorna um BLOB.

Exemplos

BEGIN 
   DBMS_CLOUD.GET_OBJECT(
     credential_name => 'OBJ_STORE_CRED',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/file.txt',
     directory_name => 'DATA_PUMP_DIR'); 
END;
/

Para ler dados de caracteres de um arquivo no Armazenamento de Objetos:

SELECT to_clob(
     DBMS_CLOUD.GET_OBJECT(
       credential_name => 'OBJ_STORE_CRED',
       object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/file.txt'))
FROM DUAL;

Para adicionar uma imagem armazenada no Armazenamento de Objetos em um BLOB no banco de dados:

DECLARE
   l_blob BLOB := NULL;
BEGIN
   l_blob := DBMS_CLOUD.GET_OBJECT(
     credential_name => 'OBJ_STORE_CRED',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/MyImage.gif' );
END;
/

Neste exemplo, namespace-string corresponde ao namespace do armazenamento de objetos do Oracle Cloud Infrastructure e bucketname corresponde ao nome do bucket. Consulte Noções Básicas de Namespaces do serviço Object Storage para obter mais informações.

Sintaxe

DBMS_CLOUD.LIST_FILES (
	directory_name      IN VARCHAR2)
       RETURN TABLE;

Parâmetros

Observações de Uso

• Para executar DBMS_CLOUD.LIST_FILES com um usuário diferente de ADMIN, conceda privilégios de leitura no diretório a esse usuário. Por exemplo, execute o seguinte comando como ADMIN para conceder privilégios de leitura a adb_user:

  GRANT READ ON DIRECTORY data_pump_dir TO adb_user;

• Essa é uma função de tabela em pipeline com tipo de retorno como DBMS_CLOUD_TYPES.list_object_ret_t.

• O DBMS_CLOUD.LIST_FILES não obtém o valor da soma de verificação e retorna NULL para esse campo.

Exemplo

Essa é uma função em pipeline que retorna uma linha para cada arquivo. Por exemplo, use a consulta a seguir para usar esta função:

SELECT * FROM DBMS_CLOUD.LIST_FILES('DATA_PUMP_DIR');

OBJECT_NAME       BYTES   CHECKSUM      CREATED              LAST_MODIFIED
------------ ---------- ----------    ---------------------  ---------------------
cwallet.sso        2965               2018-12-12T18:10:47Z   2019-11-23T06:36:54Z

Sintaxe

DBMS_CLOUD.LIST_OBJECTS (
       credential_name      IN VARCHAR2,
       location_uri         IN VARCHAR2)
   RETURN TABLE;

Parâmetros

Observações de Uso

• Dependendo dos recursos do armazenamento de objetos, o DBMS_CLOUD.LIST_OBJECTS não retorna valores para determinados atributos e o valor de retorno do campo é NULL nesse caso.

  Todos os Armazenamentos de Objetos suportados retornam valores para os campos OBJECT_NAME, BYTES e CHECKSUM.

  A tabela a seguir mostra o suporte para os campos CREATED e LAST_MODIFIED pelo Armazenamento de Objetos:

  Armazenamento de Objetos	CREATED	LAST_MODIFIED
  Nativo do Oracle Cloud Infrastructure	Retorna o timestamp	Retorna o timestamp
  Swift da Oracle Cloud Infrastructure	Retorna NULL	Retorna o timestamp
  Oracle Cloud Infrastructure Classic	Retorna NULL	Retorna o timestamp
  Amazon S3	Retorna NULL	Retorna o timestamp
  Compatível com Amazon S3	Retorna NULL	Retorna o timestamp
  Azure	Retorna o timestamp	Retorna o timestamp
  GitHub Repositório

• O valor da soma de verificação é a soma de verificação MD5. Esse é um número sextavado de 32 caracteres que é calculado no conteúdo do objeto. Espera-se que ele tenha um valor de soma de verificação diferente se a credencial OCI$RESOURCE_PRINCIPAL for usada.

• Essa é uma função de tabela em pipeline com tipo de retorno como DBMS_CLOUD_TYPES.list_object_ret_t.

Exemplo

Essa é uma função em pipeline que retorna uma linha para cada objeto. Por exemplo, use a consulta a seguir para usar esta função:

SELECT * FROM DBMS_CLOUD.LIST_OBJECTS('OBJ_STORE_CRED', 
    'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/');


OBJECT_NAME   BYTES              CHECKSUM                       CREATED         LAST_MODIFIED
------------ ---------- -------------------------------- --------------------- --------------------
cwallet.sso   2965      2339a2731ba24a837b26d344d643dc07 2019-11-23T06:36:54Z          

Neste exemplo, namespace-string corresponde ao namespace do armazenamento de objetos do Oracle Cloud Infrastructure e bucketname corresponde ao nome do bucket. Consulte Noções Básicas de Namespaces do serviço Object Storage para obter mais informações.

O bucket ou pasta de origem e destino pode estar no mesmo provedor de armazenamento do Cloud Object ou em outro provedor.

Quando a origem e o destino estão em Armazenamentos de Objetos distintos ou têm contas diferentes com o mesmo provedor de nuvem, você pode fornecer nomes de credenciais separados para os locais de origem e destino.

Por padrão, o nome da credencial de origem também é usado pelo local de destino quando o nome da credencial de destino não é fornecido.

Sintaxe

DBMS_CLOUD.MOVE_OBJECT (
    source_credential_name  IN  VARCHAR2 DEFAULT NULL,
    source_object_uri       IN  VARCHAR2,
    target_object_uri       IN  VARCHAR2,
    target_credential_name  IN  VARCHAR2 DEFAULT NULL
);

Parâmetros

Exemplo

BEGIN 
DBMS_CLOUD.MOVE_OBJECT (
    source_credential_name => 'OCI_CRED',
    source_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/bgfile.csv',
    target_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/myfile.csv'
);
END;
/

Sintaxe

DBMS_CLOUD.PUT_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       directory_name       IN VARCHAR2,
       file_name            IN VARCHAR2
       compression          IN VARCHAR2 DEFAULT  NULL);


DBMS_CLOUD.PUT_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       contents             IN BLOB
       compression          IN VARCHAR2 DEFAULT  NULL);

Parâmetros

^{Nota de rodapé 2}

GRANT READ ON DIRECTORY data_pump_dir TO adb_user;

Exemplo

Para tratar dados BLOB após o processamento no banco de dados e, em seguida, armazenar os dados diretamente em um arquivo no armazenamento de objetos:

DECLARE
      my_blob_data BLOB;
BEGIN 
 /* Some processing producing BLOB data and populating my_blob_data */
DBMS_CLOUD.PUT_OBJECT(
     credential_name => 'OBJ_STORE_CRED',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/my_new_file',
     contents => my_blob_data)); 
END;
/

Observações de Uso

Dependendo do Cloud Object Storage, o tamanho do objeto transferido é limitado da seguinte forma:

O armazenamento de objetos do Oracle Cloud Infrastructure não permite gravar arquivos em um bucket público sem fornecer credenciais (o Oracle Cloud Infrastructure permite que os usuários façam download de objetos de buckets públicos). Portanto, você deve fornecer um nome de credencial com credenciais válidas para armazenar um objeto em um bucket público do Oracle Cloud Infrastructure usando PUT_OBJECT.

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

Sintaxe

DBMS_CLOUD.SYNC_EXTERNAL_PART_TABLE (
	table_name        IN VARCHAR2,
	schema_name       IN VARCHAR2 DEFAULT,
	update_columns    IN BOOLEAN DEFAULT);

Parâmetros

Sintaxe

DBMS_CLOUD.VALIDATE_EXTERNAL_PART_TABLE (
       table_name                 IN VARCHAR2,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);


DBMS_CLOUD.VALIDATE_EXTERNAL_PART_TABLE (
       table_name                 IN VARCHAR2,
       operation_id               OUT NUMBER,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);

Parâmetros

Sintaxe

DBMS_CLOUD.VALIDATE_EXTERNAL_TABLE (
	table_name      IN VARCHAR2,
	schema_name     IN VARCHAR2 DEFAULT,		
	rowcount        IN NUMBER DEFAULT,
	stop_on_error   IN BOOLEAN DEFAULT);


DBMS_CLOUD.VALIDATE_EXTERNAL_TABLE(
	table_name      IN VARCHAR2,
	operation_id    OUT NOCOPY NUMBER,
	schema_name     IN VARCHAR2 DEFAULT NULL,		
	rowcount        IN NUMBER DEFAULT 0,
	stop_on_error   IN BOOLEAN DEFAULT TRUE);

Parâmetros

Observações de Uso

• O DBMS_CLOUD.VALIDATE_EXTERNAL_TABLE funciona com tabelas externas particionadas e tabelas híbridas particionadas. Isso potencialmente lê dados de todas as partições externas até que rowcount seja atingido ou stop_on_error seja aplicado. Você não tem controle sobre qual partição, ou partes de uma partição, é lida em que ordem.

Sintaxe

DBMS_CLOUD.VALIDATE_HYBRID_PART_TABLE (
       table_name                 IN VARCHAR2,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);


DBMS_CLOUD.VALIDATE_HYBRID_PART_TABLE (
       table_name                 IN VARCHAR2,
       operation_id               OUT NUMBER,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);

Parâmetros

Você pode filtrar a lista de arquivos a serem excluídos usando um padrão de expressão regular compatível com o operador REGEXP_LIKE.

O bucket ou pasta de origem e destino pode estar no mesmo provedor de armazenamento do Cloud Object ou em outro provedor.

Quando a origem e o destino estão em Armazenamentos de Objetos distintos ou têm contas diferentes com o mesmo provedor de nuvem, você pode fornecer nomes de credenciais separados para os locais de origem e destino.

Por padrão, o nome da credencial de origem também é usado pelo local de destino.

Sintaxe

DBMS_CLOUD.BULK_COPY (
      source_credential_name  IN  VARCHAR2 DEFAULT NULL,
      source_location_uri     IN  VARCHAR2,
      target_location_uri     IN  VARCHAR2,
      target_credential_name  IN  VARCHAR2 DEFAULT NULL,
      regex_filter            IN  VARCHAR2 DEFAULT NULL,
      format                  IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_COPY (
      source_credential_name  IN  VARCHAR2 DEFAULT NULL,
      source_location_uri     IN  VARCHAR2,
      target_location_uri     IN  VARCHAR2,
      target_credential_name  IN  VARCHAR2 DEFAULT NULL,
      regex_filter            IN  VARCHAR2 DEFAULT NULL,
      format                  IN  CLOB     DEFAULT NULL,
      operation_id            OUT NUMBER
);

Parâmetros

Observações de Uso

• Um erro é retornado quando o URI de origem e destino aponta para o mesmo bucket ou pasta do Object Storage.

Exemplo

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

Sintaxe

 DBMS_CLOUD.BULK_DELETE(
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_DELETE (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL,
     operation_id     OUT NUMBER
);

Parâmetros

Exemplo

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

Sintaxe

DBMS_CLOUD.BULK_DOWNLOAD (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     directory_name   IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_DOWNLOAD (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     directory_name   IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL,
     operation_id     OUT NUMBER
);

Parâmetros

Exemplo

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

Você pode filtrar a lista de arquivos a serem excluídos usando um padrão de expressão regular compatível com o operador REGEXP_LIKE.

O bucket ou pasta de origem e destino pode estar no mesmo provedor de armazenamento do Cloud Object ou em outro provedor.

Quando a origem e o destino estão em Armazenamentos de Objetos distintos ou têm contas diferentes com o mesmo provedor de nuvem, você pode fornecer nomes de credenciais separados para os locais de origem e destino.

Por padrão, o nome da credencial de origem também é usado pelo local de destino quando o nome da credencial de destino não é fornecido.

A primeira etapa na movimentação de arquivos é copiá-los para o local de destino e, em seguida, excluir os arquivos de origem, uma vez copiados com sucesso.

O objeto será renomeado em vez de movido se o Armazenamento de Objetos permitir a renomeação de operações entre os locais de origem e de destino.

Sintaxe

DBMS_CLOUD.BULK_MOVE (
      source_credential_name  IN  VARCHAR2 DEFAULT NULL,
      source_location_uri     IN  VARCHAR2,
      target_location_uri     IN  VARCHAR2,
      target_credential_name  IN  VARCHAR2 DEFAULT NULL,
      regex_filter            IN  VARCHAR2 DEFAULT NULL,
      format                  IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_MOVE (
      source_credential_name  IN  VARCHAR2 DEFAULT NULL,
      source_location_uri     IN  VARCHAR2,
      target_location_uri     IN  VARCHAR2,
      target_credential_name  IN  VARCHAR2 DEFAULT NULL,
      regex_filter            IN  VARCHAR2 DEFAULT NULL,
      format                  IN  CLOB     DEFAULT NULL,
      operation_id            OUT NUMBER
);

Parâmetros

Exemplo

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

Sintaxe

DBMS_CLOUD.BULK_UPLOAD (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     directory_name   IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_UPLOAD (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     directory_name   IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL,
     operation_id     OUT NUMBER
);

Parâmetros

Exemplo

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

DBMS_CLOUD supports GET, PUT, POST, HEAD and DELETE HTTP methods. The REST API method to be used for an HTTP request is typically documented in the Cloud REST API documentation.

Por padrão, as chamadas de API REST DBMS_CLOUD não salvam os resultados da sessão. Nesse caso, você usa a função DBMS_CLOUD.SEND_REQUEST para retornar resultados.

Quando você usa DBMS_CLOUD.SEND_REQUEST e define o parâmetro cache como TRUE, os resultados são salvos e você pode exibir os resultados passados na view SESSION_CLOUD_API_RESULTS. Salvar e consultar resultados históricos de solicitações da API REST DBMS_CLOUD podem ajudar você quando precisar trabalhar com resultados anteriores em seus aplicativos.

Por exemplo, para consultar resultados recentes da API REST DBMS_CLOUD, use a view SESSION_CLOUD_API_RESULTS:

SELECT timestamp FROM SESSION_CLOUD_API_RESULTS;

Quando você salva os resultados da API DBMS_CLOUD REST com DBMS_CLOUD.SEND_REQUEST, os dados salvos só ficam disponíveis na mesma sessão (conexão) Depois que a sessão for encerrada, os dados salvos não estarão mais disponíveis.

Use DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE e DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE para exibir e definir o tamanho do cache da API REST DBMS_CLOUD e para desativar o armazenamento no cache.

Sintaxe

DBMS_CLOUD.GET_RESPONSE_HEADERS(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN JSON_OBJECT_T;

Parâmetros

Exceções

Sintaxe

DBMS_CLOUD.GET_RESPONSE_RAW(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN BLOB;

Parâmetros

Exceções

Sintaxe

DBMS_CLOUD.GET_RESPONSE_STATUS_CODE(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN PLS_INTEGER;

Parâmetros

Exceções

Sintaxe

DBMS_CLOUD.GET_RESPONSE_TEXT(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN CLOB;

Parâmetros

Exceções

Sintaxe

DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE()
   RETURN NUMBER;

Sintaxe

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL)
   RETURN DBMS_CLOUD_TYPES.resp;

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL);

Parâmetros

Exceções

Observações sobre Uso

• Se você estiver usando o Oracle Cloud Infrastructure, use um valor de credencial baseado em Chave de Assinatura para o credential_name. Consulte CREATE_CREDENTIAL Procedimento para obter mais informações.

• Os parâmetros opcionais async_request_url, wait_for_states e timeout permitem tratar solicitações de longa execução. Usando essa forma assíncrona de send_request, a função aguarda o status de conclusão especificado em wait_for_states antes de retornar. Com esses parâmetros na solicitação de envio, você informa os estados esperados de retorno no parâmetro wait_for_states e usa o parâmetro async_request_url para especificar uma solicitação de serviço associada. A solicitação não é retornada imediatamente. Em vez disso, ela sonda async_request_url até que o estado de retorno seja um dos estados esperados ou até que timeout seja excedido (timeout é opcional). Se nenhum timeout for especificado, a solicitação aguardará até que ocorra um estado encontrado em wait_for_states.

Sintaxe

DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(
       cache_size          IN NUMBER);

Parâmetros

Exceções

Exemplo

EXEC DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(101);

Exemplo de Criação de Bucket

Mostra um exemplo usando DBMS_CLOUD.SEND_REQUEST com o método HTTP POST para criar um bucket de armazenamento de objetos chamado bucketname.

Consulte CreateBucket para obter detalhes sobre a API do Oracle Cloud Infrastructure Object Storage Service desse exemplo.

SET SERVEROUTPUT ON
DECLARE
  resp DBMS_CLOUD_TYPES.resp;
BEGIN
  -- Send request
  resp := DBMS_CLOUD.send_request(
            credential_name => 'OCI_KEY_CRED',
            uri => 'https://objectstorage.region.oraclecloud.com/n/namespace-string/b/',
            method => DBMS_CLOUD.METHOD_POST,
            body => UTL_RAW.cast_to_raw(
                        JSON_OBJECT('name' value 'bucketname',
                                    'compartmentId' value 'compartment_OCID'))
          );
 
  -- Response Body in TEXT format
  dbms_output.put_line('Body: ' || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_text(resp) || CHR(10));
  
  -- Response Headers in JSON format
  dbms_output.put_line('Headers: ' || CHR(10) || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_headers(resp).to_clob || CHR(10));
 
  -- Response Status Code
  dbms_output.put_line('Status Code: ' || CHR(10) || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_status_code(resp));
 
END;
/

Observações

• Neste exemplo, namespace-string corresponde ao namespace do armazenamento de objetos do Oracle Cloud Infrastructure e bucketname corresponde ao nome do bucket. Consulte Noções Básicas de Namespaces do serviço Object Storage para obter mais informações.

• Em que: region é uma região de ponto final. Consulte a referência de API do Armazenamento de Objetos em Referência de API e Pontos Finais para obter mais informações. Por exemplo, em que region é: us-phoenix-1.

Exemplo de Exclusão de Bucket

Mostra um exemplo usando DBMS_CLOUD.SEND_REQUEST com o método HTTP DELETE para excluir um bucket de armazenamento de objetos chamado bucketname.

Consulte DeleteBucket para obter detalhes sobre a API do Oracle Cloud Infrastructure Object Storage Service desse exemplo.

SET SERVEROUTPUT ON
DECLARE
  resp DBMS_CLOUD_TYPES.resp;
BEGIN
  -- Send request
  resp := DBMS_CLOUD.send_request(
            credential_name => 'OCI_KEY_CRED',
            uri => 'https://objectstorage.region.oraclecloud.com/n/namespace-string/b/bucketname',
            method => DBMS_CLOUD.METHOD_DELETE
          );
 
  -- Response Body in TEXT format
  dbms_output.put_line('Body: ' || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_text(resp) || CHR(10));
  
  -- Response Headers in JSON format
  dbms_output.put_line('Headers: ' || CHR(10) || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_headers(resp).to_clob || CHR(10));
 
  -- Response Status Code
  dbms_output.put_line('Status Code: ' || CHR(10) || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_status_code(resp));
 
END;
/

Observações

• Neste exemplo, namespace-string corresponde ao namespace do armazenamento de objetos do Oracle Cloud Infrastructure e bucketname corresponde ao nome do bucket. Consulte Noções Básicas de Namespaces do serviço Object Storage para obter mais informações.

• Em que: region é uma região de ponto final. Consulte a referência de API do Armazenamento de Objetos em Referência de API e Pontos Finais para obter mais informações. Por exemplo, em que region é: us-phoenix-1.

Exemplo de Lista de Compartimentos

Mostra um exemplo usando DBMS_CLOUD.SEND_REQUEST com o método HTTP GET para listar todos os compartimentos na tenancy (compartimento raiz). Esse exemplo mostra como especificar cabeçalhos de solicitação no DBMS_CLOUD.SEND_REQUEST.

Consulte ListCompartments para obter detalhes sobre a API do Oracle Cloud Infrastructure Identity and Access Management Service desse exemplo.

--
-- List compartments
--
DECLARE
  resp DBMS_CLOUD_TYPES.resp;
  root_compartment_ocid VARCHAR2(512) := '&1';
BEGIN
  -- Send request
  dbms_output.put_line('Send Request');
  resp := DBMS_CLOUD.send_request(
            credential_name => 'OCI_KEY_CRED',
            uri => 'https://identity.region.oraclecloud.com/20160918/compartments?compartmentId=' || root_compartment_ocid,
            method => DBMS_CLOUD.METHOD_GET,
            headers => JSON_OBJECT('opc-request-id' value 'list-compartments')
          );
  dbms_output.put_line('Body: ' || '------------' || CHR(10) || DBMS_CLOUD.get_response_text(resp) || CHR(10));
  dbms_output.put_line('Headers: ' || CHR(10) || '------------' || CHR(10) || DBMS_CLOUD.get_response_headers(resp).to_clob || CHR(10));
  dbms_output.put_line('Status Code: ' || CHR(10) || '------------' || CHR(10) || DBMS_CLOUD.get_response_status_code(resp));
  dbms_output.put_line(CHR(10));
END;
/

Em que: region é uma região de ponto final. Consulte a referência de API do IAM ( Identity and Access Management) em Referência de API e Pontos Finais para obter mais informações. Por exemplo, em que region é: uk-london-1.

Exemplo de Solicitação Assíncrona

Mostra um exemplo usando DBMS_CLOUD.SEND_REQUEST com o método HTTP POST para executar a operação de interrupção do Autonomous Database e aguardar o status. Esse exemplo mostra como usar DBMS_CLOUD.SEND_REQUEST com os parâmetros async_request_url, wait_for_states e timeout.

--
-- Sent Work Request Autonomous Database Stop Request with Wait for Status
DECLARE
    l_resp DBMS_CLOUD_TYPES.resp;
    l_resp_json JSON_OBJECT_T;
    l_key_shape JSON_OBJECT_T;
    l_body JSON_OBJECT_T;
    status_array DBMS_CLOUD_TYPES.wait_for_states_t;
BEGIN
  status_array := DBMS_CLOUD_TYPES.wait_for_states_t('SUCCEEDED');
  l_body := JSON_OBJECT_T('{}');
  l_body.put('autonomousDatabaseId', 'ocid');
-- Send request
  dbms_output.put_line(l_body.to_clob);
  dbms_output.put_line('Send Request');
  l_resp := DBMS_CLOUD.send_request(
                       credential_name    => 'NATIVE_CRED_OCI',
                       uri                => 'https://database.region.oraclecloud.com/20160918/autonomousDatabases/ocid/actions/stop',
                       method             => DBMS_CLOUD.METHOD_POST,
                       body               => UTL_RAW.cast_to_raw(l_body.to_clob),
                       async_request_url  => 'https://iaas.region.oraclecloud.com/20160918/workRequests',
                       wait_for_states    => status_array,
                       timeout            => 600
                  );
   dbms_output.put_line('resp body: '||DBMS_CLOUD.get_response_text(l_resp));
   dbms_output.put_line('resp headers: '||DBMS_CLOUD.get_response_headers(l_resp).to_clob);
END;
/

Em que: region é uma região de ponto final. Consulte a referência de API do IAM ( Identity and Access Management) em Referência de API e Pontos Finais para obter mais informações. Por exemplo, em que region é: uk-london-1.

O ocid é o identificador de recursos do Oracle Cloud Infrastructure. Consulte Identificadores de Recursos para obter mais informações.