Fazer Chamadas Externas Usando uma Wallet Gerenciada pelo Cliente

Você pode usar o pacote UTL_HTTP quando o Autonomous AI Database precisar acessar dados na internet por meio de HTTP/HTTPS. O pacote UTL_HTTP permite fazer chamadas HTTP diretamente de SQL e PL/SQL.

Se você estiver chamando um ponto final HTTPS, deverá configurar um Oracle Wallet. O Autonomous AI Database requer uma wallet que contenha os certificados raiz e intermediários confiáveis para qualquer ponto final HTTPS ao qual seu banco de dados se conectará. O pacote UTL_HTTP usa essa wallet para estabelecer uma conexão SSL/TLS segura. Você pode criar e gerenciar a wallet com o utilitário orapki.

Observação: As solicitações HTTP simples (não HTTPS) não exigem um Oracle Wallet.

As seções abaixo explicam como configurar e usar uma wallet gerenciada pelo cliente para fazer chamadas HTTPS de saída com o pacote UTL_HTTP no Autonomous AI Database.

Pré-requisitos para Usar uma Wallet Gerenciada pelo Cliente com Chamadas Externas

Antes de começar, verifique se você tem:

Acesso ao Autonomous AI Database usando uma conta que pode executar PL/SQL e configurar UTL_HTTP.
Acesso ao ponto final HTTPS de destino e sua cadeia de certificados completa (certificados raiz + intermediários).
Uma estação de trabalho na qual você pode executar orapki para criar e validar um Oracle Wallet. Você precisa instalar o Oracle Database para obter o utilitário orapki. Consulte Instalando o Oracle Database para obter detalhes.

Preparar a Wallet Gerenciada pelo Cliente

Nesta etapa, você criará e validará a wallet na sua estação de trabalho antes de fazer upload dela para o Autonomous AI Database.

Obter ou criar uma wallet gerenciada pelo cliente

Exemplo usando orapki:

-- Create an SSL Wallet and load the Root CERTs using orapki utility
$ORACLE_HOME/bin/orapki wallet create -wallet /u01/web/wallet -pwd ********
$ORACLE_HOME/bin/orapki wallet add -wallet /u01/web/wallet -trusted_cert -cert MyWebServer.cer -pwd ********
-- Store the credentials in the SSL Wallet using mkstore utility
$ORACLE_HOME/bin/mkstore -wrl /u01/web/wallet -createCredential secret-from-the-wallet 'example@oracle.com'
********Enter wallet password: ********

Validar a wallet

$ORACLE_HOME/bin/orapki wallet display -wallet /u01/web/wallet

Você deverá ver todos os certificados importados listados.

Faça upload da wallet

Quando a wallet gerenciada pelo cliente estiver pronta (incluindo quaisquer certificados autoassinados/raiz/intermediários necessários), faça upload dos arquivos da wallet para um local no Oracle Cloud Infrastructure (OCI) Object Storage.

Usar uma wallet gerenciada pelo cliente com UTL_HTTP

Esta seção mostra como fazer download da wallet do Object Storage, permitir acesso de rede ao ponto final HTTPS e, em seguida, fazer chamadas HTTPS usando o pacote UTL_HTTP.

Crie uma credencial de acesso ao serviço Object Storage:
```
 BEGIN
 DBMS_CLOUD.CREATE_CREDENTIAL(credential_name => 'DEF_CRED_NAME',
 username => 'user1@example.com',
 password => 'password'
 );
 END;
 /
```
Os valores fornecidos para username e password dependem do serviço de Cloud Object Storage que você está usando. Isso cria a credencial usada para acessar o Cloud Object Storage no qual reside a wallet gerenciada pelo cliente.
Crie (ou reutilize) um objeto de diretório para a wallet:

Use um diretório existente ou crie um novo para o arquivo da wallet. Por exemplo:
```
 CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
```
Consulte Criar Diretório no Autonomous AI Database para obter informações sobre a criação de diretórios.
Obter o caminho do diretório absoluto:

Você precisará do caminho do diretório absoluto ao chamar UTL_HTTP.SET_WALLET.
```
 SELECT DIRECTORY_NAME, DIRECTORY_PATH FROM DBA_DIRECTORIES WHERE DIRECTORY_NAME = '<wallet_dir>';
```
Faça download do arquivo da wallet do serviço Object Storage para o diretório:

