Realizar llamadas externas mediante una cartera gestionada por el cliente

Puede utilizar el paquete UTL_HTTP cuando su base de datos de IA autónoma necesite acceder a los datos de Internet a través de HTTP/HTTPS. El paquete UTL_HTTP permite realizar llamadas HTTP directamente desde SQL y PL/SQL.

Si llama a un punto final HTTPS, debe configurar un Oracle Wallet. La base de datos de IA autónoma necesita una cartera que contenga los certificados raíz e intermedios de confianza para cualquier punto final HTTPS al que se conecte la base de datos. El paquete UTL_HTTP utiliza esta cartera para establecer una conexión SSL/TLS segura. Puede crear y gestionar la cartera con la utilidad orapki.

Nota: Las solicitudes HTTP sin formato (no HTTPS) no necesitan Oracle Wallet.

En las siguientes secciones se explica cómo configurar y utilizar una cartera gestionada por el cliente para realizar llamadas HTTPS salientes con el paquete UTL_HTTP en Autonomous AI Database.

Requisitos para utilizar una cartera gestionada por el cliente con llamadas externas

Antes de empezar, asegúrese de que tiene:

Acceso a la base de datos de IA autónoma mediante una cuenta que puede ejecutar PL/SQL y configurar UTL_HTTP.
Acceso al punto final HTTPS de destino y su cadena de certificados completa (certificados raíz + intermedios).
Estación de trabajo en la que puede ejecutar orapki para crear y validar una instancia de Oracle Wallet. Debe instalar Oracle Database para obtener la utilidad orapki. Consulte Instalación de Oracle Database para obtener más información.

Preparación de la cartera gestionada por el cliente

En este paso, creará y validará la cartera en la estación de trabajo antes de cargarla en la base de datos de IA autónoma.

Obtener o crear una cartera gestionada por el cliente

Ejemplo con 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 la cartera

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

Debe ver todos los certificados importados en la lista.

Carga de la cartera

Una vez que la cartera gestionada por el cliente esté lista (incluidos los certificados autofirmados, raíz o intermedios necesarios), cargue los archivos de cartera en una ubicación de Oracle Cloud Infrastructure (OCI) Object Storage.

Utilizar una cartera gestionada por el cliente con UTL_HTTP

En esta sección se muestra cómo descargar la cartera de Object Storage, permitir el acceso de red al punto final HTTPS y, a continuación, realizar llamadas HTTPS mediante el paquete UTL_HTTP.

Cree una credencial de acceso al almacenamiento de objetos:
```
 BEGIN
 DBMS_CLOUD.CREATE_CREDENTIAL(credential_name => 'DEF_CRED_NAME',
 username => 'user1@example.com',
 password => 'password'
 );
 END;
 /
```
Los valores que proporcione para username y password dependen del servicio de Cloud Object Storage que utilice. Esto crea la credencial que utiliza para acceder a Cloud Object Storage donde reside la cartera gestionada por el cliente.
Cree (o reutilice) un objeto de directorio para la cartera:

Utilice un directorio existente o cree un nuevo directorio para el archivo de cartera. Por ejemplo:
```
 CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
```
Consulte Crear directorio en base de datos de IA autónoma para obtener información sobre la creación de directorios.
Obtenga la ruta de acceso del directorio absoluta:

Necesitará la ruta de acceso de directorio absoluta al llamar a UTL_HTTP.SET_WALLET.
```
 SELECT DIRECTORY_NAME, DIRECTORY_PATH FROM DBA_DIRECTORIES WHERE DIRECTORY_NAME = '<wallet_dir>';
```
Descargue el archivo de cartera de Object Storage en el directorio:

Utilice DBMS_CLOUD.GET_OBJECT para copiar el archivo de cartera en el directorio. Por ejemplo:
```
 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;
 /
```
En este ejemplo, namespace-string es el espacio en el que se almacenan objetos de Oracle Cloud Infrastructure y bucketname es el nombre del cubo. Consulte Descripción de los espacios de nombres de Object Storage para obtener más información.

Permitir el acceso de red saliente (ACL) al punto final HTTPS:

Debe permitir que el usuario/esquema de la base de datos llegue al host de destino a través de la red.

  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;
 /

En los despliegues de Exadata Cloud@Customer, también debe configurar el proxy como se muestra a continuación:

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

Realice llamadas HTTPS con UTL_HTTP:

Solicitud GET simple:

 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;
 /

