Usar Web Services com o Oracle APEX

Há vários requisitos para submeter uma solicitação HTTP a um host privado do Oracle APEX em sua instância do Autonomous Database.

Para submeter uma solicitação a um host de destino em um ponto final privado ou atrás de firewalls locais, o host de destino deve estar acessível pela VCN do Oracle Cloud Infrastructure do banco de dados de origem:

1. Certifique-se de que o ponto final atenda aos pré-requisitos para submeter uma solicitação HTTP, conforme descrito aqui: Envie uma Solicitação HTTP para um Host Privado com UTL_HTTP.

2. Adicione a seguinte lista de controle de acesso para o host desejado como ADMIN (observe o parâmetro private_target):

   BEGIN
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
       host => 'www.example.com',
       ace => XS$ACE_TYPE(
         privilege_list => XS$NAME_LIST('http'),
         principal_name => APEX_APPLICATION.g_flow_schema_owner,
         principal_type => XS_ACL.ptype_db),
       private_target => true);
   END;
   /

O Oracle APEX no Autonomous Database é pré-configurado com uma Oracle Wallet que funcionará com a maioria dos pontos finais HTTPS. Se quiser consumir APIs REST de servidores que usam certificados SSL menos comuns ou autoassinados, você poderá configurar uma wallet gerenciada pelo cliente.

O Oracle APEX no Autonomous Database é pré-configurado com um Oracle Wallet que contém mais de 90 dos certificados SSL raiz e intermediários confiáveis mais comuns. O pacote APEX_WEB_SERVICE aproveita automaticamente esse Oracle Wallet sem configuração adicional dos desenvolvedores de aplicativos.

Se quiser consumir APIs REST de servidores que usam certificados SSL menos comuns ou autoassinados, você poderá configurar uma wallet gerenciada pelo cliente. Primeiro, siga as instruções de configuração e implantação em Pré-requisitos para Usar uma Wallet Gerenciada pelo Cliente com Chamadas Externas. Depois que a wallet for implantada no seu Autonomous Database, conceda READ no objeto de diretório que contém a wallet ao esquema de plataforma APEX como ADMIN:

BEGIN
  execute immediate 'grant READ on directory WALLET_DIR to ' ||
    APEX_APPLICATION.g_flow_schema_owner;
END;

Em seguida, quando você fizer referência à wallet nas chamadas de API APEX_WEB_SERVICE, certifique-se de usar o prefixo DIR: em vez do prefixo FILE: usual. Por exemplo:

l_resp := APEX_WEB_SERVICE.MAKE_REST_REQUEST(
  p_url         => 'https://www.example.com/',
  p_http_method => 'GET',
  p_wallet_path => 'DIR:WALLET_DIR'
);

Você também pode configurar essa wallet como o padrão para toda a instância do Oracle APEX nos APEX Administration Services selecionando Gerenciar Instância → Definições da Instância → Wallet → Caminho da Wallet ou definindo o parâmetro de instância WALLET_PATH.

Para voltar à wallet pré-configurada, defina WALLET_PATH como um valor vazio.

Consulte Acessar o Oracle APEX Administration Services para obter mais informações.

Sua instância do Oracle APEX não requer um proxy web de saída para fazer chamadas de APIs REST externas. Os Autonomous Databases configurados com um ponto final privado podem usar um proxy Web implantado na sua VCN, se desejado.

Para usar um proxy Web, defina a seguinte lista de controle de acesso como ADMIN:

BEGIN
  DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
    host           => 'www-proxy.example.com',
    lower_port     => 80,
    ace => XS$ACE_TYPE( 
      privilege_list => XS$NAME_LIST('HTTP_PROXY'),
      principal_name => APEX_APPLICATION.g_flow_schema_owner,
      principal_type => XS_ACL.ptype_db),
    private_target => true);
END;
/

Em seguida, você pode usar o proxy Web em chamadas de API APEX_WEB_SERVICE:

l_resp := APEX_WEB_SERVICE.MAKE_REST_REQUEST(
  p_url            => 'https://www.example.com/',
  p_http_method    => 'GET',
  p_proxy_override => 'www-proxy.example.com:80'
);

Você também pode configurar um proxy Web no nível do aplicativo definindo a propriedade Servidor Proxy na página Componentes Compartilhados → Definição do Aplicativo → Propriedades ou no nível da instância em Serviços de Administração do APEX de Gerenciar Instância → Segurança → Proxy da Instância.

Se você tentar usar um proxy Web quando o seu Autonomous Database estiver configurado com um ponto final público, um erro será retornado:

ORA-01031: insufficient privileges

Consulte Submeter uma Solicitação HTTP a um Host Privado com UTL_HTTP para obter mais informações sobre proxies ao usar a API UTL_HTTP.

Consulte Acessar o Oracle APEX Administration Services para obter mais informações.

Fornece observações para trabalhar com web services no Oracle APEX de uma instância do Autonomous Database.

Observe o seguinte ao trabalhar com serviços Web no Oracle APEX:

• Todos os Web services devem ser protegidos. Somente serviços HTTPS são suportados na porta padrão (443). Não são permitidas conexões por meio de endereços IP.

• Cada instância do Autonomous Database é pré-configurada com uma lista de controle de acesso à rede (ACL) para permitir chamadas de serviço Web de saída do Oracle APEX para pontos finais públicos.

• As solicitações APEX_WEB_SERVICE não respeitam a wallet personalizada definida com chamadas de API UTL_HTTP.SET_WALLET.

• Há um limite padrão de 1.000 solicitações de serviço Web de saída por espaço de trabalho do APEX em um período contínuo de 24 horas (isso se aplica a novos bancos de dados; alguns bancos de dados mais antigos podem ter um limite maior). Se o limite de chamadas de serviço Web de saída for atingido, a seguinte exceção SQL será gerada na solicitação subsequente e a solicitação será bloqueada:

  ORA-20001: You have exceeded the maximum number of web service requests per workspace. Please contact your administrator.

  Você pode gerar ou remover o limite padrão de solicitações de web service de saída definindo um valor para o parâmetro de instância MAX_WEBSERVICE_REQUESTS ou atualizando o atributo Máximo de Solicitações de Web Service no APEX Administration Services. Por exemplo, para alterar o limite para 250.000, conecte-se ao seu banco de dados como ADMIN usando um cliente SQL e execute o seguinte:

  BEGIN
    APEX_INSTANCE_ADMIN.SET_PARAMETER('MAX_WEBSERVICE_REQUESTS', '250000');
    COMMIT;
  END;
  /

Para saber mais, consulte:

• APEX_WEB_SERVICE no Oracle APEX API Reference

• Managing REST Data Sources no Oracle APEX App Builder User's Guide