Llamada a funciones en la nube y procedimientos externos

En una instancia local de Oracle Database (Enterprise, Standard, Express, Personal Editions), puede escribir funciones definidas por el usuario en PL/SQL, Java o C para proporcionar una funcionalidad que no está disponible en las funciones incorporadas de SQL o SQL. Puede llamar a estas funciones definidas por el usuario en una sentencia SQL siempre que se produzca una expresión. Consulte Acerca de las funciones definidas por el usuario.

Desde Oracle Database 19c en adelante, puede crear, almacenar y ejecutar scripts de Python mediante la función de ejecución de Python incrustada en SQL. Consulte Ejecución de Python incrustada mediante OML4Py.

Oracle Autonomous AI Database on Dedicated Exadata Infrastructure amplía la capacidad de funciones definidas por el usuario a la nube al permitirle escribir funciones SQL que llamen a servicios informáticos sin servidor en la nube, como OCI Functions y AWS Lambda Functions, o procedimientos externos, que incluyen rutinas C/C++, scripts Shell o Python, que se ejecutan en una máquina virtual de recursos informáticos de OCI externa a la base de datos de IA autónoma.

Acerca de las funciones en la nube y los procedimientos externos

Las funciones definidas por el usuario permiten llamar a funciones disponibles externamente desde código PL/SQL o SQL dentro de la base de datos. Puede llamar a las siguientes funciones externas mediante funciones definidas por el usuario:

• Oracle Cloud Infrastructure Functions: Oracle Cloud Infrastructure Functions es una plataforma de funciones como servicio totalmente gestionada, multiinquilino, altamente escalable y a demanda. Oracle Cloud Infrastructure Functions se basa en Oracle Cloud Infrastructure de nivel empresa y cuenta con el motor de código abierto Fn Project. Consulte Visión general de OCI Functions para obtener más información.

• Funciones Lambda de AWS: AWS Lambda es un servicio de recursos informáticos sin servidor y controlado por eventos que le permite ejecutar código para prácticamente cualquier aplicación o servicio de backend sin aprovisionar ni gestionar servidores. Consulte AWS Lambda para obtener más información.

• Procedimientos externos: los procedimientos externos son funciones escritas en un lenguaje de tercera generación (C, por ejemplo), scripts de shell del sistema operativo o scripts de Python que se pueden llamar como funciones SQL o procedimientos o funciones PL/SQL. Consulte Definición de Procedimiento Externo para obtener más información.

Llamada a OCI Cloud Functions como funciones SQL

Muestra los pasos para llamar a las funciones en la nube de OCI como funciones SQL en su base de datos de IA autónoma en una infraestructura de Exadata dedicada.

Antes de continuar con estos pasos, se supone que ha creado y desplegado OCI Functions en un arrendamiento y compartimento de OCI. Consulte Funciones de OCI para obtener más información.

Una vez que haya trabajado con las funciones de OCI, utilizará las API PL/SQL DBMS_CLOUD y DBMS_CLOUD_FUNCTION para crear un catálogo de funciones de envoltorio SQL en la base de datos de IA autónoma que hagan referencia a sus respectivas funciones en la nube y las llamen a través de sus puntos finales de API. Utilizará la API DBMS_CLOUD_FUNCTION para gestionar las funciones desde la aplicación de la base de datos.

1. Cree credenciales mediante el procedimiento DBMS_CLOUD.CREATE_CREDENTIAL.

   Proporcione la clave privada de API del usuario del arrendamiento de OCI (contenido del archivo dot-pem que ha descargado al crear la clave de API) como el objeto de credencial, la huella de la clave, el OCID del arrendamiento y el OCID del usuario. Consulte Claves y OCID necesarios.

    SET DEFINE OFF
    BEGIN
      DBMS_CLOUD.CREATE_CREDENTIAL (
           credential_name => 'OCI_CRED', -- provide a string as the name
           user_ocid       => 'user_ocid', -- provide the OCID string for the user, obtained from OCI Console User Profile
           tenancy_ocid    => 'tenancy_ocid', -- provide the OCID string for the tenancy, obtained from OCI Console User Profile
           private_key     => 'private_key', -- provide the content of the dot-pem file that you downloaded when you created the API Key
           fingerprint     => 'fingerprint' -- provide the fingerprint string for the API key
      );
    END;
    /
   

   Esto crea el objeto de credencial OCI_CRED.

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

2. Cree un objeto de catálogo mediante el procedimiento DBMS_CLOUD_FUNCTION.CREATE_CATALOG.

   Un catálogo es una recopilación de funciones de envoltorio que hacen referencia a sus respectivas funciones en la nube y las llaman a través de sus puntos finales de API. Proporcione el objeto de credencial, el nombre del proveedor de servicios en la nube, en este caso OCI, el ID de región de OCI (PHX en este ejemplo) y el ID de compartimento de OCI en el que se encuentran las funciones de OCI.

    BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
        credential_name  => 'OCI_CRED',
        catalog_name     => 'OCI_DEMO_CATALOG',
        service_provider => 'OCI',
        cloud_params     => '{"region_id":"phx", "compartment_id":"compartment_id"}'
    );
    END;
    /
   

   Esto crea el objeto de catálogo OCI_DEMO_CATALOG.

   Consulte Procedimiento CREATE_CATALOG para obtener más información. Puede consultar la vista DBA_CLOUD_FUNCTION_CATALOG y la vista USER_CLOUD_FUNCTION_CATALOG para recuperar la lista de todos los catálogos de funciones en la nube de la base de datos.

