Llamada a servicios web desde una base de datos de IA autónoma

Proporciona detalles sobre el uso de UTL_HTTP para enviar una solicitud HTTP en un host público.

Por ejemplo, para enviar una solicitud HTTP para un host público www.example.com, cree una lista de control de acceso para el 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;

A continuación, envíe la solicitud HTTP:

SELECT UTL_HTTP.REQUEST(url => 'https://www.example.com/') FROM dual;

Consulte las Notas del paquete PL/SQL para la base de datos de IA autónoma para obtener información sobre las restricciones para UTL_HTTP en la base de datos de IA autónoma.

Describe los pasos para utilizar UTL_HTTP para enviar una solicitud HTTP en un host privado.

Para enviar una solicitud a un host de destino en un punto final privado, se debe poder acceder al host de destino desde la VCN de Oracle Cloud Infrastructure de la base de datos de origen. Por ejemplo, puede conectarse al host de destino cuando:

• Tanto la base de datos de origen como el host de destino están en la misma VCN de Oracle Cloud Infrastructure.

• La base de datos de origen y el host de destino se encuentran en distintas redes virtuales en la nube de Oracle Cloud Infrastructure que están emparejadas.

• El host de destino es una red local que está conectada a la VCN de Oracle Cloud Infrastructure de la base de datos origen mediante FastConnect o una VPN.

También puede realizar llamadas UTL_HTTP con una cartera gestionada por el cliente cuando su base de datos de IA autónoma está en un punto final privado. Consulte Realización de llamadas externas mediante una cartera gestionada por el cliente para obtener más información.

Para realizar una solicitud UTL_HTTP a un destino en un punto final privado:

1. Cree una lista de control de acceso para el host.

   Por ejemplo:

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

   Como se muestra en este ejemplo, al crear una lista de control de acceso para el host, especifique el parámetro private_target con el valor TRUE.

   Nota
   
   Si define la propiedad de base de datos ROUTE_OUTBOUND_CONNECTIONS, no es necesario definir el parámetro private_target en TRUE en esta API. Consulte Seguridad mejorada para conexiones salientes con puntos finales privados para obtener más información.

2. Envíe la solicitud HTTP:

   SELECT UTL_HTTP.REQUEST(
                   url => 'https://www.example.com/',
                   https_host => 'www.example.com') 
                FROM dual;

Consulte las Notas del paquete PL/SQL para la base de datos de IA autónoma para obtener información sobre las restricciones para UTL_HTTP en la base de datos de IA autónoma.

Cuando su instancia de base de datos de IA autónoma está en un punto final privado, puede utilizar un proxy para enviar solicitudes HTTP con UTL_HTTP.

1. Defina la ACL HTTP_PROXY en el servidor proxy.

   Por ejemplo:

   BEGIN
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
          host =>'www-proxy-example.com',
          ace  => xs$ace_type(privilege_list => xs$name_list('HTTP_PROXY'),
                              principal_name => 'APPUSER1',
                              principal_type => xs_acl.ptype_db),
                              private_target => TRUE);
   END;
   /

   Como se muestra en este ejemplo, al crear una lista de control de acceso para el servidor proxy, especifique el parámetro private_target con el valor TRUE.

   Nota
   
   Si define la propiedad de base de datos ROUTE_OUTBOUND_CONNECTIONS, no es necesario definir el parámetro private_target en TRUE en esta API. Consulte Seguridad mejorada para conexiones salientes con puntos finales privados para obtener más información.
2. Defina la ACL HTTP en el servidor web remoto.

   Por ejemplo:

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

3. Defina la cartera y el proxy para UTL_HTTP.

   Por ejemplo:

   BEGIN
      UTL_HTTP.SET_WALLET('');
      UTL_HTTP.SET_PROXY('www-proxy-example:80');
   END;
   /

4. Enviar una solicitud HTTP:

   SELECT UTL_HTTP.REQUEST(    
                       url         => 'https://www.example.com/',
                       https_host  => 'www.example.com')
                FROM dual;

Describe cómo transferir objetos de credenciales al procedimiento UTL_HTTP.SET_CREDENTIAL.

El procedimiento UTL_HTTP.SET_CREDENTIAL define la información de autenticación HTTP en la cabecera de solicitud HTTP. El servidor web necesita esta información para autorizar la solicitud.

El procedimiento UTL_HTTP.SET_CREDENTIAL permite transferir objetos de credenciales para definir la autenticación HTTP. Los objetos de credenciales son objetos de esquema, por lo que solo pueden acceder a ellos los usuarios con privilegios y le permiten configurar privilegios de nivel de esquema para controlar el acceso a las credenciales. La transferencia de objetos de credenciales es una forma adecuada y segura de almacenar y gestionar el nombre de usuario, la contraseña o las claves que se van a utilizar para la autenticación.

El procedimiento UTL_HTTP.SET_CREDENTIAL es una alternativa segura y conveniente al procedimiento UTL_HTTP.SET_AUTHENTICATION.

