Chamar Web Services do Autonomous AI Database

Fornece detalhes para usar o UTL_HTTP para submeter uma solicitação HTTP em um host público.

Por exemplo, para submeter uma solicitação HTTP para um host público www.example.com, crie uma Lista de Controle de Acesso para o host:

BEGIN
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
         host => 'www.example.com',
         ace =>  xs$ace_type( privilege_list => xs$name_list('http'),
                              principal_name => 'ADMIN',
                              principal_type => xs_acl.ptype_db));
END;

Em seguida, envie a solicitação HTTP:

SELECT UTL_HTTP.REQUEST(url => 'https://www.example.com/') FROM dual;

Consulte Notas do Pacote PL/SQL para o Autonomous AI Database para obter informações sobre restrições do UTL_HTTP no Autonomous AI Database.

Descreve as etapas para usar o UTL_HTTP para submeter uma solicitação HTTP em um host privado.

Para submeter uma solicitação a um host de destino em um ponto final privado, o host de destino deve estar acessível pela VCN do Oracle Cloud Infrastructure do banco de dados de origem. Por exemplo, você pode estabelecer conexão com o host de destino quando:

• O banco de dados de origem e o host de destino estão na mesma VCN do Oracle Cloud Infrastructure.

• O banco de dados de origem e o host de destino estão em diferentes VCNs do Oracle Cloud Infrastructure pareadas.

• O host de destino é uma rede on-premises conectada à VCN do Oracle Cloud Infrastructure do banco de dados de origem usando FastConnect ou VPN.

Você também pode fazer chamadas UTL_HTTP com uma wallet gerenciada pelo cliente quando seu Autonomous AI Database estiver em um ponto final privado. Consulte Fazer Chamadas Externas Usando uma Wallet Gerenciada pelo Cliente para obter mais informações.

Para fazer uma solicitação UTL_HTTP para um destino em um ponto final privado:

1. Crie uma Lista de Controle de Acesso para o host.

   Por exemplo:

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

   Conforme mostrado neste exemplo, quando você cria uma Lista de Controle de Acesso para o host, especifique o parâmetro private_target com o valor TRUE.

   Observação
   
   Se você definir a propriedade do banco de dados ROUTE_OUTBOUND_CONNECTIONS, não será necessário definir o parâmetro private_target como TRUE nesta API. Consulte Segurança Aprimorada para Conexões de Saída com Pontos Finais Privados para obter mais informações.

2. Submeter solicitação HTTP:

   SELECT UTL_HTTP.REQUEST(
                   url => 'https://www.example.com/',
                   https_host => 'www.example.com') 
                FROM dual;

Consulte Notas do Pacote PL/SQL para o Autonomous AI Database para obter informações sobre restrições do UTL_HTTP no Autonomous AI Database.

Quando sua instância do Autonomous AI Database estiver em um ponto final privado, você poderá usar um proxy para submeter solicitações HTTP com UTL_HTTP.

1. Defina a ACL HTTP_PROXY no servidor proxy.

   Por exemplo:

   BEGIN
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
          host =>'www-proxy-example.com',
          ace  => xs$ace_type(privilege_list => xs$name_list('HTTP_PROXY'),
                              principal_name => 'APPUSER1',
                              principal_type => xs_acl.ptype_db),
                              private_target => TRUE);
   END;
   /

   Conforme mostrado neste exemplo, quando você cria uma Lista de Controle de Acesso para o servidor proxy, especifique o parâmetro private_target com o valor TRUE.

   Observação
   
   Se você definir a propriedade do banco de dados ROUTE_OUTBOUND_CONNECTIONS, não será necessário definir o parâmetro private_target como TRUE nesta API. Consulte Segurança Aprimorada para Conexões de Saída com Pontos Finais Privados para obter mais informações.
2. Defina a ACL HTTP no Web Server remoto.

   Por exemplo:

   BEGIN
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
           host =>'example.com',
           ace => xs$ace_type( privilege_list => xs$name_list('HTTP'),
                               principal_name => 'APPUSER1',
                               principal_type => xs_acl.ptype_db)
   END;
   /

3. Defina a wallet e o proxy para UTL_HTTP.

   Por exemplo:

   BEGIN
      UTL_HTTP.SET_WALLET('');
      UTL_HTTP.SET_PROXY('www-proxy-example:80');
   END;
   /

4. Submeter uma solicitação HTTP:

   SELECT UTL_HTTP.REQUEST(    
                       url         => 'https://www.example.com/',
                       https_host  => 'www.example.com')
                FROM dual;

Descreve como especificar objetos de credencial para o procedimento UTL_HTTP.SET_CREDENTIAL.

O procedimento UTL_HTTP.SET_CREDENTIAL define informações de autenticação HTTP no cabeçalho da solicitação HTTP. O servidor Web precisa dessas informações para autorizar a solicitação.

O procedimento UTL_HTTP.SET_CREDENTIAL permite que você informe objetos de credencial para definir a autenticação HTTP. Os objetos de credencial são objetos de esquema; portanto, eles só podem ser acessados por usuários privilegiados e permitem que você configure privilégios no nível do esquema para acessar as credenciais. A aprovação de objetos de credencial é uma maneira apropriada e segura de armazenar e gerenciar nome de usuário/senha/chaves a serem usados para autenticação.

O procedimento UTL_HTTP.SET_CREDENTIAL é uma alternativa segura e conveniente ao procedimento UTL_HTTP.SET_AUTHENTICATION.

