Los procedimientos externos son funciones escritas en un lenguaje de tercera generación y que se pueden llamar desde PL/SQL o SQL como si fueran una rutina o función PL/SQL.

Puede llamar y utilizar procedimientos externos en Autonomous Database con funciones definidas por el usuario.

Defina el procedimiento C utilizando uno de estos prototipos.

Cree una biblioteca de objetos compartidos (archivo .so). La biblioteca de objetos compartidos contiene el procedimiento C (procedimiento externo) que se definió en el paso anterior.

gcc -I/u01/app/oracle/extproc_libs/ -shared -fPIC -o extproc.so UpdateSalary.c

Muestra los pasos para obtener la aplicación de pila EXTPROC de OCI Marketplace.

1. Conéctese a la consola de OCI en http://cloud.oracle.com. Consulte Conexión a la consola de Oracle Cloud Infrastructure para obtener más información.
2. En el menú de navegación de la izquierda de Oracle Cloud Infrastructure, haga clic en Marketplace y, a continuación, en Marketplace, haga clic en Todas las aplicaciones. Accederá al panel de control Todas las aplicaciones de Marketplace.
3. Introduzca EXTPROC en el campo de búsqueda y haga clic en Buscar.
4. Haga clic en el widget EXTPROC de Tipo: pila.
   
   

   
   

   
   

Inicie la aplicación de pila EXTPROC desde la página Detalles de aplicación de EXTPROC.

1. En la página EXTPROC Agent de Oracle Autonomous Database, en Pila de tipo, realice lo siguiente:

   • En la lista desplegable Versión, seleccione la versión del paquete de la pila. Por defecto, el menú muestra la última versión.

   • En la lista desplegable compartimento, seleccione el nombre del compartimento en el que desea iniciar la instancia.

     Nota
     
     Si no tiene permiso para iniciar la instancia en el compartimento seleccionado, la instancia se inicia en el compartimento raíz.

   • Seleccione la casilla de control He revisado y acepto las condiciones y restricciones estándar de Oracle.

2. Haga clic en Iniciar pila.
   
   

   
   

   
   

Muestra los pasos para crear la pila para la instancia EXTPROC.

1. En la página Información de pila, revise y edite la siguiente información según sea necesario:

   • Stack information

   • Custom providers

   • Nombre (opcional): puede editar el nombre de pila por defecto. Evite introducir información confidencial.

   • Descripción (opcional): puede editar la descripción de pila por defecto. Evite introducir información confidencial.

   • Create in compartment

   • Terraform version

   • Etiquetas: proporcione lo siguiente para asignar etiquetas a la pila.

     • Espacio de nombres de etiqueta: para agregar una etiqueta definida, seleccione un espacio de nombres existente. Para agregar una etiqueta de origen libre, deje el valor en blanco.

     • clave de etiqueta: para agregar una etiqueta definida, seleccione una clave de etiqueta existente. Para agregar una etiqueta de formato libre, escriba el nombre de clave que desee.

     • Valor de etiqueta: escriba el valor de etiqueta que desee.

     Agregar etiqueta: haga clic para agregar otra etiqueta.

     Consulte Etiquetas de recursos para obtener más información sobre el etiquetado.

   
   

   
   

   
   
2. Haga clic en Siguiente.
   Accederá a la página Configurar variables, que permite configurar variables para los recursos de infraestructura que la pila crea al ejecutar el trabajo de aplicación para este plan de ejecución.