Ejemplo

...
UTL_HTTP.SET_AUTHENTICATION (l_http_request, 'web_app_user', 'xxxxxxxxxxxx');
...

Como se muestra en el ejemplo anterior, al llamar al procedimiento SET_AUTHENTICATION, debe transferir el nombre de usuario/contraseña en texto no cifrado como parte de los parámetros formales PL/SQL. Puede que necesite embeber el nombre de usuario/contraseña en varios scripts cron o automatización PL/SQL. La transferencia de contraseñas de texto no cifrado es un problema de conformidad que se aborda en el procedimiento UTL_HTTP.SET_CREDENTIAL.

Consulte Procedimiento SET_AUTHENTICATION y Procedimiento SET_AUTHENTICATION_FROM_WALLET para obtener más información.

Sintaxis de 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);

Ejemplo para transferir un objeto de credencial en el procedimiento SET_CREDENTIAL:

• Cree un objeto de credencial:

  BEGIN DBMS_CLOUD.CREATE_CREDENTIAL (
      credential_name => 'HTTP_CRED',
      username        => 'web_app_user',
      password        => '<password>' );
  END;

  Esto crea un objeto de credencial que crea un par de nombre de usuario/contraseña almacenado.

  Consulte CREATE_CREDENTIAL Procedure para obtener más información.

  Consulte Especificación de Credenciales de Trabajo del Planificador para obtener más información.

• Llame al procedimiento 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;
  

  En este ejemplo, primero se crea una solicitud llamando al procedimiento BEGIN_REQUEST y se define la información de autenticación HTTP en la cabecera de solicitud HTTP llamando al procedimiento SET_CREDENTIAL. El servidor web necesita esta información para autorizar la solicitud. El valor l_http_request es la solicitud HTTP, HTTP_CRED es el nombre de las credenciales y BASIC es el esquema de autenticación HTTP.

Consulte UTL_HTTP para obtener más información.

Consulte las Notas del paquete PL/SQL para la base de datos de IA autónoma para obtener información sobre las restricciones para UTL_HTTP en la base de datos de IA autónoma.

Al utilizar los comandos SQL de Oracle APEX o la hoja de trabajo SQL de Database Actions para ejecutar varios comandos SQL secuenciales, los comandos se pueden ejecutar en diferentes sesiones de base de datos que no guardan el estado de una sentencia anterior. Este comportamiento difiere de los clientes SQL de escritorio, como SQL*Plus y SQL Developer, que mantienen una conexión persistente a la base de datos.

Los envíos de hojas de trabajo SQL de comandos SQL y acciones de base de datos de Oracle APEX a una instancia de base de datos de IA autónoma no tienen estado. Esto significa que la ejecución de sentencias SQL y PL/SQL individuales puede ahorrar estado en la memoria de la base de datos, por ejemplo, al ejecutar un comando para utilizar una cartera, pero el estado se puede borrar antes de ejecutar la siguiente sentencia.

Consulte la siguiente tabla para ver los pasos para mantener el estado de la memoria de la base de datos entre ejecuciones de sentencias para los comandos SQL que envíe a la base de datos de IA autónoma.

Por ejemplo, utilice el siguiente bloque de código para ejecutar un comando utl_http.request() que utilice una cartera gestionada por el cliente:

SELECT utl_http.request(url => 'https://api.example.com/', wallet_path => 'file:path_to_wallet', wallet_password => 'password' ) FROM DUAL";

Compare esto con la ejecución con dos sentencias consecutivas que podrían fallar si el comando utl_http.set_wallet() y la sentencia utl_http.request() se ejecutan de forma individual, en lugar de como un único bloque de código:

EXEC utl_http.set_wallet('file:WALLET_DIR/wallet.sso', 'password');
SELECT utl_http.request('https://api.example.com/') FROM DUAL;

Puede configurar su base de datos de IA autónoma para que envíe información de identidad de base de datos como cabeceras HTTP personalizadas al realizar solicitudes HTTP salientes.

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS = '[
"DATABASE_NAME",
"REGION",
"DATABASE_OCID"
]';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS = '[
"DATABASE_NAME",
"REGION",
"TENANT_OCID",
"DATABASE_OCID",
"COMPARTMENT_OCID",
"CLOUD_DOMAIN",
"CLIENT_IP_ADDRESS"
]';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS_DOMAINS = '*';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS_DOMAINS = 'objectstorage.oraclecloud.com';

ALTER DATABASE PROPERTY SET DATABASE_IDENTITY_NETWORK_HEADERS_DOMAINS = 'oraclecloud.com, example.com';

X-ADB-Source-Database=
  {"databaseName":"MYDATABASENAME",
   "region":"region_identifier",
   "tenantOcid":"tenant_ocid",
   "databaseOcid":"database_ocid",
   "compartmentOcid":"compartment_ocid",
   "clientIpAddress":"client_ip_address"}