3. Puede mostrar todas las funciones en la nube del catálogo mediante el procedimiento DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS.

    SET PAGESIZE 1000
   
    VAR function_list CLOB;
   
    BEGIN
        DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS (
          credential_name  => 'OCI_CRED',
          catalog_name     => 'OCI_DEMO_CATALOG',
          function_list    => :function_list
     );
    END;
    /
   

    SELECT JSON_QUERY (:function_list, '$' RETURNING VARCHAR2(32676) pretty) AS search_results FROM dual;
   

    SEARCH_RESULTS
   
    ------------------------------------------------------------------------------------------------ [
      {
        "functionName"   : "create_par",
        "functionId"     : "ocid.funfc.oc1.phx.aaaa_example",
        "invokeEndpoint" : "https://dw.us.func.oci.oraclecloud_example.com"
      },
      {
        "functionName"   : "fintech",
        "functionId"     : "ocid.funfc.oc1.phx.bbbb_example"
        "invokeEndpoint" : "https://dw.us.func.oci.oraclecloud.com_example"
      },
      {
        "functionName"   : "jwt_codec",
        "functionId"     : "ocid.funfc.oc1.phx.jwt_code_example",
        "invokeEndpoint" : "https://dw.us.func.oci.oraclecloud_example.com"
      },
      {
        "functionName"   : "oci-objectstorage-create-par-python",
        "functionId"     : "ocid.funfc.oc1.phx.aaaaaaaas_example",
        "invokeEndpoint" : "https://dw.us.func.oci.oraclecloud_example.com"
      },
      {
        "functionName"   : "run_dbt",
        "functionId"     : "ocid.funfc.oc1.phx.aaaaaaaav_example",
        "invokeEndpoint" : "https://dw.us.func.oci.oraclecloud_example.com"
      }
    ]
   

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

4. Cree la función SQL Wrapper. Puede utilizar uno de los dos métodos siguientes para crear las funciones SQL de encapsulador desde el catálogo, que llaman a sus respectivas funciones en la nube:

   • Puede utilizar DBMS_CLOUD_FUNCTION. SYNC_FUNCTIONS Procedimiento para generar envoltorios SQL desde el objeto de catálogo.

   • Puede crear manualmente funciones de envoltorio individuales mediante DBMS_CLOUD_FUNCTION. Procedimiento CREATE_FUNCTION.

   1. SYNC_FUNCTIONS: SYNC_FUNCTIONS sincroniza automáticamente (crea y/o actualiza) las funciones de envoltorio en el catálogo con la lista completa de funciones en la nube definidas en la región, el compartimento y el arrendamiento con los que se creó el catálogo.

       BEGIN
        DBMS_CLOUD_FUNCTION.SYNC_FUNCTIONS (
               catalog_name => 'OCI_DEMO_CATALOG'
        );
       END;
       /
      

      Esto crea un envoltorio PL/SQL para agregar nuevas funciones al catálogo y eliminar envoltorios para las funciones que se han suprimido del catálogo.

      Puede verificar los resultados de sincronización mediante la siguiente consulta para un usuario actual determinado.

       SHOW user
      

       TEST_USER
      

       SELECT object_name FROM sys.all_objects WHERE owner='TEST_USER' AND object_type='FUNCTION';
      

       OBJECT_NAME
      
       --------------------------------------------------------------------------------
       CREATE_PAR
       FINTECH
       JWT_CODEC
       OCI-OBJECTSTORAGE-CREATE-PAR-PYTHON
       RUN_DBT
      

      Consulte el procedimiento SYNC_FUNCTIONS para obtener más información.

   2. CREATE_FUNCTION: puede crear manualmente una función SQL en el catálogo que llame a su función en la nube respectiva mediante DBMS_CLOUD.CREATE_FUNCTION.

       VAR function_args CLOB;
      
       EXEC :function_args := TO_CLOB('{"command": "VARCHAR2", "value": "VARCHAR2"}');
      
       BEGIN
           DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
               credential_name  => 'OCI_CRED',
               catalog_name     => 'OCI_DEMO_CATALOG',
               function_name    => 'FINTECH_FUNCTION',
               function_id      => 'ocid1.fnfunc.oc1.phx.aaabbbcccc_example',
               input_args       => :function_args
        );
       END;
       /
      

      Esto crea la función FINTECH_FUN en el catálogo OCI_DEMO_CATALOG, como referencia a la función en la nube respectiva a la que hace referencia el parámetro FUNCTION_ID al punto final. La llamada a la función en el catálogo junto con sus argumentos ejecuta la función en la nube correspondiente en OCI y proporciona la salida devuelta por la función en la nube.

      Nota: El nombre de la función de OCI puede ser algo completamente diferente de FINTECH_FUNCTION. Solo se tiene en cuenta el OCID de la función de OCI que proporcione como entrada para el parámetro function_id para crear esta referencia.

   3. CREATE_FUNCTION con tipos de retorno personalizados y manejadores de respuestas: la creación manual de funciones permite crear tipos de retorno personalizados y manejadores de respuestas, y se muestra en el siguiente ejemplo.

      Primero, cree un tipo de retorno y el manejador de respuestas de la función.

       CREATE OR REPLACE TYPE fintech_rt AS OBJECT (
           status VARCHAR2(1000),
           output CLOB
       );
       /
      

       Type created.
      

       CREATE OR REPLACE FUNCTION fintech_response_handler(function_response IN CLOB)
       RETURN fintech_rt
       IS
             l_comp     fintech_rt;
             l_json_obj JSON_OBJECT_T;
             status     VARCHAR2(1000);
             output     CLOB;
       BEGIN
             l_json_obj := JSON_OBJECT_T.parse(function_response);
             status     := l_json_obj.get('STATUS').to_string;
             output     := l_json_obj.get('RESPONSE_BODY').to_string;
             l_comp     := fintech_rt(status,output);
             RETURN l_comp;
       END;
       /
      

       Function created.
      

      A continuación, utilice este tipo y manejador de respuestas durante la creación manual de la función de envoltorio SQL.

       VAR input_param CLOB;
       VAR l_return_type VARCHAR2(100);
       VAR l_response_handler VARCHAR2(1000);
      
       -- Define function parameters
       exec :input_param       := TO_CLOB('{"command": "VARCHAR2", "value": "VARCHAR2"}');
      

       PL/SQL procedure successfully completed.
      

       exec :l_return_type     := 'fintech_rt';
      

       PL/SQL procedure successfully completed.
      

       exec :l_response_handler := 'fintech_response_handler';
      

       PL/SQL procedure successfully completed.
      

       BEGIN
           DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
               credential_name  => 'OCI_CRED',
               catalog_name     => 'OCI_DEMO_CATALOG',
               function_name    => 'FINTECH_FUNCTION',
               function_id      => 'ocid1.fnfunc.oc1.phx.aaabbbcccc_example',
               input_args       => :input_param,
               return_type      => :l_return_type,
               response_handler => :l_response_handler
        );
       END;
       /
      

      Puede consultar la vista DBA_CLOUD_FUNCTION y la vista USER_CLOUD_FUNCTION para recuperar la lista de todas las funciones de la base de datos.

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

      Una vez creada la función, puede DESCRIBIR la función para obtener los detalles de devolución.

       DESC fintech_fun
       COLUMN STATUS format a30
       COLUMN OUTPUT format a30
      

      A continuación, puede llamar a la función, proporcionando los valores para los parámetros de entrada.

       SET SERVEROUTPUT ON
      
       DECLARE
           l_comp fintech_rt;
       BEGIN
           l_comp := fintech_fun(command=>'tokenize',value => 'PHI_INFORMATION');
      
           DBMS_OUTPUT.put_line ('Status of the function   =  '|| l_comp.status);
           DBMS_OUTPUT.put_line ('Response of the function =  '|| l_comp.output);
       END;
       /
      

      Esto llama a la función en la nube fintech_fun llamando a la referencia de función oocid1.funfn.oci.phx.aaaaaa_example en el catálogo OCI_DEMO_CATALOG.