3. En la página Configurar variables, introduzca la información en las áreas: Configurar el agente EXTPROC, Configuración de red y Configuración de recursos informáticos.
   1. Proporcione información en el área Configurar el agente EXTPROC.

      • Bibliotecas externas: proporcione una lista de bibliotecas, separadas por comas (,), a las que desea permitir que se llame desde Autonomous Database. Por ejemplo, extproc.so, extproc1.so.

        Después de crear la pila, debe copiar las bibliotecas en el directorio /u01/app/oracle/extproc_libs de la máquina virtual del agente EXTPROC.

      • Contraseña de cartera: proporcione la contraseña de cartera.

        La cartera y un certificado autofirmado se generan para la autenticación TLS mutua entre Autonomous Database y la máquina virtual del agente EXTPROC. La cartera se crea en el directorio /u01/app/oracle/extproc_wallet.

        Nota
        
        Después de crear la cartera, no se puede cambiar la contraseña de la cartera.

      
      

      
      

      
      
   2. Proporcione información en el área Configuración de red.

      • Compartimento: en la lista desplegable, seleccione el compartimento en el que desea colocar la configuración.

      • Estrategia de red: seleccione una de las opciones de la lista desplegable, Crear nueva VCN y subred o Usar VCN y subred existentes.

        • Crear nueva VCN y subred: seleccione esta opción si no hay ningún punto final privado configurado para Autonomous Database. Esto crea una nueva VCN con subred pública y privada que está preconfigurada con reglas de seguridad.

          Si selecciona esta opción, la página también muestra la lista desplegable Estrategia de Configuración:

          Seleccione Usar configuración recomendada en la lista desplegable Estrategia de configuración.

          
          

          
          

          
          

        • Usar VCN y subred existentes: seleccione esta opción para crear el agente EXTPROC mediante una VCN existente. Esto crea la instancia del agente EXTPROC en la subred proporcionada.

          Al seleccionar esta opción, proporcione la siguiente información para la VCN y la subred existentes:

          • En Virtual Cloud Network:

            En la lista desplegable VCN existente, seleccione una VCN existente. Si la VCN especificada no existe, se crea una nueva VCN.

          • En Subred EXTPROC:

            En la lista desplegable Subred existente, seleccione una subred existente.

            Al utilizar una VCN y una subred existentes, agregue una regla de entrada para el puerto 16000 de la instancia de agente EXTPROC. También puede agregar una regla de salida en la subred pública.

            Consulte Configuración del acceso de red con puntos finales privados para obtener más información.

          
          

          
          

          
          

      • Tipo de acceso de agente EXTPROC: seleccione una de las siguientes opciones en la lista desplegable.

        • Acceso seguro desde bases de datos de punto final privado de ADB-S específicas en la VCN: seleccione esta opción para permitir que solo las IP de punto final privado especificadas en la red virtual en la nube (VCN) se conecten al agente EXTPROC.

          Cuando se selecciona esta opción, se proporciona una lista de direcciones IP de punto final privado permitidas en el siguiente paso.

        • Acceso seguro desde todas las bases de datos de punto final privado de ADB-S de la VCN: seleccione esta opción para permitir que cualquier punto final privado de la red virtual en la nube (VCN) se conecte al agente EXTPROC.

      • Direcciones IP de punto final privado

        Proporcione una lista de direcciones IP de punto final privado separadas por comas (,) para la variable Private Endpoint IP Addresses. Por ejemplo, 10.0.0.0, 10.0.0.1.

        Nota
        
        Este campo solo se muestra al seleccionar Acceso seguro desde bases de datos de punto final privado de ADB-S específicas en la VCN para el tipo de acceso de agente EXTPROC.
   3. Proporcione la información de configuración de recursos informáticos.

      • Compartimento: seleccione el compartimento en el que desea crear la pila.

      • Unidad: seleccione una unidad según los requisitos de carga de trabajo de la instancia de agente EXTPROC. La unidad determina los recursos asignados a la instancia de agente EXTPROC.

      • Número de organizaciones: seleccione el número de organizaciones que desea asignar a la instancia de agente EXTPROC.

      • Tamaño de memoria (GB): seleccione la cantidad de memoria en GB que desea asignar a la instancia de agente EXTPROC.

      • Agregar claves SSH: cargue una clave SSH pública o pegue la clave pública. Seleccione una de las opciones siguientes:

        • Seleccionar archivo de clave SSH: cargue la parte de clave pública de su par de claves. Busque el archivo de claves que desea cargar, o bien arrastre y suelte el archivo en el cuadro.

        • Pegar clave SSH: pegue la parte de clave pública del par de claves en el cuadro.

      
      

      
      

      
      
4. Haga clic en Siguiente.

   Esto le llevará a la página Revisión.

5. En la página Revisar, realice los siguientes pasos:
   1. Verifique las variables de configuración.
   2. Seleccione la casilla de control Ejecutar aplicación en Ejecutar aplicación en la pila creada
   3. Haga clic en Crear.
   Nota
   
   Esta área no muestra variables que tengan valores por defecto o variables que no haya cambiado.

   
   

   
   

   
   

   El gestor de recursos ejecuta el trabajo de aplicación para crear recursos de pila según corresponda. Esto le llevará a la página Detalles del trabajo y el estado del trabajo será Aceptado. Cuando se inicia el trabajo de aplicación, el estado se actualiza a En curso.

   
   

   
   

   
   

   Nota
   
   La información necesaria para conectarse a la instancia creada como parte de la pila está disponible en el separador Información de la aplicación.

Se crea una cartera autofirmada como parte de la creación de la aplicación de agente EXTPROC. Esta cartera permite acceder a la instancia de agente Extrpoc.

1. Importe la cartera, cwallet.sso, que contiene los certificados para la instancia de agente EXTPROC desde Object Storage en Autonomous Database. Tenga en cuenta lo siguiente para 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 de 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.

2. Cree credenciales para acceder a Object Storage en el que almacena 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.
   La creación de una credencial para acceder al almacén de objetos de Oracle Cloud Infrastructure no es necesaria si activa las credenciales de la entidad de recurso. Consulte Acerca del uso de la entidad de recurso para acceder a los recursos de Oracle Cloud Infrastructure para obtener más información.
3. Cree un directorio en Autonomous Database para el archivo de cartera cwallet.sso.

   CREATE DIRECTORY wallet_dir AS 'directory_location';

   See Create Directory in Autonomous Database for more information creating directories.

4. Utilice DBMS_CLOUD.GET_OBJECT para cargar la cartera. 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 de nombres de Oracle Cloud Infrastructure Object Storage, y bucketname es el nombre del cubo. Consulte Espacios de nombres de Object Storage para obtener más información.

   La cartera se copia en el directorio creado en el paso anterior, WALLET_DIR. La cartera que permite conectarse a la instancia de agente EXTPROC ahora está disponible en la instancia de Autonomous Database.