Solicitud POST con carga útil 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;
  /

Solución de problemas de errores comunes:

Errores de cadena de certificados

Error: ORA-29024: Certificate validation failure

Es posible que falten certificados raíz e intermedios.
El punto final de destino puede estar utilizando una nueva CA: vuelva a descargar la cadena de certificados completa y vuelva a crear la cartera.

Errores de ruta de acceso de cartera

ORA-28759: Failure to open file

Ruta de acceso de cartera incorrecta en SET_WALLET.
Falta el prefijo file:.
Los archivos de cartera cargados no están presentes en el directorio.

Fallos de establecimiento de comunicación

ORA-24263 / ORA-29005

El protocolo TLS no coincide.
Certificados incorrectos o caducados.
El punto final aplica TLS > 1,2

Uso de una cartera gestionada por el cliente para las notificaciones por correo electrónico del programador (SMTP)

En esta sección se muestra cómo configurar las notificaciones de correo electrónico del programador para utilizar un servidor SMTP a través de TLS (STARTTLS) con una cartera gestionada por el cliente.

Antes de empezar, asegúrese de que ya ha preparado la cartera gestionada por el cliente (la ha creado localmente, la ha validado y la ha cargado en Object Storage). Consulte Prepare la cartera gestionada por el cliente para obtener más información.

Para utilizar una cartera gestionada por el cliente con el servidor de correo electrónico del programador:

Cree una credencial de acceso al almacenamiento de objetos:

Puede utilizar DBMS_CLOUD.CREATE_CREDENTIAL para crear una credencial para acceder a Cloud Object Storage.
```
 BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL(
     credential_name => 'DEF_CRED_NAME',
     username => 'user1@example.com',
     password => 'password'
 );
 END;
 /
```
Los valores que proporcione para username y password dependen del servicio de Cloud Object Storage que utilice. Esto crea la credencial que utiliza para acceder a Cloud Object Storage donde reside la cartera gestionada por el cliente.
Cree (o reutilice) un objeto de directorio para la cartera:

Utilice un directorio existente o cree un nuevo directorio para el archivo de cartera. Por ejemplo:
```
 CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
```
Consulte Crear directorio en base de datos de IA autónoma para obtener información sobre la creación de directorios.
Obtenga la ruta de acceso del directorio absoluta:

Necesitará la ruta de acceso de directorio absoluta al llamar a UTL_HTTP.SET_WALLET.
```
 SELECT DIRECTORY_NAME, DIRECTORY_PATH FROM DBA_DIRECTORIES WHERE DIRECTORY_NAME = '<wallet_dir>';
```
Descargue el archivo de cartera de Object Storage en el directorio:

Utilice DBMS_CLOUD.GET_OBJECT para copiar el archivo de cartera en el directorio. Por ejemplo:
```
 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;
 /
```
En este ejemplo, namespace-string es el espacio en el que se almacenan objetos de Oracle Cloud Infrastructure y bucketname es el nombre del cubo. Consulte Descripción de los espacios de nombres de Object Storage para obtener más información.

Configure el correo electrónico del programador (SMTP + STARTTLS):

Ejecute los comandos para configurar el programador para que envíe el correo electrónico SMTP para las notificaciones de trabajos del programador:

 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'
 );

Los comandos realizan lo siguiente:

Define el punto final SMTP del programador (EMAIL_SERVER)
Almacena los detalles de conexión SMTP en EMAIL_CRED y le apunta al programador
Activa el cifrado TLS mediante STARTTLS

Consulte Procedimiento SET_SCHEDULER_ATTRIBUTE para obtener más información.

Cree una credencial para la contraseña de cartera:

Cree una credencial para almacenar la contraseña para la cartera gestionada por el cliente.
```
 BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL(
     credential_name => 'WALLET_CRED',
     username        => 'any_user',
     password        => 'password'
   );
 END;
 /
```
Esto crea la credencial que utiliza en el siguiente paso para proporcionar la contraseña para la cartera gestionada por el cliente.

Indique al programador dónde está la cartera y cómo desbloquearla:

Defina el directorio de cartera del programador y la credencial de cartera.

 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 la configuración de correo electrónico del programador:

Consulte la vista DBA_SCHEDULER_GLOBAL_ATTRIBUTE para verificar los valores definidos en los pasos 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"

Referencia

Comandos orapki útiles:

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

Estructura de directorio de cartera de ejemplo:

cmw_wallet/
- ewallet.p12
- cwallet.sso