5. Puede borrar una función existente mediante el procedimiento DROP_FUNCTION.

    BEGIN
        DBMS_CLOUD_FUNCTION.DROP_FUNCTION (
            catalog_name  => 'OCI_DEMO_CATALOG',
            function_name => 'fintech_fun');
    END;
    /
   

   Esto borra la función FINTECH_FUN del catálogo OCI_DEMO_CATALOG.

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

6. Puede borrar un catálogo existente mediante el procedimiento DROP_CATALOG.

    BEGIN
        DBMS_CLOUD_FUNCTION.DROP_CATALOG (
            catalog_name => 'OCI_DEMO_CATALOG'
      );
    END;
    /
   

   Esto borra OCI_DEMO_CATALOG de la base de datos.

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

Llamada a funciones Lambda de AWS como funciones SQL

Muestra los pasos para llamar a funciones remotas de AWS como funciones SQL en su base de datos de IA autónoma en una infraestructura de Exadata dedicada.

Antes de continuar con estos pasos, se supone que ha creado e implementado AWS Lambda Functions en un arrendamiento de AWS. Consulte AWS Lambda para obtener más información.

Para acceder a las funciones lambda de AWS, debe configurar las políticas necesarias en Oracle Cloud Infrastructure. Consulte Creación de una política de IAM para acceder a los recursos de AWS Lambda y Uso de políticas basadas en recursos para Lambda para obtener más información.

Una vez que haya trabajado con las funciones Lambda de AWS, utilizará las API PL/SQL DBMS_CLOUD y DBMS_CLOUD_FUNCTION para crear un catálogo de funciones de envoltorio SQL en la base de datos de IA autónoma que hacen referencia a sus respectivas funciones en la nube y las llaman a través de sus puntos finales de API. Utilizará la API DBMS_CLOUD_FUNCTION para gestionar las funciones desde la aplicación de la base de datos.

1. Cree una credencial mediante el procedimiento DBMS_CLOUD.CREATE_CREDENTIAL mediante la clave secreta de AWS como objeto de credencial.

    SET DEFINE OFF
   
    BEGIN
      DBMS_CLOUD.CREATE_CREDENTIAL (
        credential_name => 'AWS_CRED',
        username        => 'access_key_ID', -- ID of Secret Key
        password        => 'secret_access_key' -- Secret Key password
      );
    END;
    /
   

   Esto crea el objeto de credencial AWS_CRED.

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

2. Cree un objeto de catálogo mediante el procedimiento DBMS_CLOUD_FUNCTION.CREATE_CATALOG.

   Un catálogo es una recopilación de funciones de envoltorio que hacen referencia a sus respectivas funciones en la nube y las llaman a través de sus puntos finales de API. Proporcione el objeto de credencial, el nombre del proveedor de servicios en la nube, en este caso AWS, y el ID de región de AWS (ap-northeast-1 en este ejemplo) en el que se encuentran las funciones de AWS Lambda.

    BEGIN
        DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
            credential_name  => 'AWS_CRED',
            catalog_name     => 'AWS_DEMO_CATALOG',
            service_provider => 'AWS',
            cloud_params     => '{"region_id":"ap-northeast-1"}'
     );
    END;
    /
   

   Esto crea el objeto de catálogo AWS_DEMO_CATALOG.

   Consulte Procedimiento CREATE_CATALOG para obtener más información. Puede consultar la vista DBA_CLOUD_FUNCTION_CATALOG y la vista USER_CLOUD_FUNCTION_CATALOG para recuperar la lista de todos los catálogos de la base de datos.

   El resto de los pasos/operaciones, es decir, el procedimiento LIST_FUNCTIONS, el procedimiento SYNC_FUNCTIONS, el procedimiento CREATE_FUNCTION, el procedimiento DROP_FUNCTION y el procedimiento DROP_CATALOG, tienen el mismo uso que se describe para las funciones en la nube de OCI. Consulte Llamada a OCI Cloud Functions como funciones SQL.

