DBMS_CLOUD Formatos de URI

Descreve o formato dos URIs de arquivo de origem em operações com DBMS_CLOUD. O formato depende do serviço de armazenamento de objetos que você está usando.

O DBMS_CLOUD garante comunicação segura e qualquer URI que você especificará deverá usar HTTPS, com https:// como prefixo do URI.

Formato de URI Nativo do Oracle Cloud Infrastructure Object Storage
Formato de URI Swift do Oracle Cloud Infrastructure Object Storage
Formato de URI do Oracle Cloud Infrastructure Object Storage Usando URL de Solicitação Pré-autenticada
Formato de URI Usando URL Público
Formato de URI do Oracle Cloud Infrastructure Object Storage Classic
Formato de URI do Amazon S3
Formato de URI do Azure Blob Storage ou Azure Data Lake Storage
Formato de URI Compatível com Amazon S3
O GitHub Formato de URL Bruto
DBMS_CLOUD suporta URLs Brutos GitHub para acessar dados de um Repositório GitHub.
Formatos de URI Gerenciados pelo Cliente Adicionais
Além do URIs pré-configurado e reconhecido com seus nomes de domínio totalmente qualificados (FQDNs), o DBMS_CLOUD não pode determinar o esquema de autenticação adequado para pontos finais gerenciados pelo cliente URIs. Nesses casos, o DBMS_CLOUD depende do esquema URI adequado para identificar o esquema de autenticação para o ponto final gerenciado pelo cliente.

Tópico principal: DBMS_CLOUD Pacote

Formato de URI Nativo do Oracle Cloud Infrastructure Object Storage

Se seus arquivos de origem residirem no Oracle Cloud Infrastructure Object Storage no realm comercial (OC1), é recomendável usar o formato de URI a seguir, que usa Pontos Finais Dedicados do Object Storage. Consulte Pontos Finais Dedicados do Serviço Object Storage para obter mais informações.

https://namespace-string.objectstorage.region.oci.customer-oci.com/n/namespace-string/b/bucketname/o/filename

Observação

Os URLs de ponto final dedicados do OCI Object Store só são suportados em realms comerciais (OC1).

Se seus arquivos de origem residirem no Oracle Cloud Infrastructure Object Storage e não estiverem no realm comercial (OC1), use o seguinte formato:

https://objectstorage.region.oraclecloud.com/n/namespace-string/b/bucket/o/filename

Por exemplo, no realm comercial (OC1), o URI Nativo do arquivo channels.txt no bucket bucketname no data center Phoenix é:

https://namespace.objectstorage.region.oci.customer-oci.com/n/namespace/b/bucketname/o/channels.txt

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.

Você pode encontrar o URI nos "Detalhes do Objeto" do Oracle Cloud Infrastructure Object Storage no menu de reticências no lado direito do Armazenamento de Objetos:

Abra a Console do Oracle Cloud Infrastructure clicando em ao lado do Oracle Cloud.
No menu de navegação esquerdo do Oracle Cloud Infrastructure, clique em Infraestrutura Principal. Em Serviço Object Storage, clique em Serviço Object Storage.
Em Escopo da Lista, selecione um Compartimento.
Na coluna Nome, selecione um bucket.
Na área Objetos, clique em Exibir Detalhes do Objeto.

Descrição da ilustração ad_oci_view_object_details.png
Na página Detalhes do Objeto, o campo Caminho do URL (URI) mostra o URI para acessar o objeto.

Observação

Os arquivos de origem precisam ser armazenados em um bucket da camada de Armazenamento de Objetos. O Autonomous Database não oferece suporte a buckets na camada de Serviço Archive Storage. Consulte Visão Geral do Serviço Object Storage para obter mais informações.

Tópico principal: DBMS_CLOUD Formatos de URI

Formato de URI Swift do Oracle Cloud Infrastructure Object Storage

https://namespace-string.swiftobjectstorage.region.oci.customer-oci.com/v1/namespace-string/bucket/filename

Observação

Os URLs de ponto final dedicados do OCI Object Store só são suportados nos realms comerciais (OC1).

