Fornece detalhes do uso de 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 Autonomous Database para obter informações sobre restrições para UTL_HTTP no Autonomous Database.

Descreve as etapas para usar 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 na 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 pareadas do Oracle Cloud Infrastructure.

• O host de destino é uma rede on-premises que está 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 o seu Autonomous 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 ROUTE_OUTBOUND_CONNECTIONS como PRIVATE_ENDPOINT, não será necessário definir o parâmetro private_target como TRUE nessa API. Consulte Segurança Avançada para Conexões de Saída com Pontos Finais Privados para obter mais informações.

2. Envie a 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 Autonomous Database para obter informações sobre restrições para UTL_HTTP no Autonomous Database.

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

1. Defina a ACL de 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 ROUTE_OUTBOUND_CONNECTIONS como PRIVATE_ENDPOINT, não será necessário definir o parâmetro private_target como TRUE nessa API. Consulte Segurança Avançada para Conexões de Saída com Pontos Finais Privados para obter mais informações.
2. Defina a ACL HTTP no Servidor Web 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. Envie uma solicitação HTTP:

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

Descreve como informar 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 credenciais 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 controlar as credenciais. A passagem de objetos de credencial é uma maneira apropriada e segura de armazenar e gerenciar nome de usuário/senha/chaves a serem usadas 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. A passagem de senhas de texto não criptografado é um problema de conformidade que é tratado no procedimento UTL_HTTP.SET_CREDENTIAL.

Consulte Procedimento SET_AUTHENTICATION e Procedimento SET_AUTHENTICATION_FROM_WALLET 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 informar 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 Procedimento para obter mais informações.

  Consulte Especificando Credenciais de 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;
  

  Esse 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.

Para obter mais informações, consulte UTL_HTTP.

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

Quando você usa a planilha SQL Commands do Oracle APEX ou Database Actions para executar vários comandos SQL sequenciais, os comandos podem ser executados em diferentes sessões de banco de dados que não salvam o estado de uma instrução anterior. Esse comportamento difere dos clientes SQL de desktop, como o SQL*Plus e o 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 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ê submete um comando para usar uma wallet, mas o estado pode ser limpo antes de executar a 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 submetidos ao Autonomous 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 poderão 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;