Descripción general de procedimientos externos

Proporciona una visión general de los procedimientos externos y su uso en aplicaciones de Autonomous AI Database on Dedicated Infrastructure.

Los procedimientos externos son funciones escritas en un lenguaje de tercera generación y que se llaman como funciones SQL o procedimientos o funciones PL/SQL. SQL y PL/SQL son los más adecuados para el procesamiento rápido y eficiente de datos y transacciones en la base de datos. Los procedimientos externos pueden complementar SQL y PL/SQL mediante la ejecución de tareas que hacen un uso intensivo de la memoria y los recursos informáticos en una máquina virtual dedicada y externa, y la devolución de los resultados a la base de datos. Ejemplos típicos de tales tareas son los problemas científicos y de ingeniería cuyas bibliotecas computacionales existen en el sistema operativo Linux (y no se pueden transportar fácilmente a una plataforma de datos), el análisis de datos fuera de línea, el control de dispositivos y procesos en tiempo real, etc.

Puede llamar y utilizar procedimientos externos en su base de datos de IA autónoma con funciones definidas por el usuario. En lugar de ejecutar estos procedimientos dentro de la base de datos, colocará el código ejecutable en una máquina virtual de Linux de OCI dedicada y personalizada que se aprovisiona con un contenedor y tiempo de ejecución para ejecutar programas C, scripts de Shell y scripts de Python, junto con bibliotecas Oracle SQL\*Net para permitir la ejecución remota de SQL desde la base de datos.

Nota: El host remoto para procedimientos externos debe ser una VM de OCI Linux EXTPROC aprovisionada desde OCI Marketplace y configurada en una red virtual en la nube (VCN) de OCI adecuada.

La ejecución remota en OCI Linux EXTPROC VM solo está soportada por Autonomous AI Database en infraestructura de Exadata dedicada en Oracle Public Cloud a partir de la versión 19.30 y en Oracle Database 26ai, a partir de la versión 23.26.1. Esta función aún no está soportada por la base de datos de Autonomous AI Database on Dedicated Exadata Infrastructure en Exadata Cloud@Customer (ExaCC).

Configuración del sistema para procedimientos y secuencias de comandos externos

Muestra los pasos para aprovisionar la máquina virtual EXTPROC y los pasos para configurar la red y los recursos informáticos de OCI para ejecutar procedimientos externos.

Como mínimo, la arquitectura consta de los siguientes recursos:

• Red virtual en la nube de OCI aprovisionada en un compartimento de OCI en el arrendamiento de OCI.

• Una base de datos de IA autónoma, creada como instancia en una base de datos de contenedores autónoma (ACD), que se aprovisiona desde un cluster de VM de Exadata autónomo (AVMC), que se crea en la infraestructura de Exadata en Oracle Public Cloud.

• Una máquina virtual EXTPROC aprovisionada como parte de una pila EXTPROC desde OCI Marketplace.

Como mejor práctica, el cluster de AVM se colocará en una subred privada de una VCN. La tabla de rutas por defecto y las listas de seguridad de la VCN se configurarán según los requisitos de la base de datos de IA autónoma del arrendamiento de OCI. La VCN puede tener una tabla de rutas por defecto y una lista de seguridad por defecto, donde puede definir todas las reglas de enrutamiento y seguridad. Opcionalmente, la VCN se puede configurar con un gateway de NAT si las aplicaciones de base de datos de IA autónoma y otros recursos de la subred privada necesitan acceso de salida a Internet.

Siga estos pasos mínimos de configuración de OCI Networking al introducir la VM de ExtProc en esta topología.

• Debe poder iniciar sesión en su máquina virtual ExtProc para crear la biblioteca compartida (dot-so) con los procedimientos externos implementados en C/C++, inspeccionar y configurar la máquina virtual y el contenedor, y realizar otras operaciones de este tipo.

• La práctica habitual es configurar la máquina virtual EXTPROC para que esté en una subred pública de la VCN. En este caso, debe crear un gateway de Internet en la VCN (si el administrador aún no lo ha configurado).

Nota: La máquina virtual EXTPROC NO debe estar en una subred cuyo rango de CIDR sea 10.x.x.x. Si la dirección IP de la máquina virtual EXPROC es 10.x.x.x, no podrá comunicarse con la base de datos de IA autónoma.

• Debe definir una regla de entrada en la lista de seguridad de la VCN para permitir el acceso de conexión SSH a la máquina virtual mediante el puerto 22. También debe definir una regla de salida en la lista de seguridad de la VCN para permitir que ADBD acceda al puerto de destino 16000 para que sea específico o todos los puertos de destino, en general. Consulte Acceso y seguridad de redes de OCI.

• Como parte del aprovisionamiento de la pila de VM EXTPROC, proporcionará todas las direcciones IP del cliente de AVMC. Obtendrá estas direcciones IP de cliente IPv4 desde el panel de control de OCI para el cluster de AVM.

• Posteriormente, la herramienta de aprovisionamiento creará automáticamente un grupo de seguridad de red (NSG), denominado nsg_acl. Este NSG tendrá una regla de entrada que permitirá a las direcciones IP de cliente dedicado de Autonomous Database como los únicos orígenes que pueden acceder al destino del puerto 16000.

Temas avanzados