Se seus arquivos de origem residirem no Oracle Cloud Infrastructure Object Storage e não estiverem no realm comercial (OC1), use o seguinte formato:

https://swiftobjectstorage.region.oraclecloud.com/v1/namespace-string/bucket/filename

Por exemplo, no realm comercial (OC1), o URI Swift para o arquivo channels.txt no bucket bucketname no data center Phoenix é:

https://namespace-string.swiftobjectstorage.us-phoenix-1.oci.customer-oci.com/v1/namespace-string/bucketname/channels.txt

Observação

Tópico principal: DBMS_CLOUD Formatos de URI

Formato de URI do Oracle Cloud Infrastructure Object Storage Usando URL de Solicitação Pré-autenticada

Se seus arquivos de origem residirem no Oracle Cloud Infrastructure Object Storage, você poderá usar URIs pré-autenticados do Oracle Cloud Infrastructure. Quando você cria uma solicitação pré-autenticada, um URL exclusivo é gerado. Você então poderá fornecer o URL exclusivo aos usuários da sua organização, parceiros ou terceiros para acessar o destino de recursos do Armazenamento de Objetos identificado na solicitação pré-autenticada.

Observação

Avalie com cuidado o requisito de negócios e as ramificações de segurança do acesso pré-autenticado. Ao criar o URL de solicitação pré-autenticada, observe a Expiração e o Tipo de acesso para garantir que eles sejam apropriados para seu uso.

Um URL de solicitação pré-autenticada fornece a todos os que têm o URL acesso aos destinos identificados na solicitação, desde que a solicitação esteja ativa. Além de considerar as necessidades operacionais do acesso pré-autenticado, é igualmente importante gerenciar sua distribuição.

https://namespace-string.objectstorage.region.oci.customer-oci.com/p/encrypted_string/n/namespace-string/b/bucket/o/filename

Observação

Os URLs de ponto final dedicados do OCI Object Store só são suportados nos realms comerciais (OC1).

Se seus arquivos de origem residirem no Oracle Cloud Infrastructure Object Storage e não estiverem no realm comercial (OC1), use o seguinte formato:

https://objectstorage.region.oraclecloud.com.com/p/encrypted_string/n/namespace-string/b/bucket/o/filename

Por exemplo, no realm comercial (OC1), um URI pré-autenticado de amostra para o arquivo channels.txt no bucket bucketname no data center Phoenix é:

https://namespace-string.objectstorage.us-phoenix-1.oci.customer-oci.com/p/2xN-uDtWJNsiD910UCYGue/n/namespace-string/b/bucketname/o/channels.txt

Você pode usar um URL pré-autenticado em qualquer procedimento DBMS_CLOUD que extraia um URL para acessar arquivos no armazenamento de objetos do Oracle Cloud Infrastructure, sem a necessidade de criar uma credencial. Você precisa especificar o parâmetro credential_name como NULL ou não fornecer um parâmetro credential_name.

Por exemplo:

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

Observação

Uma lista de URLs mistos é válida. Se a lista de URLs contiver URLs pré-autenticados e URLs que exijam autenticação, o DBMS_CLOUD usará o credential_name especificado para acessar os URLs que exigem autenticação e, para os URLs pré-autenticados, o credential_name especificado será ignorado.

Consulte Using Pre-Authenticated Requests para obter mais informações.

Tópico principal: DBMS_CLOUD Formatos de URI

Formato de URI Usando URL Público

Se seus arquivos de origem residirem em um Armazenamento de Objetos que forneça URLs públicos, você poderá usar URLs públicos com procedimentos DBMS_CLOUD. Público significa que o serviço Object Storage suporta acesso anônimo não autenticado aos arquivos do Armazenamento de Objetos. Consulte o seu serviço Cloud Object Storage para obter detalhes sobre como tornar um objeto público em um Armazenamento de Objetos suportado.

Observação

Avalie com cuidado o requisito de negócios e as ramificações de segurança do uso de URLs públicos. Ao usar URLs públicos, como o conteúdo do arquivo não é autenticado, verifique se isso é adequado para seu uso.

