Paquete DBMS_CLOUD_FUNCTION

El paquete DBMS_CLOUD_FUNCTION le permite invocar funciones remotas de OCI y AWS Lambda en su base de datos de IA autónoma como funciones SQL.

Nota: El soporte para DBMS_CLOUD_FUNCTION está disponible en Oracle Database 19c a partir de la versión 19.29 y en Oracle AI Database 26ai a partir de la versión 23.26.

Resumen de subprogramas DBMS_CLOUD_FUNCTION

En esta tabla se resumen los subprogramas incluidos en el paquete DBMS_CLOUD_FUNCTION.

Tabla - Subprogramas DBMS_CLOUD_FUNCTION

Subprograma	Descripción
Procedimiento CREATE_CATALOG	Este procedimiento crea un catálogo.
Procedimiento CREATE_FUNCTION	Este procedimiento crea funciones en un catálogo.
Procedimiento DROP_CATALOG	Este procedimiento borra un catálogo y las funciones creadas mediante el catálogo.
Procedimiento DROP_FUNCTION	Este procedimiento borra las funciones de un catálogo.
Procedimiento LIST_FUNCTIONS	Este procedimiento enumera todas las funciones de un catálogo.
Procedimiento SYNC_FUNCTIONS	Este procedimiento permite agregar nuevas funciones al catálogo y eliminar las funciones que se han suprimido del catálogo.

Procedimiento CREATE_CATALOG

El procedimiento DBMS_CLOUD_FUNCTION.CREATE_CATALOG crea un catálogo en la base de datos. Un catálogo es un juego de funciones que crea la infraestructura necesaria para ejecutar subrutinas. Este procedimiento está sobrecargado.

Variante de sintaxis 1

DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
    credential_name             IN VARCHAR2,
    catalog_name                IN VARCHAR2,
    service_provider            IN VARCHAR2,
    cloud_params                IN CLOB
);

Parámetros para variante 1

parámetro	Descripción
`credential_name`	Especifica el nombre de la credencial para la autenticación. Este parámetro es obligatorio.
`service_provider`	Especifica el tipo de proveedor de servicios. Este parámetro puede tener `OCI` o `AWS` como valor de parámetro. Este parámetro es obligatorio.
`catalog_name`	Especifica el nombre del catálogo. Este parámetro es obligatorio.
`cloud_params`	Proporciona un parámetro para la función. Por ejemplo, OCID de compartimento y regiones. Este parámetro es obligatorio.

Ejemplos para Variante 1

BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
        credential_name  => 'OCI_CREDENTIAL',
        catalog_name     => 'OCI_DEMO_CATALOG',
        service_provider => 'OCI',
        cloud_params     => '{"region_id":"us-phoenix-1", "compartment_id":"compartment_id"}'
 );
END;
/

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

Debe utilizar el procedimiento sobrecargado para crear una biblioteca con procedimientos externos. Este procedimiento no necesita un objeto de credencial. Los parámetros requieren especificaciones de la máquina virtual EXTPROC y la biblioteca compartida que contiene los procedimientos externos.

Variante de sintaxis 2

DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
    library_name                IN VARCHAR2,
    library_listener_url        IN VARCHAR2,
    library_wallet_dir_name     IN VARCHAR2,
    library_ssl_server_cert_dn  IN VARCHAR2,
    library_remote_path         IN VARCHAR2
);

Parámetros para Variante 2

parámetro	Descripciones
`library_name`	Especifica el nombre proporcionado al catálogo/biblioteca en la base de datos. Este parámetro es obligatorio.
`library_listener_url`	Especifica el FQDN (nombre de dominio completo) de la máquina virtual EXTPROC que aloja la biblioteca compartida que contiene los procedimientos externos escritos en un lenguaje de tercera generación como C/C++, y el número de puerto en el que el listener de SQL*Net que se ejecuta en el contenedor de máquina virtual EXTPROC acepta solicitudes de conexión. El parámetro se especifica como una cadena con el formato `host_name:port_number`. Por ejemplo: `'extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com:16000'` Este parámetro es obligatorio.
`library_wallet_dir_name`	Especifica el nombre de DIRECTORY en la base de datos en la que se ha importado y almacenado la cartera autofirmada.
`library_ssl_server_cert_dn`	Especifica el nombre distintivo (DN) del certificado de servidor obtenido de la cartera. Por ejemplo: `'CN=extproc-agent-170798'` Este parámetro es obligatorio.
`library_remote_path`	Especifica el nombre de ruta completo del directorio en la máquina virtual EXTPROC, donde se almacena la biblioteca que contiene los procedimientos externos. Por ejemplo: `'/u01/app/oracle/extproc_libs/helloCextproc.so'` Este parámetro es obligatorio.