• Si las subredes que alojan la VM de ExtProc y la base de datos de IA autónoma están en la misma VCN, no es necesario especificar ninguna regla de enrutamiento especial en la tabla de enrutamiento de la VCN. Si las subredes que alojan la VM de ExtProc y ADBD están en redes virtuales en la nube diferentes, debe implantar el intercambio de VCN. Consulte Intercambio de tráfico de VCN.

• Si decide configurar la máquina virtual de ExtProc para que esté en una subred privada, debe poder conectarse a la máquina virtual a través de un servidor bastión/salto, activar la entrada solo en la máquina virtual de ExtProc y proteger el acceso a los demás recursos de la subred privada, como la base de datos de IA autónoma. Consulte las guías de redes de OCI para obtener más información.

Implantación de funciones definidas por el usuario con procedimientos externos

1. Aprovisionamiento y configuración de la máquina virtual EXTPROC desde OCI MarketPlace

   a. Conéctese a la consola de OCI en http://cloud.oracle.com. Para obtener más información, consulte Conexión a la consola de Oracle Cloud Infrastructure.

   b. En el menú de navegación de la izquierda de Oracle Cloud Infrastructure, seleccione Marketplace y, a continuación, en Marketplace, haga clic en Todas las aplicaciones.

   c. Introduzca "EXTPROC" en la barra de búsqueda y haga clic en Search. Verá dos widgets: una pila etiquetada y otra imagen etiquetada.

   d. Seleccione el widget denominado Pila (esto es importante). This will take you to Oracle Autonomous Database EXTPROC Agentdetails page, providing the stack version, release date, and release notes about the Stack. En esta página, haga clic en el botón Iniciar pila. Accederá a la siguiente página Launch Stack.

   e. En la página Launch Stack:

   • En la lista desplegable Versión, seleccione la versión del paquete de la pila.

   • En la lista desplegable Compartimento, seleccione el nombre del compartimento en el que desea aprovisionar la VM EXTPROC. A menos que tenga motivos específicos para no hacerlo, seleccione el mismo compartimento que el de ADBD (en las mejores prácticas, evite el compartimento raíz de cualquier recurso).

   • Acepte los términos y condiciones y haga clic en Iniciar pila.

   Accederá a la página siguiente: Asistente de Creación de Pila.

   f. En esta página, proporcione un nombre, una descripción, un nombrede compartimento, la versión de Terraform y cualquier información de etiqueta. El nombre del compartimento es una entrada obligatoria, y lo más importante, en el asistente de esta página. Haga clic en Siguiente.

   g. Esto le llevará a la página de variables de configuración para la máquina virtual EXTPROC (también denominada agente EXTPROC). La primera parte de esta página recopila la información sobre las bibliotecas EXTPROC y una contraseña de cartera.

   • Para Bibliotecas externas, proporcione una lista de las bibliotecas, separadas por comas (,), que desea que se puedan llamar desde la base de datos de IA autónoma en la infraestructura dedicada. Estas bibliotecas compartidas contendrán los procedimientos externos escritos en C/C++, que se compilan y construyen idealmente en la propia máquina virtual (para que coincidan con la arquitectura y el entorno).

     Nota: Dado que aún está creando la máquina virtual EXTPROC, anote los nombres de las bibliotecas compartidas que proporciona aquí. Cuando la máquina virtual está disponible y desarrolla los procedimientos externos en C/C++, debe recordar compilar y crear la biblioteca/bibliotecas con los nombres exactos proporcionados anteriormente.

   • Para Contraseña de cartera, proporcione una contraseña para el archivo de cartera que se creará en la VM de ExtProc. La cartera y un certificado autofirmado se generan para la autenticación TLS mutua entre la base de datos de IA autónoma en infraestructura dedicada y la máquina virtual del agente EXTPROC.

   h. La segunda parte de la página de variables de configuración implica la configuración de red para la máquina virtual EXTPROC.

   • En Compartimento, seleccione el nombre del compartimento para la VCN en el menú desplegable. En el ejemplo anterior, se muestra como adbd. Idealmente, la base de datos de IA autónoma y la máquina virtual EXTPROC se colocarán en la misma VCN, incluso si se encuentran en subredes diferentes (privadas y públicas).

   • En Estrategia de red, seleccione "Usar VCN y subred existentes". Como se ha indicado en una sección anterior, en esta etapa de su esfuerzo de desarrollo de ExtProc, puede tener la arquitectura del sistema en su lugar con una VCN, AVMC y una base de datos de IA autónoma.

     Nota: La otra opción es crear una nueva VCN y una subred con su propia estrategia de configuración para el agente de VM EXTPROC. Si decide colocar la VM EXTPROC en una VCN diferente a la de la base de datos de IA autónoma, debe parar las VCN.

   • Omita la siguiente entrada para EXTPROC Agent Access Type. Este campo no se aplica a la base de datos de IA autónoma en una infraestructura de Exadata dedicada.

   i. A continuación, en el campo con la etiqueta "Direcciones IP de punto final privado", introduzca TODAS las direcciones IP de cliente del AVMC en el que está configurada la base de datos. Puede obtener estas direcciones IP de cliente desde el panel de control de la consola de OCI para AVMC.

   • Para Red virtual en la nube, proporcione el nombre de la VCN en la que desea crear el agente de VM EXTPROC.

   • Para la subred EXTPROC, proporcione el nombre de la subred en la que desea crear el agente de VM EXTPROC.

   j. A continuación, proporcione los detalles de la VCN y la subred.

   Nota: La máquina virtual EXTPROC NO debe estar en una subred cuyo rango de CIDR sea 10.x.x.x. Si la dirección IP de la máquina virtual EXPROC es 10.x.x.x, no podrá comunicarse con la base de datos de IA autónoma.

   k. La parte final de la página de configuración implica la configuración de recursos informáticos para el agente de VM EXTPROC.

   • En Compartimento, seleccione el nombre del compartimento en el menú desplegable. Se recomienda colocar la máquina virtual en el mismo compartimento que la base de datos de IA autónoma en una infraestructura dedicada, la VCN y la subred para minimizar la resolución de problemas.

   • Para Unidad, Número de OCPU y Tamaño de memoria (GB), introduzca valores basados en las características de carga de trabajo de los procedimientos externos.

   • Para Agregar claves SSH, genere los archivos de claves SSH públicas y privadas en el sistema operativo Linux, MacOS o Windows. Abra una ventana de terminal y ejecute uno de los siguientes comandos (ED25519 es el algoritmo moderno y seguro; los sistemas más antiguos admiten el algoritmo de cifrado RSA):

     ssh-keygen -t ed25519 -C "[e-mail]" (OR)
     ssh-keygen -t rsa -b 4096 -C "[e-mail]"
     

     Esto generará un archivo de clave privada ssh-key-<date-time-id>.key y un archivo de clave pública ssh-key-<date-time-id>.key.pub. Copie y pegue el contenido de la clave pública SSH en la ventana o arrastre y suelte el archivo .pub en la ventana.

   • Haga clic en Siguiente.

   l. Accederá a la página Review. Revise todas las entradas y, a continuación, seleccione la casilla de control Ejecutar aplicación y haga clic en Crear.

   Esto iniciará OCI Resource Manager para crear la pila de VM EXTPROC. Una vez que el trabajo de ORM se haya completado correctamente, se creará y ejecutará la máquina virtual EXTPROC.