Você pode usar um URL público em qualquer procedimento DBMS_CLOUD que extraia um URL para acessar arquivos em seu armazenamento de objetos, sem a necessidade de criar uma credencial. Você precisa especificar o parâmetro credential_name como NULL ou não fornecer um parâmetro credential_name.

O seguinte exemplo usa DBMS_CLOUD.COPY_DATA sem um credential_name:

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

Observação

Uma lista de URLs mistos é válida. Se a lista de URLs contiver URLs públicos e URLs que exigem autenticação, o DBMS_CLOUD usará o credential_name especificado para acessar os URLs que exigem autenticação e, para os URLs públicos, o credential_name especificado será ignorado.

Consulte Buckets Públicos para obter informações sobre o uso de buckets públicos do Oracle Cloud Infrastructure.

Tópico principal: DBMS_CLOUD Formatos de URI

Formato de URI do Oracle Cloud Infrastructure Object Storage Classic

Se seus arquivos de origem residirem no Oracle Cloud Infrastructure Object Storage Classic, consulte a página REST para obter uma descrição do formato de URI para acessar seus arquivos: Sobre URLs REST para Recursos do Oracle Cloud Infrastructure Object Storage Classic.

Tópico principal: DBMS_CLOUD Formatos de URI

Formato de URI do Amazon S3

Se seus arquivos de origem residirem no Amazon S3, consulte o seguinte tópico para obter uma descrição do formato do URI para acessar seus arquivos: Acessando um bucket.

Por exemplo, a seguinte amostra se refere ao arquivo channels.txt no bucket adb na região us-west-2.

https://s3-us-west-2.amazonaws.com/adb/channels.txt

Você pode usar um URL pré-assinado em qualquer procedimento DBMS_CLOUD que extrai um URL para acessar arquivos no armazenamento de objetos do Amazon S3, sem a necessidade de criar uma credencial. Para usar um URL pré-assinado em qualquer procedimento DBMS_CLOUD, especifique o parâmetro credential_name como NULL ou não forneça um parâmetro credential_name.

Consulte Compartilhar um Objeto com Outros para obter mais informações.

Observação

O DBMS_CLOUD suporta a sintaxe de ponto final padrão do Amazon S3 para acessar buckets. O DBMS_CLOUD não suporta pontos finais legados do Amazon S3. Consulte Pontos Finais Legados para obter mais informações.

Tópico principal: DBMS_CLOUD Formatos de URI

Formato de URI do Azure Blob Storage ou Azure Data Lake Storage

Se seus arquivos de origem residirem no Azure Blob Storage ou no Azure Data Lake Storage, consulte o seguinte tópico para obter uma descrição do formato de URI para acessar seus arquivos: Sintaxe de URI de Recursos.

Por exemplo, o seguinte exemplo se refere ao arquivo channels.txt no contêiner adb na conta de armazenamento adb_user:

https://adb_user.blob.core.windows.net/adb/channels.txt

Observação

Você pode usar o URL de Assinaturas de Acesso Compartilhado (SAS) em qualquer procedimento DBMS_CLOUD que utilize um URL para acessar arquivos no Azure Blob Storage ou no Azure Data Lake Storage, sem a necessidade de criar uma credencial. Para usar um URL de Assinatura de Acesso Compartilhado (SAS), especifique o parâmetro credential_name como NULL ou não forneça um parâmetro credential_name.

Consulte Grant Limited Access to Azure Storage Resources Using Shared Access Signatures (SAS) para obter mais informações.

Tópico principal: DBMS_CLOUD Formatos de URI

Formato de URI compatível com Amazon S3

O DBMS_CLOUD suporta implementações do serviço de armazenamento de objetos que suportam URLs compatíveis com o Amazon S3, incluindo os seguintes serviços:

URL compatível com Amazon S3 do Oracle Cloud Infrastructure Object Storage
Google Cloud Storage com URL compatível com Amazon S3
Wasabi Hot Cloud Storage com URL compatível com Amazon S3

Observação

Para usar o DBMS_CLOUD com um armazenamento de objetos compatível com Amazon S3, forneça credenciais válidas. Consulte CREATE_CREDENTIAL Procedimento para obter mais informações.

Se seus arquivos de origem residirem em um serviço que suporte URIs compatíveis com o Amazon S3, use o seguinte formato de URI para acessar seus arquivos:

URL Compatível com S3 do Oracle Cloud Infrastructure Object Storage

Se seus arquivos de origem residirem no Oracle Cloud Infrastructure Object Storage no realm comercial (OC1), recomendamos que você use os formatos URL do objeto e URL do bucket listados abaixo para o realm comercial (OC1). Consulte Pontos Finais Dedicados do Serviço Object Storage para obter mais informações.

Observação

Os URLs de ponto final dedicados do OCI Object Store só são suportados nos realms comerciais (OC1).

Formatos de URL do Objeto
- Suportado somente no realm comercial (OC1):
```
https://mynamespace.compat.objectstorage.region.oci.customer-oci.com/bucket_name/object_name
```
- Suportado em todas as zonas:
```
https://mynamespace.compat.objectstorage.region.oraclecloud.com/bucket_name/object_name
```
Formatos de URL de Bucket:
- Suportado somente no realm comercial (OC1):
```
https://mynamespace.compat.objectstorage.region.oci.customer-oci.com/bucket_name
```
- Suportado em todas as zonas:
```
https://mynamespace.compat.objectstorage.region.oraclecloud.com/bucket_name
```
Consulte Compatibilidade com Amazon S3 e API do Object Storage Service para obter mais informações.
URL Compatível com S3 do Google Cloud Storage

Formato de URL do Objeto:
```
https://bucketname.storage.googleapis.com/object_name
```
Formato de URL do Bucket:
```
https://bucketname.storage.googleapis.com/
```
Consulte Migrando do Amazon S3 para o Cloud Storage e Pontos Finais de Solicitação para obter mais informações.
Wasabi S3 URL compatível

Formato de URL do Objeto:
```
https://bucketname.s3.region.wasabisys.com/object_name
```
Formato de URL do Bucket:
```
https://bucketname.s3.region.wasabisys.com/
```
Consulte Referência de API do Wasabi S3 e URLs de Serviço para Regiões de Armazenamento do Wasabi para obter mais informações.

Tópico principal: DBMS_CLOUD Formatos de URI

GitHub Formato de URL Bruto

O DBMS_CLOUD suporta URLs Brutos GitHub para acessar dados de um Repositório GitHub.

Observação

Para acesso ao DBMS_CLOUD com URLs Brutos do GitHub, o acesso ao repositório é limitado à funcionalidade somente para leitura. As APIs do DBMS_CLOUD, como DBMS_CLOUD.PUT_OBJECT, que gravam dados, não são suportadas com APIs do DBMS_CLOUD em um Repositório do GitHub.

Como alternativa, use DBMS_CLOUD_REPO.PUT_FILE para fazer upload de dados para um Repositório GitHub.

Use URLs brutos do GitHub com APIs do DBMS_CLOUD para acessar arquivos de origem que residem em um Repositório do GitHub. Quando você procura um arquivo em GitHub e clique no link Baixo, isso mostra o URL Bruto GitHub. O domínio raw.githubusercontent.com fornece versões não processadas de arquivos armazenados nos repositórios GitHub.

Por exemplo, usando DBMS_CLOUD.GET_OBJECT:

BEGIN
 DBMS_CLOUD.GET_OBJECT(
   credential_name => 'MY_CRED',
   object_uri      => 'https://raw.githubusercontent.com/myaccount/myrepo/master/data-management-library/autonomous-database/adb-loading.csv',
   directory_name  => 'DATA_PUMP_DIR'
  );
END;
/

Por exemplo, usando DBMS_CLOUD.CREATE_EXTERNAL_TABLE:

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
    credential_name => 'MY_CRED',
    table_name      => 'EMPLOYEES_EXT',
    file_uri_list   => 'https://raw.githubusercontent.com/myaccount/myrepo/master/data-management-library/autonomous-database/*.csv',
    column_list     => 'name varchar2(30), gender varchar2(30), salary number',
    format          => JSON_OBJECT('type' value 'csv')
  );
END;
/
SELECT * FROM employees_ext;