Ejemplos para Variante 2

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

Errores

Código de error	Descripción
`ORA-20000`	Este error se emite en la siguiente condición: - Falta el valor `cloud_params` o se transfieren valores de parámetros incorrectos.
`ORA-20001`	Este error se emite en la siguiente condición: - La credencial a la que se hace referencia en `credential_name` no existe.
`ORA-20002`	Este error se emite en la siguiente condición: - Este error se emite cuando el catálogo ya existe.
`ORA-20009`	Este error se produce cuando el proveedor de servicios no existe.

Notas de uso

Para crear un catálogo, debe estar conectado como usuario ADMIN o tener privilegios en lo siguiente:
- DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE
- DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE_INVOKE_FUNCTION_RESPONSE_T
- DBMS_CLOUD
- Leer privilegio en USER_CLOUD_FUNCTION
- Leer privilegio en USER_CLOUD_FUNCTION_CATALOG

Procedimiento CREATE_FUNCTION

Puede crear manualmente una función SQL que llame a su función en la nube correspondiente en el catálogo. Mientras SYNC_FUNCTIONS recupera y crea automáticamente envoltorios para todas las funciones en la nube de un catálogo, CREATE_FUNCTION le permite crear funciones con tipos de retorno personalizados y manejadores de respuestas. El procedimiento CREATE_FUNCTION solo es aplicable para Cloud Functions.

Sintaxis

El procedimiento DBMS_CLOUD_FUNCTION.CREATE_FUNCTION solo está soportado para las funciones en la nube.

DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
    credential_name   IN VARCHAR2,
    catalog_name      IN VARCHAR2,
    function_name     IN VARCHAR2,
    function_id       IN VARCHAR2,
    input_args        IN CLOB      DEFAULT NULL,
    return_type       IN VARCHAR2  DEFAULT 'CLOB',
    response_handler  IN VARCHAR2  DEFAULT NULL
);

response_handler se debe definir con este formato:

<USER DEFINED TYPE> response_handler_name(function_response in CLOB)RETURNS CLOB;

El valor devuelto de response_handler es 'Tipo definido por el usuario' y response_json es un documento JSON con dos campos, con el siguiente formato:

'{
"status":"<response status>",
"response_body":"<response from the function>"
}'

Parámetros

parámetro	Descripción
`credential_name`	Especifica el nombre de la credencial para la autenticación. Este parámetro es obligatorio.
`catalog_name`	Especifica el nombre del catálogo. Este parámetro es obligatorio.
`function_name`	Especifica el nombre de la función PL/SQL. Este parámetro es obligatorio.
`function_id`	El valor del parámetro `function_id` hace referencia a la función de OCI o AWS Lambda. Este parámetro es obligatorio.
`input_args`	Especifica el par JSON de valor de clave que acepta argumentos de entrada y sus tipos.
`return_type`	Define el tipo de retorno de la función. El tipo de retorno es del tipo de dato `CLOB`.
`response_handler`	Especifica la devolución de llamada definida por el usuario para manejar la respuesta.

Errores

Código de error	Descripción
`ORA-20001`	Este error se emite cuando la credencial a la que se hace referencia en `credential_name` no existe.
`ORA-20003`	Este error se produce cuando el catálogo especificado no existe.
`ORA-20004`	Este error se emite cuando la función especificada ya existe.
`ORA-20005`	Este error se produce cuando el ID de función o la función Nombres de recursos de Amazon (ARN) no existen.
`ORA-20006`	Este error se emite cuando los argumentos de entrada no son válidos.
`ORA-20007`	Este error se genera cuando falta el tipo de devolución o no es válido.
`ORA-20008`	Este error se emite cuando falta el manejador de respuestas o no es válido.

Ejemplo

El caso simple con solo parámetros de entrada a la función:

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

Ejemplo con tipo de retorno y manejador de respuestas:

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

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

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 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.

Notas de uso

Para llamar a procedimientos externos, puede utilizar la misma sintaxis que se utiliza para las funciones definidas por el usuario. Por ejemplo, si ha creado una biblioteca denominada EXTPROC_LIBRARY en la base de datos mediante el procedimiento CREATE_CATALOG para procedimientos externos, puede definir una función SQL como se muestra en este ejemplo y llamarla desde una sentencia SQL.

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

Function created.

SQL> SELECT HELLOCEXTPROC() FROM dual;

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