2. Recopilar información del sistema de VM EXTPROC para la entrada de API DBMS_CLOUD_FUNCTION

   Debe proporcionar la información del sistema de máquina virtual EXTPROC como entradas a las API DBMS_CLOUD_FUNCTION en la base de datos de IA autónoma para permitir la llamada de procedimientos externos desde la base de datos.

   a. En el menú de navegación de la izquierda de Oracle Cloud Infrastructure, en la lista desplegable de Compute, seleccione el compartimento que ha especificado para el aprovisionamiento de VM EXTPROC y revise el panel de control que muestra todas las VM del compartimento. El trabajo de ORM habrá creado la VM EXTPROC con un nombre canónico EXTPROC-agent o EXTPROC-agent-<setofnumbers>. Este será el nombre de host de la instancia de VM de EXTPROC. Al hacer clic en esta entrada, accederá a la página que muestra los detalles del sistema: las direcciones IPV4 públicas y privadas (IPv4 e IPv6), la subred y los detalles de la imagen.

   b. Inicie sesión en la VM de ExtProc mediante la clave SSH que proporcionó durante la creación de la pila de ExtProc y la dirección IP. El usuario por defecto de la máquina virtual es opc. sudo para convertirse en usuario oracle.

    ~ ssh -i ssh-key-<date-time-id>.key opc@<Public-IP-Address>
   

    Wed Nov 19 10:46:25 GMT 2025: EXTPROC Agent intialization completed.
   
    Activate the web console with: systemctl enable --now cockpit.socket
       
    Last login: Thu Nov 20 20:10:54 2025 from  <client-IP-address>
   

    [opc@extproc-agent-170798 ~]$ whoami
   

    opc
   
    [opc@extproc-agent-170798 ~]$ sudo su - oracle
    Last login: Wed Nov 19 19:07:24 GMT 2025 on pts/0
   

   La máquina virtual EXTPROC tendrá un contenedor Podman en ejecución con un listener de Oracle SQL*Net. Dentro del contenedor, estará disponible un entorno de cliente de Oracle con los archivos de configuración necesarios, como sqlnet.ora, listener.ora, junto con un archivo de cartera para una comunicación segura con la base de datos de IA autónoma.

   c. Recopile la información del sistema necesaria para las API de PL/SQL: en el nivel del sistema operativo y, a continuación, desde el contenedor de Podman configurado en la máquina virtual. El contenedor ejecuta Oracle Listener para recibir solicitudes de ejecución remota de la aplicación SQL y PL/SQL en Autonomous AI Database y es el motor de ejecución en tiempo de ejecución del procedimiento externo.

   • Desde el sistema operativo Linux, el FQDN (nombre de dominio completo) del host de VM EXTPROC.

   • Desde el contenedor Podman, desde el estado del listener, el puerto de la máquina virtual EXTPROC en el que la base de datos se conecta a la máquina virtual.

   • Desde el contenedor Podman, desde la especificación sqlnet.ora, la ubicación del archivo de cartera.

   • En una inspección del archivo de cartera mediante la herramienta orapki, el valor del parámetro Nombre distintivo (DN) para el certificado de cartera.

    [oracle@extproc-agent-170798 ~]$ hostname -f
    extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com
   
    [oracle@extproc-agent-170798 ~]$ podman ps
    CONTAINER ID  IMAGE                              COMMAND     CREATED       STATUS                 PORTS       NAMES
    86d81c4df6ff  ghcr.io/oracle/adb-extproc:latest              23 hours ago  Up 23 hours (healthy)              adb-extproc
   
    [oracle@extproc-agent-170798 ~]$ podman exec -it 86d81c4df6ff bash
   
    (base) [oracle@extproc-agent-170798 admin]$ lsnrctl status
   
    LSNRCTL for Linux: Version 23.26.0.0.0 - for Oracle Cloud and Engineered Systems on 20-NOV-2025 09:25:54
   
    Copyright (c) 1991, 2025, Oracle.  All rights reserved.
   
    Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=IPC)(KEY=EXTPROC1)))
    STATUS of the LISTENER
   
    ------------------------
    Alias                     LISTENER
    Version                   TNSLSNR for Linux: Version 23.26.0.0.0 - for Oracle Cloud and Engineered Systems
    Start Date                19-NOV-2025 17:19:58
    Uptime                    0 days 16 hr. 5 min. 55 sec
    Trace Level               off
    Security                  ON: Local OS Authentication
    SNMP                      OFF
    Listener Parameter File   /u01/app/oracle/product/23.0.0.0/client_1/network/admin/listener.ora
    Listener Log File         /u01/app/oracle/diag/tnslsnr/extproc-agent-170798/listener/alert/log.xml
    Listening Endpoints Summary...
      (DESCRIPTION=(ADDRESS=(PROTOCOL=ipc)(KEY=EXTPROC1)))
      (DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=0.0.0.0)(PORT=16000)))
    Services Summary...
    Service "extproccontainer.com" has 1 instance(s).
      Instance "extproccontainer", status UNKNOWN, has 1 handler(s) for this service...
     The command completed successfully
   
    (base) [oracle@extproc-agent-170798 /]$ cd $ORACLE_HOME/network/admin
   
    (base) [oracle@extproc-agent-170798 admin]$ cat sqlnet.ora
   
    NAMES.DIRECTORY_PATH= (TNSNAMES, EZCONNECT)
    WALLET_LOCATION =(SOURCE = (METHOD = FILE)(METHOD_DATA = (DIRECTORY = /u01/app/oracle/wallets/extproc_wallet)))
    tcp.invited_nodes=(20.63.19.141,20.63.19.141,20.63.19.143,20.63.19.144)
    tcp.validnode_checking=yes
   
    (base) [oracle@extproc-agent-170798 admin]$ orapki wallet display -wallet /u01/app/oracle/wallets/extproc_wallet/cwallet.sso
    Oracle PKI Tool Release 23.0.0.0.0 - Production
    Version 23.0.0.0.0
    Copyright (c) 2004, 2025, Oracle and/or its affiliates. All rights reserved.
   
    Requested Certificates:
    User Certificates:
    Subject:        CN=extproc-agent-170798
    Trusted Certificates:
    Subject:        CN=extproc-agent-170798
    (base) [oracle@extproc-agent-170798 admin]$ exit
    exit
   

   En el ejemplo anterior, hemos recopilado las siguientes entradas para la API DBMS_CLOUD_FUNCTION.CREATE_CATALOG.

   • La cadena formada por FQDN + número de puerto será la entrada para el parámetro library_listener_url. En este ejemplo, es 'extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com:16000'.

   • sqlnet.ora contiene la ubicación del archivo de cartera en la máquina virtual: /u01/app/oracle/wallets/extproc_wallet/cwallet.sso. Tenga en cuenta la lista de direcciones IP para tcp.invited_nodes. Debe contener la lista de direcciones IP de cliente que proporcionó como entrada para la configuración de red al crear la pila de VM EXTPROC.

   • El nombre distintivo (DN) del certificado será la entrada para el parámetro library_ssl_server_cert_dn: 'CN=extproc-agent-170798'.