Muestra los pasos para llamar a un procedimiento externo como una función SQL.

1. Cree una biblioteca.

   Un procedimiento externo es una rutina de lenguaje C almacenada en una biblioteca. Para llamar a procedimientos externos con Autonomous Database, cree una biblioteca.

   Ejecute DBMS_CLOUD_FUNCTION.CREATE_CATALOG para crear una biblioteca. Por ejemplo:

   BEGIN
       DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
           library_name               => 'demolib',
           library_listener_url       => 'remote_extproc_hostname:16000',
           library_wallet_dir_name    => 'wallet_dir',
           library_ssl_server_cert_dn => 'CN=VM Hostname',
           library_remote_path        => '/u01/app/oracle/extproc_libs/library name'
   );
   END;
   /
   

   De esta forma se crea la biblioteca demolib en Autonomous Database y se registra la biblioteca de enlaces dinámicos en la base de datos. La instancia de agente EXTPROC está preconfigurada para alojar procedimientos externos en el puerto 16000.

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

   Consulte las vistas DBA_CLOUD_FUNCTION_CATALOG y USER_CLOUD_FUNCTION_CATALOG para recuperar la lista de todos los catálogos y bibliotecas de la base de datos.

   Consulte la vista USER_CLOUD_FUNCTION_ERRORS View (Vista USER_CLOUD_FUNCTION_ERRORS) para mostrar los errores generados durante la validación de conexión a la ubicación remota de la biblioteca.

2. Después de crear la biblioteca, utilice DBMS_CLOUD_FUNCTION.CREATE_FUNCTION para crear funciones de envoltorio PL/SQL que hagan referencia a los procedimientos externos (funciones C).

   Por ejemplo:

   DECLARE
       plsql_params clob    := TO_CLOB('{"sal": "IN, FLOAT", "comm" :"IN, FLOAT"}');
       external_params clob := TO_CLOB('sal FLOAT, sal INDICATOR SHORT, comm FLOAT, comm INDICATOR SHORT,
       RETURN INDICATOR SHORT, RETURN FLOAT');
   BEGIN
   DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
       LIBRARY_NAME    => 'demolib',
       FUNCTION_NAME   => '"PercentComm"',
       PLSQL_PARAMS    => plsql_params,
       EXTERNAL_PARAMS => external_params,
       API_TYPE        => 'FUNCTION',
       WITH_CONTEXT    => FALSE,
       RETURN_TYPE     => 'FLOAT'
   );
   END;
   /
   

   Esto crea la función PercentComm y registra el procedimiento externo PercentComm en la biblioteca DEMOLIB.

   La función PercentComm de la biblioteca es una referencia al procedimiento externo correspondiente cuyo nombre hace referencia el parámetro FUNCTION_ID.

   En este ejemplo, no se proporciona el parámetro FUNCTION_ID, el valor proporcionado para el parámetro FUNCTION_NAME se utiliza como FUNCTION_ID.

   Por ejemplo:

   DECLARE
       plsql_params clob := TO_CLOB('{"row_id": "IN,CHAR"}');
       external_params clob := TO_CLOB('CONTEXT, row_id STRING, row_id LENGTH SB4');
   BEGIN
   DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
       LIBRARY_NAME    => 'demolib',
       FUNCTION_NAME   => 'UpdateSalary_local',
       FUNCTION_ID     => '"UpdateSalary"',
       PLSQL_PARAMS    => plsql_params,
       EXTERNAL_PARAMS => external_params,
       API_TYPE        => 'PROCEDURE',
       WITH_CONTEXT    => TRUE
   );
   END;
   /
   

   Esto crea el procedimiento UPDATESALARY_LOCAL y registra el procedimiento UpdateSalary en la biblioteca DEMOLIB.

   El procedimiento UPDATESALARY_LOCAL de la biblioteca es una referencia al procedimiento externo correspondiente UpdateSalary cuyo nombre hace referencia el parámetro FUNCTION_ID.

   Puede consultar las vistas DBA_CLOUD_FUNCTION y USER_CLOUD_FUNCTION para recuperar la lista de todas las funciones disponibles para su uso en la base de datos.

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

3. Después de crear la función, puede DESCRIBE. Por ejemplo:

   DESC "PercentComm";

4. Puede borrar una función existente mediante el procedimiento DROP_FUNCTION. Por ejemplo:

   EXEC DBMS_CLOUD_FUNCTION.DROP_FUNCTION (LIBRARY_NAME => 'demolib', FUNCTION_NAME => '"PercentComm"');
   

   Esto borra la función PercentComm de la biblioteca DEMOLIB.

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

5. Puede borrar una biblioteca existente mediante el procedimiento DROP_CATALOG. Por ejemplo:

   BEGIN
       DBMS_CLOUD_FUNCTION.DROP_CATALOG (
         LIBRARY_NAME  => 'demolib'
     );
   END;
   /
   

   Esto borra la biblioteca DEMOLIB.

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