Use DBMS_CLOUD.GET_OBJECT para copiar o arquivo da wallet no seu diretório. Por exemplo:
```
 BEGIN
 DBMS_CLOUD.GET_OBJECT(
 credential_name => 'DEF_CRED_NAME',
 object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/cwallet.sso',
 directory_name => 'WALLET_DIR');
 END;
 /
```
Neste exemplo, namespace-string é o namespace do Oracle Cloud Infrastructure Object Storage e bucketname é o nome do bucket. Consulte Noções Básicas de Namespaces do serviço Object Storage para obter mais informações.

Permitir acesso à rede de saída (ACL) para o ponto final HTTPS:

Você deve permitir que o usuário/esquema do banco de dados acesse o host de destino pela rede.

  BEGIN
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
       host => 'api.example.com',
       ace  => xs$ace_type(
       privilege_list => xs$name_list('CONNECT','HTTP','RESOLVE'),
       principal_name => 'ADMIN',
       principal_type => xs_acl.ptype_db
   )
 );
 END;
 /

Nas implantações do Exadata Cloud@Customer, você também precisa configurar o proxy, conforme mostrado abaixo:

 BEGIN
   UTL_HTTP.SET_PROXY('www-proxy.us.oracle.com:80', 'oracle.com');
 END;
 /

Faça chamadas HTTPS com UTL_HTTP:

Solicitação GET simples:

 DECLARE
 l_http_req UTL_HTTP.req;
 l_http_resp UTL_HTTP.resp;
 l_response VARCHAR2(32767);

 BEGIN
    utl_http.set_wallet('file:<absolute_directory_path_from_step_3>');
    l_http_req := UTL_HTTP.BEGIN_REQUEST('https://api.example.com/status');
    l_http_resp := UTL_HTTP.GET_RESPONSE(l_http_req);
    LOOP UTL_HTTP.READ_LINE(l_http_resp, l_response, TRUE);
        DBMS_OUTPUT.PUT_LINE(l_response);
    END LOOP;
    UTL_HTTP.END_RESPONSE(l_http_resp);
 END;
 /

Solicitação POST com payload JSON:

 DECLARE
   l_req UTL_HTTP.req;
   l_resp UTL_HTTP.resp;
   l_line VARCHAR2(32767);
 BEGIN
   utl_http.set_wallet('file:<absolute_directory_path_from_step_3>');
   l_req := UTL_HTTP.BEGIN_REQUEST( url => 'https://api.example.com/data', method => 'POST' );
   UTL_HTTP.SET_HEADER(l_req, 'Content-Type', 'application/json');
   UTL_HTTP.WRITE_TEXT(l_req, '{"key":"value"}');
   l_resp := UTL_HTTP.GET_RESPONSE(l_req);
   LOOP UTL_HTTP.READ_LINE(l_resp, l_line, TRUE);
     DBMS_OUTPUT.PUT_LINE(l_line);
   END LOOP;
   UTL_HTTP.END_RESPONSE(l_resp);
  END;
  /

Solução de problemas para erros comuns:

Erros da cadeia de certificados

Erro: ORA-29024: Certificate validation failure

Os certificados raiz e intermediário podem estar ausentes.
O ponto final de destino pode estar usando uma nova CA - faça download novamente da cadeia de certificados completa e recrie a wallet.

Erros de caminho da wallet

ORA-28759: Failure to open file

Caminho da wallet incorreto em SET_WALLET.
Prefixo file: ausente.
Arquivos da wallet submetidos a upload não presentes no diretório.

Falhas de handshake

ORA-24263 / ORA-29005

Incompatibilidade de protocolo TLS.
Certificados inválidos ou expirados.
O ponto final impõe TLS > 1.2

Usar uma Wallet Gerenciada pelo Cliente para Notificações por E-mail do Scheduler (SMTP)

Esta seção mostra como configurar notificações de e-mail do Scheduler para usar um servidor SMTP em TLS (STARTTLS) com uma wallet gerenciada pelo cliente.

Antes de começar, certifique-se de já ter preparado a wallet gerenciada pelo cliente (criada localmente, validada e submetida a upload para o Object Storage). Consulte Preparar a Wallet Gerenciada pelo Cliente para obter detalhes.

Para usar uma wallet gerenciada pelo cliente com o servidor de e-mail do scheduler:

Crie uma credencial de acesso ao serviço Object Storage:

Você pode usar DBMS_CLOUD.CREATE_CREDENTIAL para criar uma credencial para acessar o Cloud Object Storage.
```
 BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL(
     credential_name => 'DEF_CRED_NAME',
     username => 'user1@example.com',
     password => 'password'
 );
 END;
 /
```
Os valores fornecidos para username e password dependem do serviço de Cloud Object Storage que você está usando. Isso cria a credencial usada para acessar o Cloud Object Storage no qual reside a wallet gerenciada pelo cliente.
Crie (ou reutilize) um objeto de diretório para a wallet:

