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çãoDBMS_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
ouUTL_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 usarUTL_HTTP
para submeter uma solicitação HTTP em um host público. - Submeter uma Solicitação HTTP a um Host Privado
Descreve as etapas para usarUTL_HTTP
para submeter uma solicitação HTTP em um host privado. - 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 comUTL_HTTP
. - Usar Objetos de Credencial para Definir Autenticação HTTP
Descreve como passar objetos de credencial para o procedimentoUTL_HTTP.SET_CREDENTIAL
. - Observações para Enviar Solicitações HTTP com o Oracle APEX ou o Database Actions
Quando você usa a planilha SQL Oracle APEX SQL Commands 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 do desktop, como SQL*Plus e SQL Developer, que mantêm uma conexão persistente com o banco de dados.
Tópico principal: Tarefas
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;
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.
Tópico principal: Chamar Web Services do 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:
-
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 valorTRUE
.Observação
Se você definirROUTE_OUTBOUND_CONNECTIONS
comoPRIVATE_ENDPOINT
, não será necessário definir o parâmetroprivate_target
comoTRUE
nesta API. Consulte Segurança Aprimorada para Conexões de Saída com Pontos Finais Privados para obter mais informações. -
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.
Tópico principal: Chamar Web Services do 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
:
Observações para definir um servidor proxy com UTL_HTTP.SET_PROXY
:
-
As solicitações
DBMS_CLOUD
não respeitam o servidor proxy definido comUTL_HTTP.SET_PROXY
. Isso incluiDBMS_CLOUD.SEND_REQUEST
e todo o acesso ao armazenamento de objetos para tabelas externasDBMS_CLOUD
que você define comDBMS_CLOUD.CREATE_EXTERNAL_TABLE
,DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE
ouDBMS_CLOUD.CREATE_HYBRID_PART_TABLE
. -
As solicitações
APEX_WEB_SERVICE
não respeitam o servidor proxy definido comUTL_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.
Tópico principal: Chamar Web Services do 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 procedimentoSET_CREDENTIAL
. O servidor Web precisa dessas informações para autorizar a solicitação. O valorl_http_request
é a solicitação HTTP,HTTP_CRED
é o nome das credenciais eBASIC
é 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.
Tópico principal: Chamar Web Services do 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 |
|
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;
Tópico principal: Chamar Web Services do Autonomous Database