Chamar Web Services do Autonomous Database

Descreve opções para chamar Web Services do Autonomous Database.

Há várias opções para chamar Web Services do Autonomous Database, incluindo as seguintes:

  • Usar APIs REST DBMS_CLOUD: A função DBMS_CLOUD.SEND_REQUEST inicia uma solicitação HTTP, obtém a resposta e encerra a resposta. Esta função fornece um workflow para enviar uma solicitação de API REST na nuvem com argumentos e a função retorna um código de resposta e um payload. Consulte SEND_REQUEST Função e Procedimento para obter mais informações.

  • Usar o Oracle APEX: Você pode interagir com os serviços Web do estilo SOAP e RESTful do APEX na sua instância do Autonomous Database. Consulte Usar Web Services com o Oracle APEX para obter mais informações.

  • Use UTL_HTTP para submeter uma solicitação a um site público: Consulte Submeter uma Solicitação HTTP a um Host Público para obter mais informações.

  • Use UTL_HTTP para submeter uma solicitação a um site privado: Consulte Submeter uma Solicitação HTTP a um Host Privado para obter mais informações.

    Quando sua instância do Autonomous Database está em um ponto final privado, você pode usar uma wallet gerenciada pelo cliente com procedimentos em UTL_HTTP, DBMS_LDAP, UTL_SMTP ou UTL_TCP. Consulte Fazer Chamadas Externas Usando uma Wallet Gerenciada pelo Cliente para obter mais informações.

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

Tópicos

Submeter uma Solicitação HTTP a um Host Público

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;
Observação

Se sua instância do Autonomous Database estiver em um ponto final privado e você quiser que suas chamadas do UTL_HTTP para hosts públicos estejam sujeitas às regras de saída da VCN do ponto final privado, defina a propriedade do banco de dados ROUTE_OUTBOUND_CONNECTIONS como PRIVATE_ENDPOINT.

Consulte Segurança Aprimorada para Conexões de Saída com Pontos Finais Privados para obter mais informações.

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

Submeter uma Solicitação HTTP a um Host Privado

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

Submeter uma Solicitação HTTP a um Site Privado com um Proxy

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

Quando sua instância do Autonomous Database estiver em um ponto final privado, para usar UTL_HTTP com um proxy de destino, o proxy de destino deverá estar acessível pela VCN do Oracle Cloud Infrastructure do banco de dados de origem.

Por exemplo, você pode se conectar usando um proxy quando:

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

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

  • O servidor proxy é 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 usando uma wallet gerenciada pelo cliente. Consulte Fazer Chamadas Externas Usando uma Wallet Gerenciada pelo Cliente para obter mais informações.

Para usar um servidor proxy 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 ROUTE_OUTBOUND_CONNECTIONS como PRIVATE_ENDPOINT, 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;

Observações para definir um servidor proxy com UTL_HTTP.SET_PROXY:

  • As solicitações DBMS_CLOUD não respeitam o servidor proxy definido com UTL_HTTP.SET_PROXY. Isso inclui DBMS_CLOUD.SEND_REQUEST e todo o acesso ao armazenamento de objetos para tabelas externas DBMS_CLOUD que você define com DBMS_CLOUD.CREATE_EXTERNAL_TABLE, DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE ou DBMS_CLOUD.CREATE_HYBRID_PART_TABLE.

  • As solicitações APEX_WEB_SERVICE não respeitam o servidor proxy definido com UTL_HTTP.SET_PROXY.

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

Usar Objetos de Credencial para Definir Autenticação HTTP

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

Observações para Enviar Solicitações HTTP com o Oracle APEX ou o Database Actions

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 planilha SQL do Oracle APEX SQL Commands e do Database Actions para uma instância do Autonomous Database são sem 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 de manutenção do estado da memória do banco de dados entre execuções de instrução para comandos SQL que você submete ao Autonomous Database.

Ferramenta de Comandos SQL Enviar Declarações como um Bloco
Planilha SQL do Database Actions
  • Selecione todas as instruções e clique em Executar Instrução
  • Não selecione nada e clique em Run as SQL script
Comandos SQL do Oracle APEX

O APEX SQL Commands suporta apenas a execução de instruções individuais. Quando quiser executar várias instruções, encapsule-as em um único bloco anônimo PL/SQL. Para executar o bloco com Comandos SQL do APEX, clique em Executar.

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;