3. Cree la biblioteca C y colóquela en la ubicación especificada en el sistema de archivos de máquina virtual EXTPROC

   Codificar las funciones C, crearlas y colocar la biblioteca en el directorio designado en el sistema de archivos de la máquina virtual del agente ExtProc.

   El nombre de la biblioteca debe coincidir exactamente con los nombres que proporcionó durante la creación de la pila ExtProc. En caso de que la haya extraviado, puede encontrarla en la entrada EXTPROC_DLLS del archivo initextproccontainer.ora del contenedor ExtProc, como se muestra a continuación, o en la sección "Variables" del trabajo ORM (Oracle Resource Manager) que creó la pila ExtProc. Debe copiar las bibliotecas en el directorio /u01/app/oracle/extproc_libs de la máquina virtual del agente EXTPROC.

   • El nombre completo de la ruta de acceso del archivo (en este ejemplo "/u01/app/oracle/extproc_libs/helloCextproc.so") será la entrada del parámetro library_remote_path de DBMS_CLOUD_FUNCTION.CREATE_CATALOG().

    (base) [oracle@extproc-agent-170798 client_1]$ cat $ORACLE_HOME/hs/admin/initextproccontainer.ora
    SET TRACE_LEVEL=ON
    SET _EXTPROC_REMOTE=TRUE
    SET WHOAMI=FROMDOCKER
    SET LD_LIBRARY_PATH=/u01/app/oracle/product/23.0.0.0/client_1/lib:/u01/app/oracle/extproc_libs:/opt/conda/lib
    SET EXTPROC_DLLS=ONLY:/u01/app/oracle/product/extprocutils.so:/u01/app/oracle/product/23.0.0.0/client_1/lib/libgsfextproc.so:/u01/app/oracle/extproc_libs/helloCextproc.so
    SET PYTHONHOME=/opt/conda
    SET SCRIPTS_FOLDER_LOC_ENV=/u01/app/oracle/extproc_scripts
    SET TRACE_FILE_LOC_ENV=/u01/app/oracle/extproc_logs
    SET PYTHONPATH=/tmp:/u01/app/oracle/extproc_scripts
    (base) [oracle@extproc-agent-170798 client_1]$ exit
   
    [oracle@extproc-agent-170798 ~]$ cat > helloCextproc.c
    #include <stdio.h>
    const char* helloCextproc() {
            return ("\nHello C Extproc from FQDN: extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com\n");
    }
    ^D
   
    [oracle@extproc-agent-170798 ~]$ gcc -shared -fPIC -o /u01/app/oracle/extproc_libs/helloCextproc.so helloCextproc.c
   
    [oracle@extproc-agent-170798 ~]$ ls -al /u01/app/oracle/extproc_libs/
    total 8
    drwxr-xr-x. 2 oracle oinstall   30 Nov 19 11:14 .
    drwxr-xr-x. 6 root   root       91 Nov 14 02:19 ..
   
    -rwxr-xr-x. 1 oracle oinstall 8184 Nov 19 11:14 helloCextproc.so
    [oracle@extproc-agent-170798 ~]$
   

   Esto completará todas las entradas de parámetros que necesitamos para crear el objeto Catálogo/Biblioteca en la aplicación de base de datos.

