Usar Web Services com o Oracle APEX

Você pode interagir com os serviços Web do estilo SOAP e RESTful do Oracle APEX na sua instância do Autonomous Database.

Os serviços Web permitem que os aplicativos interajam uns com os outros pela Web em um ambiente independente de linguagem neutro em plataforma. Em um cenário típico de web services, um aplicativo de negócios envia uma solicitação a um serviço em um determinado URL usando o protocolo HTTP. O serviço recebe a solicitação, a processa e retorna uma resposta. Os serviços Web geralmente se baseiam em arquiteturas SOAP (Simple Object Access Protocol) ou Representational State Transfer (REST).

Usando Origens de Dados REST, os desenvolvedores do APEX podem acessar declarativamente serviços de dados de uma variedade de pontos finais REST, permitindo operações de leitura e gravação. Além de oferecer suporte a regras de armazenamento inteligente em cache para dados REST remotos, o Oracle APEX também oferece a capacidade exclusiva de manipular diretamente os resultados de origens de dados REST usando SQL padrão do setor.

O pacote APEX_WEB_SERVICE permite que você integre outros sistemas ao APEX, permitindo que você interaja com serviços Web em qualquer lugar em que possa usar PL/SQL em sua aplicação. O pacote contém procedimentos e funções para chamar serviços Web do estilo SOAP e RESTful e para simplificar a implementação de fluxos OAuth 2.0.

Envie uma Solicitação HTTP para um Host Privado 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;
    /
Observação

Se você definir a propriedade do banco de dados ROUTE_OUTBOUND_CONNECTIONS como PRIVATE_ENDPOINT, não precisará definir listas de controle de acesso para hosts individuais para acessá-los no APEX. Consulte Segurança Aprimorada para Conexões de Saída com Pontos Finais Privados para obter mais informações.

Faça Chamadas Externas Usando uma Wallet Gerenciada pelo Cliente com o Oracle APEX

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.

Faça Chamadas Externas Usando um Web Proxy com o Oracle APEX

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.

Observações sobre o Uso de Web Services com o Oracle APEX

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: