Paquete DBMS_CLOUD

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.

Note:

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
CREATE_CATALOG Procedimiento	Este procedimiento crea un catálogo.
CREATE_FUNCTION Procedimiento	Este procedimiento crea funciones en un catálogo.
DROP_CATALOG Procedimiento	Este procedimiento borra un catálogo y las funciones creadas mediante el catálogo.
DROP_FUNCTION Procedimiento	Este procedimiento borra las funciones de un catálogo.
LIST_FUNCTIONS Procedimiento	Este procedimiento enumera todas las funciones de un catálogo.
SYNC_FUNCTIONS Procedimiento	Este procedimiento permite agregar nuevas funciones al catálogo y eliminar las funciones que se han suprimido del catálogo.

CREATE_CATALOG Procedimiento

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.

Sintaxis

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

Parámetros

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

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. Consulte External Procedures Overview.

Sintaxis

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

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 VM 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 VM 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 donde 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

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

CREATE_FUNCTION Procedimiento

Puede crear manualmente una función SQL que llame a su función en la nube correspondiente en el catálogo. Mientras que 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 se admite para 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 de <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 que devuelve 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

DROP_CATALOG Procedimiento

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

DROP_FUNCTION Procedimiento

El procedimiento DBMS_CLOUD_FUNCTION.DROP_FUNCTION borra la función.

Sintaxis

El procedimiento DBMS_CLOUD_FUNCTION.DROP_FUNCTION solo se admite para 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;
/

LIST_FUNCTIONS Procedimiento

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

Note:

El procedimiento LIST_FUNCTIONS solo es aplicable para 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;

SYNC_FUNCTIONS Procedimiento

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

Note:

El procedimiento SYNC_FUNCTIONS solo es aplicable para 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 por defecto del 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 por defecto del 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;
/

Título e Información de Copyright

Oracle y/o sus filiales.