Use um diretório existente ou crie um novo para o arquivo da wallet. Por exemplo:
```
 CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
```
Consulte Criar Diretório no Autonomous AI Database para obter informações sobre a criação de diretórios.
Obter o caminho do diretório absoluto:

Você precisará do caminho do diretório absoluto ao chamar UTL_HTTP.SET_WALLET.
```
 SELECT DIRECTORY_NAME, DIRECTORY_PATH FROM DBA_DIRECTORIES WHERE DIRECTORY_NAME = '<wallet_dir>';
```
Faça download do arquivo da wallet do serviço Object Storage para o diretório:

Use DBMS_CLOUD.GET_OBJECT para copiar o arquivo da wallet no seu diretório. Por exemplo:
```
 BEGIN
   DBMS_CLOUD.GET_OBJECT(
     credential_name => 'DEF_CRED_NAME',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/cwallet.sso',
     directory_name => 'WALLET_DIR');
 END;
 /
```
Neste exemplo, namespace-string é o namespace do Oracle Cloud Infrastructure Object Storage e bucketname é o nome do bucket. Consulte Noções Básicas de Namespaces do serviço Object Storage para obter mais informações.

Configurar e-mail do Scheduler (SMTP + STARTTLS):

Execute os comandos para configurar o scheduler e enviar um e-mail SMTP para notificações de job do scheduler:

 EXEC DBMS_CLOUD.CREATE_CREDENTIAL('EMAIL_CRED', '<user_ocid>', '<password>');
 GRANT EXECUTE ON admin.EMAIL_CRED TO sys;
 EXEC DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
       'EMAIL_SERVER',
       'smtp.email.us-ashburn-1.oci.oraclecloud.com:587'
 );
 EXEC DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
         'EMAIL_SERVER_CREDENTIAL',
         'EMAIL_CRED'
 );
 EXEC DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
         'EMAIL_SERVER_ENCRYPTION',
         'STARTTLS'
 );

Os comandos fazem o seguinte:

Define o ponto final SMTP do Scheduler (EMAIL_SERVER)
Armazena detalhes de log-in SMTP no EMAIL_CRED e aponta o Scheduler para ele
Ativa a criptografia TLS usando STARTTLS

Consulte Procedimento SET_SCHEDULER_ATTRIBUTE para obter mais informações.

Crie uma credencial para a senha da wallet:

Crie uma credencial para armazenar a senha da wallet gerenciada pelo cliente.
```
 BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL(
     credential_name => 'WALLET_CRED',
     username        => 'any_user',
     password        => 'password'
   );
 END;
 /
```
Isso cria a credencial usada na próxima etapa para fornecer a senha da wallet gerenciada pelo cliente.

Informe ao Scheduler onde está a wallet e como desbloqueá-la:

Defina o diretório da wallet do scheduler e a credencial da wallet.

 BEGIN
   DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
     'EMAIL_SERVER_WALLET_DIRECTORY',
     'WALLET_DIR'
   );

   DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
     'EMAIL_SERVER_WALLET_CREDENTIAL',
     'ADMIN.WALLET_CRED'
   );
 END;
 /

Verifique a configuração de e-mail do Scheduler:

Consulte a exibição DBA_SCHEDULER_GLOBAL_ATTRIBUTE para verificar os valores definidos nas etapas anteriores.

 SELECT attribute_name, value
 FROM DBA_SCHEDULER_GLOBAL_ATTRIBUTE
 WHERE attribute_name LIKE 'EMAIL_SERVER%' ORDER BY 1, 2;

 ATTRIBUTE_NAME                 VALUE

 ------------------------------ -----------------------------------------------
 EMAIL_SERVER                   smtp.email.us-ashburn-1.oci.oraclecloud.com:587
 EMAIL_SERVER_CREDENTIAL        "ADMIN"."EMAIL_CRED"
 EMAIL_SERVER_ENCRYPTION        STARTTLS
 EMAIL_SERVER_WALLET_CREDENTIAL "ADMIN"."WALLET_CRED"
 EMAIL_SERVER_WALLET_DIRECTORY  "WALLET_DIR"

Reference

Comandos orapki úteis:

orapki wallet display -wallet <path> orapki wallet add -wallet <path>
-trusted_cert -cert <cert-file> orapki wallet create -wallet <path> -auto_login

Exemplo de estrutura de diretório da wallet:

cmw_wallet/
- ewallet.p12
- cwallet.sso