Procedimiento DROP_CATALOG

El procedimiento DBMS_CLOUD_FUNCTION.DROP_CATALOG borra el catálogo y las funciones creadas mediante el catálogo.

Sintaxis

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    catalog_name      IN VARCHAR2
 );

Parámetros

parámetro Descripción

parámetro	Descripción
`catalog_name`	Especifica el nombre del catálogo. Este parámetro es obligatorio.

catalog_name

Especifica el nombre del catálogo.

Este parámetro es obligatorio.

Errores

Código de error	Descripción
`ORA-20003`	Este error se produce cuando el catálogo especificado no existe.

Por ejemplo:

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

Procedimiento DROP_FUNCTION

El procedimiento DBMS_CLOUD_FUNCTION.DROP_FUNCTION borra la función.

Sintaxis

El procedimiento DBMS_CLOUD_FUNCTION.DROP_FUNCTION solo está soportado para las funciones en la nube.

DBMS_CLOUD_FUNCTION.DROP_FUNCTION (
    catalog_name      IN VARCHAR2,
    function_name     IN VARCHAR2
);

Parámetros

parámetro Descripción

parámetro	Descripción
`catalog_name`	Especifica el nombre del catálogo. Este parámetro es obligatorio.
`function_name`	Especifica el nombre de la función que se va a borrar. Este parámetro es obligatorio.

catalog_name

Especifica el nombre del catálogo.

Este parámetro es obligatorio.

function_name

Especifica el nombre de la función que se va a borrar.

Este parámetro es obligatorio.

Errores

Código de error	Descripción
`ORA-20003`	Este error se emite cuando la función especificada no existe.

Ejemplos

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

Procedimiento LIST_FUNCTIONS

Este procedimiento enumera todas las funciones de un catálogo.

Nota: El procedimiento LIST_FUNCTIONS solo se puede aplicar a Cloud Functions.

Sintaxis

DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS (
    credential_name   IN VARCHAR2,
    catalog_name      IN VARCHAR2,
    function_list     OUT VARCHAR2
);

Parámetros

parámetro Descripción

credential_name

Especifica el nombre de la credencial para la autenticación.

Este parámetro es obligatorio.

function_list

Devuelve la lista de funciones en formato JSON.

Este parámetro es obligatorio.

catalog_name

Especifica el nombre del catálogo.

Este parámetro es obligatorio.

Errores

Código de error	Descripción
`ORA-20000`	Este error se produce cuando se transfieren valores de parámetros incorrectos.
`ORA-20001`	Este error se emite cuando la credencial a la que se hace referencia en `credential_name` no existe.
`ORA-20003`	Este error se produce cuando el catálogo especificado no existe.

Por ejemplo:

VAR function_list CLOB;
BEGIN
    DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS (
	credential_name  => 'DEFAULT_CREDENTIAL',
	catalog_name     => 'OCI_DEMO_CATALOG',
	function_list    => :function_list);
 );
END;
/
SELECT JSON_QUERY(:function_list, '$' RETURNING VARCHAR2(32676) pretty) AS search_results FROM dual;

Procedimiento SYNC_FUNCTIONS

Este procedimiento permite agregar nuevas funciones al catálogo y eliminar las funciones que se han suprimido del catálogo.

Nota: El procedimiento SYNC_FUNCTIONS solo se puede aplicar a Cloud Functions.

Sintaxis

DBMS_CLOUD_FUNCTION.SYNC_FUNCTIONS (
    catalog_name      IN VARCHAR2,
    refresh_rate     IN VARCHAR2 DEFAULT 'DAILY'
);

Parámetros

parámetro Descripción

parámetro	Descripción
`catalog_name`	Especifica el nombre del catálogo. Este parámetro es obligatorio.
`refresh_rate`	Especifica el ratio de refrescamiento de la función. `refresh_rate` puede aceptar los siguientes valores: `HOURLY` `DAILY` `WEEKLY` `MONTHLY` El valor predeterminado de este parámetro es `DAILY`.

catalog_name

Especifica el nombre del catálogo.

Este parámetro es obligatorio.

refresh_rate

Especifica el ratio de refrescamiento de la función.

refresh_rate puede aceptar los siguientes valores:

HOURLY
DAILY
WEEKLY
MONTHLY

El valor predeterminado de este parámetro es DAILY.

Errores

Código de error	Descripción
`ORA-20003`	Este error se produce cuando el catálogo especificado no existe.
`ORA-20004`	Este error se emite cuando se transfiere un valor no válido para el parámetro `refresh_rate`.

Por ejemplo:

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