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.

Requisitos

Para utilizar subprogramas en el paquete DBMS_CLOUD_FUNCTION, debe estar conectado como usuario ADMIN y otorgar los siguientes privilegios:

GRANT EXECUTE ON DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE TO <user_or_role>;
GRANT EXECUTE ON DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE_INVOKE_FUNCTION_RESPONSE_ T TO <user_or_role>;
GRANT EXECUTE ON DBMS_CLOUD_FUNCTION TO <user_or_role>;
GRANT EXECUTE ON DBMS_CLOUD TO <user_or_role>;

Resumen de Subprogramas DBMS_CLOUD_FUNCTION

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

Subprograma	Descripción
Procedimiento CREATE_CATALOG	Este procedimiento crea un catálogo.
Procedimiento LIST_FUNCTIONS	Este procedimiento enumera todas las funciones de un catálogo.
Procedimiento CREATE_FUNCTION	Este procedimiento crea funciones en un catálogo.
Procedimiento SYNC_FUNCTIONS	Este procedimiento 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.
Procedimiento DROP_FUNCTION	Este procedimiento borra las funciones de un catálogo.
Procedimiento DROP_CATALOG	Este procedimiento borra un catálogo y las funciones creadas mediante el catálogo.

CREATE_CATALOG Procedimiento