4. Cargar el archivo de cartera de la VM de ExtProc en OCI Object Storage

   Una cartera autofirmada se crea como parte de la creación de la aplicación del agente EXTPROC. Esta cartera permite acceder a la instancia de agente Extproc.

   Para ejecutar procedimientos remotos en la instancia del agente EXTPROC, la base de datos de IA autónoma y el agente EXTPROC se conectan mediante la seguridad de capa de transporte mutuo (mTLS). Al utilizar la seguridad de capa de transporte mutuo (mTLS), los clientes se conectan a través de una conexión del TCPS (TCP seguro) con un certificado TLS 1.2 con una autoridad de certificado (CA) de cliente (CA) de confianza.

   Nota: También puede obtener y utilizar un certificado público emitido por una autoridad de certificación (CA).

   Como requisito, debe exportar la cartera del directorio /u01/app/oracle/extproc_wallet de la máquina virtual donde se ejecuta EXTPROC a OCI Object Storage.

   Nota:

   • Proteja el archivo de cartera. El archivo de cartera, junto con el ID de usuario y la contraseña de la base de datos, proporcionan acceso a la instancia del agente EXTPROC. Almacene los archivos de cartera en una ubicación segura y compártalos solo con usuarios autorizados.
   • No cambie el nombre del archivo de cartera. El archivo de cartera de Object Storage debe tener el nombre cwallet.sso.

5. Crear el catálogo, definir funciones SQL y llamar a procedimientos externos como funciones SQL

   Desde los pasos anteriores, tenemos todas las entradas que necesitamos para que las API DBMS_CLOUD_FUNCTION ejecuten procedimientos remotos desde aplicaciones de base de datos SQL o PL/SQL.

   A continuación, importe la cartera, cwallet.sso, que contiene los certificados para la instancia del agente EXTPROC de Object Storage a un directorio en su base de datos de IA autónoma.

   Cree una credencial para acceder a Object Storage donde haya almacenado el archivo de cartera cwallet.sso. Consulte Procedimiento CREATE_CREDENTIAL para obtener información sobre los parámetros de nombre de usuario y contraseña para diferentes servicios de almacenamiento de objetos.

   Cree un objeto DIRECTORY en la base de datos y descargue la cartera en el directorio mediante la API DBMS_CLOUD.GET_OBJECT.

     SET DEFINE OFF
   
     BEGIN
      DBMS_CLOUD.CREATE_CREDENTIAL (
        credential_name => 'OCI_CREDENTIAL',
        user_ocid       => '<oci_user_ocid>',
        tenancy_ocid    => '<oci_tenancy_ocid>',
        private_key     => '<API-key-dot-pem-file-contents>',
        fingerprint     => '<fingerprint-created-with-API-key>');
    END;
    /
   
    CREATE DIRECTORY extprocwalletdir AS 'extprocwalletdir';
   

    Directory created.
   

    SELECT directory_name, directory_path FROM dba_directories WHERE directory_name LIKE '%EXTPROC%';
   

    DIRECTORY_NAME    DIRECTORY_PATH
   
    ----------------  -------------------------------------------------------------------------
    EXTPROCWALLETDIR  /u02/data/dbfs/<adbd-name>/42E945D608E16DF9E0630301000AF88D/extprocwalletdir
   

     BEGIN
      DBMS_CLOUD.GET_OBJECT (
      credential_name     => 'OCI_CREDENTIAL',
      object_uri          => 'https://objectstorage.us-ashburn-1.oraclecloud.com/p/aN.../n/zr.../b/bucket-name-20260129/o/cwallet.sso',
      directory_name      => 'EXTPROCWALLETDIR'
      );
    END;
    /
   

   A continuación, cree el objeto de biblioteca en la base de datos que representa la biblioteca C en ExtProc, con los parámetros de entrada que ha recopilado en el paso anterior.

    BEGIN
      DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
         library_name               => 'EXTPROC_LIBRARY',
         library_listener_url       => 'extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com:16000',
         library_wallet_dir_name    => 'EXTPROCWALLETDIR',
         library_ssl_server_cert_dn => 'CN=extproc-agent-170798',
         library_remote_path        => '/u01/app/oracle/extproc_libs/helloCextproc.so'
      );
    END;
    /
   

    PL/SQL procedure successfully completed.
   

     SELECT catalog_name from DBA_CLOUD_FUNCTION_CATALOG WHERE catalog_name LIKE '%EXTPROC%';
   

    CATALOG_NAME
   
    ---------------
    EXTPROC_LIBRARY
   

   Cree la función SQL asignada a la función ExtProc C. Consulte el nombre de la función C del programa escrito anteriormente.

     CREATE OR REPLACE FUNCTION HELLOCEXTPROC RETURN VARCHAR2 AS
        LANGUAGE C
        LIBRARY EXTPROC_LIBRARY
        NAME "helloCextproc";
    /
   

    Function created.
   

   Llame a la función SQL. Es una ejecución exitosa (ver el cuerpo de la función C de la rutina C anterior).

     SELECT HELLOCEXTPROC() FROM dual;
   

    HELLOCEXTPROC()
   
    ----------------------------------------------------------------------------------
    Hello C Extproc from FQDN: extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com
   

Temas relacionados

Paquete DBMS_CLOUD_FUNCTION