Llamada a servicios web desde Autonomous Database

Describe las opciones para llamar a servicios web desde Autonomous Database.

Hay una serie de opciones para llamar a servicios web desde Autonomous Database, incluidas las siguientes:

  • Utilice las API de REST DBMS_CLOUD: la función DBMS_CLOUD.SEND_REQUEST inicia una solicitud HTTP, obtiene la respuesta y finaliza la respuesta. Esta función proporciona un flujo de trabajo para enviar una solicitud de API de REST en la nube con argumentos y la función devuelve un código de respuesta y una carga útil. Consulte SEND_REQUEST Función y procedimiento para obtener más información.

  • Utilice Oracle APEX: puede interactuar con servicios web de estilo SOAP y RESTful desde APEX en su instancia de Autonomous Database. Consulte Uso de servicios web con Oracle APEX para obtener más información.

  • Utilice UTL_HTTP para enviar una solicitud a un sitio público: consulte Envío de una Solicitud HTTP a un Host Público para obtener más información.

  • Utilice UTL_HTTP para enviar una solicitud a un sitio privado: consulte Envío de una solicitud HTTP a un host privado para obtener más información.

    Cuando la instancia de Autonomous Database está en un punto final privado, puede utilizar una cartera gestionada por el cliente con procedimientos en UTL_HTTP, DBMS_LDAP, UTL_SMTP o UTL_TCP. Consulte Realización de llamadas externas mediante una cartera gestionada por el cliente para obtener más información.

Consulte las Notas del paquete PL/SQL para Autonomous Database para obtener información sobre las restricciones de UTL_HTTP en Autonomous Database.

Temas

Envío de una Solicitud HTTP a un Host Público

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

Si la instancia de Autonomous Database está en un punto final privado y desea que las llamadas UTL_HTTP a los hosts públicos estén sujetas a las reglas de salida de la VCN del punto final privado, defina la propiedad de base de datos ROUTE_OUTBOUND_CONNECTIONS en PRIVATE_ENDPOINT.

Consulte Seguridad mejorada para conexiones salientes con puntos finales privados para obtener más información.

Consulte las Notas del paquete PL/SQL para Autonomous Database para obtener información sobre las restricciones de UTL_HTTP en Autonomous Database.

Envío de una solicitud HTTP a un host privado

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 Autonomous Database 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 ROUTE_OUTBOUND_CONNECTIONS en PRIVATE_ENDPOINT, 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 Autonomous Database para obtener información sobre las restricciones de UTL_HTTP en Autonomous Database.

Enviar una solicitud HTTP a un sitio privado con un proxy

Cuando la instancia de Autonomous Database está en un punto final privado, puede utilizar un proxy para enviar solicitudes HTTP con UTL_HTTP.

Cuando la instancia de Autonomous Database está en un punto final privado, para utilizar UTL_HTTP con un proxy de destino, se debe poder acceder al proxy de destino desde la VCN de Oracle Cloud Infrastructure de la base de datos de origen.

Por ejemplo, puede conectarse mediante un proxy cuando:

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

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

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

También puede realizar llamadas UTL_HTTP mediante una cartera gestionada por el cliente. Consulte Realización de llamadas externas mediante una cartera gestionada por el cliente para obtener más información.

Para utilizar un servidor proxy 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 ROUTE_OUTBOUND_CONNECTIONS en PRIVATE_ENDPOINT, 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;

Notas para definir un servidor proxy con UTL_HTTP.SET_PROXY:

  • Las solicitudes DBMS_CLOUD no respetan el servidor proxy definido con UTL_HTTP.SET_PROXY. Esto incluye DBMS_CLOUD.SEND_REQUEST y todo el acceso de almacenamiento de objetos para las tablas externas DBMS_CLOUD que defina con DBMS_CLOUD.CREATE_EXTERNAL_TABLE, DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE o DBMS_CLOUD.CREATE_HYBRID_PART_TABLE.

  • Las solicitudes APEX_WEB_SERVICE no respetan el servidor proxy definido con UTL_HTTP.SET_PROXY.

Consulte las Notas del paquete PL/SQL para Autonomous Database para obtener información sobre las restricciones de UTL_HTTP en Autonomous Database.

Uso de Objetos de Credenciales para Definir la Autenticación HTTP

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 Autonomous Database para obtener información sobre las restricciones de UTL_HTTP en Autonomous Database.

Notas para el envío de solicitudes HTTP con Oracle APEX o Database Actions

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 comandos SQL de Oracle APEX y los envíos de hojas de trabajo SQL de Database Actions a una instancia de Autonomous Database 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 necesarios para mantener el estado de memoria de la base de datos entre ejecuciones de sentencias para los comandos SQL que envíe a Autonomous Database.

Herramienta de comandos SQL Enviar sentencias como bloque
Hoja de trabajo SQL de Database Actions
  • Seleccione todas las sentencias y haga clic en Ejecutar sentencia.
  • No seleccione nada y haga clic en Ejecutar como script SQL
Comandos SQL de Oracle APEX

Los comandos SQL de APEX solo soportan la ejecución de sentencias individuales. Cuando desea ejecutar varias sentencias, debe encapsular las sentencias en un único bloque anónimo PL/SQL. Para ejecutar el bloque con los comandos SQL de APEX, haga clic en Run.

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;