Este procedimiento crea un catálogo en la base de datos. El procedimiento DBMS_CLOUD_FUNCTION.CREATE_CATALOG crea un catálogo. 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
);

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	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`, `AWS`, `AZURE` o `GCP` 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, regiones y Azure subscription_id. Este parámetro es obligatorio.
`library_name`	Especifica el nombre de la biblioteca al crear una biblioteca remota. Este parámetro es obligatorio.
`library_listener_url`	Especifica la ubicación remota de la biblioteca. El parámetro acepta un valor de cadena en formato `host_name:port_number`. Por ejemplo: `EHRPMZ_DBDOMAIN.adb-us-phoenix1.com:16000` Este parámetro es obligatorio.
`library_remote_path`	Especifica la ruta de la biblioteca remota. Debe proporcionar la ruta absoluta completa a la biblioteca remota. Por ejemplo:`/u01/app/oracle/product/21.0.0.0/client_1/lib/libst_shape.so` Este parámetro es obligatorio.
`library_wallet_dir_name`	Especifica el directorio en el que se almacena la cartera autofirmada. Este parámetro es obligatorio.
`library_ssl_server_cert_dn`	Especifica el nombre distintivo (DN) del certificado de servidor. Este parámetro es obligatorio.

Errores

Código de error	Descripción
`ORA-20000`	Este error se produce en cualquiera de las siguientes condiciones: - Falta el valor `cloud_params` o se han transferido valores de parámetros incorrectos. El valor `library_name` no es único al crear una biblioteca.
`ORA-20001`	Este error se emite en cualquiera de las siguientes condiciones: La credencial a la que se hace referencia en `credential_name` no existe. No se puede acceder al listener especificado en el `library_listener_url` al crear una biblioteca.
`ORA-20002`	Este error se emite en cualquiera de las siguientes condiciones: Este error se produce cuando el catálogo ya existe. El directorio de certificado del servidor especificado está vacío al crear una biblioteca.
`ORA-20009`	Este error se produce cuando el proveedor de servicios no existe.

Ejemplos

BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
      credential_name => 'DEFAULT_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  => 'AZURE$PA',
        catalog_name     => 'AZURE_DEMO_CATALOG',
        service_provider => 'AZURE',
        cloud_params     => '{"subscription_id":"44495e6a-8ff1-4161-b387-0e14e675b878"}'
);
END;
/

BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
        credential_name  => 'GCP$PA',
        catalog_name     => 'GCP_DEMO_CATALOG',
        service_provider => 'GCP',
        cloud_params     => '{"project_id":"example_XXXXXX"}'
 );
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;
/

BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
    library_name               => 'EXT_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;
/

Nota 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

LIST_FUNCTIONS Procedimiento

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

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 falta el valor `cloud_params` o 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.

Ejemplo:

SET SERVEROUTPUT ON
SET LINESIZE 32767
SET LONG 1000000
SET LONGCHUNKSIZE 32767
SET TRIMSPOOL ON
SET WRAP OFF

DECLARE
  l_function_list CLOB;
  l_function_array JSON_ARRAY_T;
  l_object JSON_OBJECT_T;
BEGIN
 DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS(
                                     credential_name => 'DEFAULT_CREDENTIAL',
                                     catalog_name    => 'OCI_DEMO_CATALOG',
                                     function_list   => l_function_list);
  l_function_array := JSON_ARRAY_T.parse(l_function_list);
  FOR i IN 0 .. l_function_array.get_size - 1
  LOOP
     l_object := TREAT(l_function_array.get(i) AS json_object_t);
     dbms_output.put_line('Function ID   = ' || l_object.get_string('functionId'));
     dbms_output.put_line('Function Name = ' || l_object.get_string('functionName'));
     dbms_output.put_line('--------------------------');
  END LOOP;
END;
/

CREATE_FUNCTION Procedimiento

Este procedimiento crea funciones en un catálogo. Hay dos procedimientos DBMS_CLOUD_FUNCTION.CREATE_FUNCTION sobrecargados.

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

Firma del manejador de respuestas

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

El tipo de retorno es el tipo definido por el usuario o el tipo PL/SQL. function_response es de JSON con campos.

'{
"STATUS":"<RESPONCE STATUS>",
"RESPONSE_BODY":"<FUNCTION RESPONSE>"
}'

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 OCI, AWS Lambda o la función Azure. 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.

Excepciones

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

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

Tipo de sintaxis 2

DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
  library_name         IN VARCHAR2,
  function_name        IN VARCHAR2,
  function_id          IN VARCHAR2 DEFAULT NULL,
  plsql_params         IN CLOB DEFAULT NULL,
  external_params      IN CLOB DEFAULT NULL,
  api_type             IN VARCHAR2 DEFAULT 'FUNCTION',
  with_context         IN BOOLEAN DEFAULT FALSE,
  return_type          IN VARCHAR2 DEFAULT NULL
);

Parámetros para el tipo de sintaxis 2

Parámetro	Descripción
`library_name`	Especifica el nombre de la biblioteca remota. 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 los procedimientos externos (`extproc`). Si el valor de `function_id` no se proporciona, se utiliza el valor de `function_name`.
`plsql_params`	Especifica el par JSON de valor de clave que acepta los parámetros para el envoltorio PL/SQL. Los valores se deben proporcionar con el formato `"var_name":"modetype, datatype"`. `var_name`: es el nombre de la variable. Este parámetro es obligatorio. `modetype`: especifica el modo de variable. El modo de variable puede ser uno de los siguientes: `IN` `OUT` `IN OUT` `datatype`: especifica el tipo de dato variable. Este parámetro es obligatorio. El valor por defecto para `plsql_params` es `NULL`.
`external_params`	Especifica los parámetros que se deben proporcionar a la función C externa. Si no se proporciona un valor para `external_params`, se utilizan los parámetros PL/SQL.
`api_type`	Especifica el tipo de API (función o procedimiento). El valor por defecto para `api_type` es `function`.
`with_context`	Especifica que se transfiere un puntero de contexto al procedimiento externo. La biblioteca externa en C utiliza este contexto para volver a conectarse a la base de datos. El valor por defecto para `with_context` es `FALSE`.
`return_type`	Especifica el tipo de retorno de la función creada.

SYNC_FUNCTIONS Procedimiento

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

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

Ejemplo:

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

DROP_FUNCTION Procedimiento

El procedimiento DBMS_CLOUD_FUNCTION.DROP_FUNCTION borra la función. Este procedimiento está sobrecargado.

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

DBMS_CLOUD_FUNCTION.DROP_FUNCTION (
    library_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.
`library_name`	Especifica el nombre de la biblioteca. 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.

library_name

Especifica el nombre de la biblioteca.

Este parámetro es obligatorio.

Ejemplos

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

BEGIN
    DBMS_CLOUD_FUNCTION.DROP_FUNCTION (
       library_name     => 'EXTPROC_DEMO_LIBRARY',
       function_name    => 'demo_function');
END;
/

DROP_CATALOG Procedimiento

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

Sintaxis

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    catalog_name      IN VARCHAR2
 );

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    library_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.
`library_name`	Especifica el nombre de la biblioteca. Este parámetro es obligatorio.

catalog_name

Especifica el nombre del catálogo.

Este parámetro es obligatorio.

library_name

Especifica el nombre de la biblioteca.

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.

Ejemplos

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

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

Documentación de Oracle Cloud Infrastructure

Paquete DBMS_CLOUD_FUNCTION

Requisitos

Resumen de Subprogramas DBMS_CLOUD_FUNCTION

CREATE_CATALOG Procedimiento

Sintaxis

Parámetros

Errores

Ejemplos

Nota de uso

LIST_FUNCTIONS Procedimiento

Sintaxis

Parámetros

Errores

Ejemplo:

CREATE_FUNCTION Procedimiento

Sintaxis

Parámetros

Excepciones

Ejemplo

Tipo de sintaxis 2

Parámetros para el tipo de sintaxis 2

SYNC_FUNCTIONS Procedimiento

Sintaxis

Parámetros

Errores

Ejemplo:

DROP_FUNCTION Procedimiento

Sintaxis

Parámetros

Ejemplos

DROP_CATALOG Procedimiento

Sintaxis

Parámetros

Errores

Ejemplos