Os procedimentos DBMS_CLOUD que utilizam um URL para acessar um Repositório GitHub não exigem credenciais com repositórios GitHub de visibilidade pública. Para usar um URL de visibilidade pública, você pode especificar o parâmetro credential_name como NULL ou não fornecer um parâmetro credential_name. Consulte Definindo a visibilidade do repositóriopara obter mais informações.

Tópico principal: DBMS_CLOUD Formatos de URI

Formatos de URI Adicionais Gerenciados pelo Cliente

Além do URIs reconhecido e pré-configurado com seus nomes de domínio totalmente qualificados (FQDNs), o DBMS_CLOUD não pode determinar o esquema de autenticação adequado para pontos finais gerenciados pelo cliente URIs. Nesses casos, DBMS_CLOUD conta com o esquema URI adequado para identificar o esquema de autenticação para o ponto final gerenciado pelo cliente.

Esquema do URI	Tipo de Autenticação	Descrição do Método de Acesso	Exemplo de URI
básico://	Autenticação básica	O nome de usuário e a senha armazenados no objeto de credencial do banco de dados são usados para autenticar a solicitação HTTP	`basic://api.github.com/users/myaccount`
portador://	Autenticação de token do portador	O token do portador armazenado no campo de senha no objeto de credencial do banco de dados é usado para especificar o cabeçalho de Autorização da solicitação HTTP	`bearer://api.sendgrid.com/v3/resource`
oci://	Nativo do OCI	Chave de assinatura do OCI obtida do objeto de credencial do banco de dados armazenado e usado para assinar solicitações usando o protocolo de autenticação do OCI	`oci://objectstorage.us-ashburn-1.oraclecloud.com`
public://	Sem autenticação	URLs Públicos	`public://cms.data.gov/`
s3://	Compatível com Amazon Web Services S3	Chave de acesso e chave secreta obtidas do campo nome de usuário/senha do objeto de credencial do banco de dados e autenticação compatível com S3 executada para a solicitação HTTP.	`s3://bucket.myprivatesite.com/file1.csv`

Exemplos de:

Ponto final gerenciado pelo cliente usando autenticação compatível com S3.

Este exemplo mostra como, para o novo URIs, os clientes podem adicionar o padrão de nome de host público ou privado usando o pacote DBMS_NETWORK_ACL_ADMIN. O bloco de código, executado pelo usuário ADMIN, permite o acesso HTTPS do usuário SCOTT aos pontos finais no domínio *.myprivatesite.com. Em seguida, mostra como o usuário SCOTT acessa o ponto final recém-ativado. Observe que a credencial MY_CRED do usuário SCOTT deve armazenar a chave de acesso e a chave secreta para autenticação compatível com S3 executada para a solicitação HTTP indicada pelo prefixo URI.


BEGIN
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
         host => '*.myprivatesite.com',
         ace => xs$ace_type(privilege_list => xs$name_list('http'),
                            principal_name => 'SCOTT',
                            principal_type => xs_acl.ptype_db),
         private_target => TRUE   );
END;
/

BEGIN
   DBMS_CLOUD.get_object(
       credential_name => 'MY_CRED',
       object_uri      => 's3://bucket.myprivatesite.com/file1.csv',
       directory_name  => 'MY_DIR'  );
END;
/

Ponto final gerenciado pelo cliente com acesso público

Este exemplo mostra como registrar o usuário SCOTT para acessar APIs REST públicas. O usuário ADMIN cria uma ACL de rede para o host para fornecer acesso ao usuário SCOTT.


BEGIN
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
         host => 'data.cms.gov',
         ace => xs$ace_type(privilege_list => xs$name_list('http'),
                            principal_name => 'SCOTT',
                            principal_type => xs_acl.ptype_db)
   );
END;
/

SELECT DBMS_CLOUD.get_response_text(
          DBMS_CLOUD.send_request(
              uri     => 'public://data.cms.gov/provider-data/api/1/datastore/imports/a',
              method  => DBMS_CLOUD.METHOD_GET,
              headers => JSON_OBJECT('Accept' VALUE 'application/json')
          )
       )
   FROM DUAL;
/

Tópico principal: DBMS_CLOUD Formatos de URI

Documentação do Oracle Cloud Infrastructure