Exemplo

...
UTL_HTTP.SET_AUTHENTICATION (l_http_request, 'web_app_user', 'xxxxxxxxxxxx');
...

Conforme mostrado no exemplo acima, ao chamar o procedimento SET_AUTHENTICATION, você deve informar o nome de usuário/senha em texto não criptografado como parte dos parâmetros formais PL/SQL. Talvez seja necessário incorporar o nome de usuário/senha em vários scripts cron ou de automação PL/SQL. Passar senhas de texto não criptografado é um problema de conformidade que é tratado no procedimento UTL_HTTP.SET_CREDENTIAL.

Consulte SET_AUTHENTICATION Procedure e SET_AUTHENTICATION_FROM_WALLET Procedure para obter mais informações.

Sintaxe UTL_HTTP.SET_CREDENTIAL

UTL_HTTP.SET_CREDENTIAL (
    r          IN OUT NOCOPY req,
    credential IN VARCHAR2,
    scheme     IN VARCHAR2 DEFAULT 'Basic',
    for_proxy  IN BOOLEAN  DEFAULT FALSE);

Exemplo para especificar um objeto de credencial no procedimento SET_CREDENTIAL:

• Crie um objeto de credencial:

  BEGIN DBMS_CLOUD.CREATE_CREDENTIAL (
      credential_name => 'HTTP_CRED',
      username        => 'web_app_user',
      password        => '<password>' );
  END;

  Isso cria um objeto de credencial que cria um par de nome de usuário/senha armazenado.

  Consulte CREATE_CREDENTIAL Procedures para obter mais informações.

  Consulte Especificando Credenciais do Job do Scheduler para obter mais informações.

• Chame o procedimento UTL_HTTP.SET_CREDENTIAL:

  DECLARE
        l_http_request  UTL_HTTP.REQ;
      BEGIN 
        l_http_request := UTL_HTTP.BEGIN_REQUEST('https://www.example.com/v1/dwcsdev/NAME/dwcs_small_xt1.csv');
        UTL_HTTP.SET_CREDENTIAL (l_http_request, 'HTTP_CRED','BASIC');
        ...
  END;
  

  Este exemplo primeiro cria uma solicitação chamando o procedimento BEGIN_REQUEST e define informações de autenticação HTTP no cabeçalho da solicitação HTTP chamando o procedimento SET_CREDENTIAL. O servidor Web precisa dessas informações para autorizar a solicitação. O valor l_http_request é a solicitação HTTP, HTTP_CRED é o nome das credenciais e BASIC é o esquema de autenticação HTTP.

Consulte UTL_HTTP para saber mais.

Consulte Notas do Pacote PL/SQL para o Autonomous AI Database para obter informações sobre restrições do UTL_HTTP no Autonomous AI Database.

Quando você usa a planilha SQL Comandos SQL do Oracle APEX ou Database Actions para executar vários comandos SQL sequenciais, os comandos podem ser executados em sessões de banco de dados diferentes que não salvam o estado de uma instrução anterior. Esse comportamento difere dos clientes SQL do desktop, como SQL*Plus e SQL Developer, que mantêm uma conexão persistente com o banco de dados.

Os envios de planilhas SQL do Oracle APEX SQL Commands e do Database Actions para uma instância do Autonomous AI Database não têm monitoramento de estado. Isso significa que a execução de instruções SQL e PL/SQL individuais pode salvar o estado na memória do banco de dados, por exemplo, quando você envia um comando para usar uma wallet, mas o estado pode ser limpo antes da execução da próxima instrução.

Exiba a tabela a seguir para ver as etapas para manter o estado da memória do banco de dados entre execuções de instrução para comandos SQL que você submete ao Autonomous AI Database.

Por exemplo, use o seguinte bloco de código para executar um comando utl_http.request() que faça uso de uma Wallet Gerenciada pelo Cliente:

SELECT utl_http.request(url => 'https://api.example.com/', wallet_path => 'file:path_to_wallet', wallet_password => 'password' ) FROM DUAL";

Compare isso com a execução com duas instruções consecutivas que podem falhar se o comando utl_http.set_wallet() e a instrução utl_http.request() forem executados individualmente, em vez de como um único bloco de código:

EXEC utl_http.set_wallet('file:WALLET_DIR/wallet.sso', 'password');
SELECT utl_http.request('https://api.example.com/') FROM DUAL;

Você pode configurar seu Autonomous AI Database para enviar informações de identidade do banco de dados como cabeçalhos HTTP personalizados ao fazer solicitações HTTP de saída.

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS = '[
"DATABASE_NAME",
"REGION",
"DATABASE_OCID"
]';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS = '[
"DATABASE_NAME",
"REGION",
"TENANT_OCID",
"DATABASE_OCID",
"COMPARTMENT_OCID",
"CLOUD_DOMAIN",
"CLIENT_IP_ADDRESS"
]';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS_DOMAINS = '*';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS_DOMAINS = 'objectstorage.oraclecloud.com';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS_DOMAINS = 'oraclecloud.com, example.com';

X-ADB-Source-Database=
  {"databaseName":"MYDATABASENAME",
   "region":"region_identifier",
   "tenantOcid":"tenant_ocid",
   "databaseOcid":"database_ocid",
   "compartmentOcid":"compartment_ocid",
   "clientIpAddress":"client_ip_address"}