Documentación de Oracle Cloud Infrastructure

Paquete DBMS_CLOUD_FUNCTION

El paquete DBMS_CLOUD_FUNCTION permite llamar a funciones remotas Lambda de OCI y AWS en Autonomous Database como funciones SQL.

Tema principal: Referencia de paquete proporcionado por Autonomous Database

Resumen de los subprogramas DBMS_CLOUD_FUNCTION

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

Subprograma Descripción

Procedimiento CREATE_CATALOG

Con este procedimiento se 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 funciones de un catálogo.

Procedimiento LIST_FUNCTIONS

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

Procedimiento SYNC_FUNCTIONS

Este procedimiento crea un envoltorio PL/SQL para agregar nuevas funciones al catálogo y eliminar envoltorios para funciones que se han suprimido del catálogo.
  • Procedimiento CREATE_CATALOG
    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.
  • Procedimiento CREATE_FUNCTION
    Este procedimiento crea funciones en un catálogo. Hay dos procedimientos DBMS_CLOUD_FUNCTION.CREATE_FUNCTION sobrecargados.
  • Procedimiento DROP_CATALOG
    El procedimiento DBMS_CLOUD_FUNCTION.DROP_CATALOG borra el catálogo y las funciones creadas mediante el catálogo. Este procedimiento está sobrecargado.
  • Procedimiento DROP_FUNCTION
    El procedimiento DBMS_CLOUD_FUNCTION.DROP_FUNCTION borra la función. Este procedimiento está sobrecargado.
  • Procedimiento LIST_FUNCTIONS
    Este procedimiento muestra todas las funciones de un catálogo.
  • Procedimiento SYNC_FUNCTIONS
    Este procedimiento crea un envoltorio PL/SQL para agregar nuevas funciones al catálogo y eliminar envoltorios para funciones que se han suprimido del catálogo.

Tema principal: Paquete DBMS_CLOUD_FUNCTION

Procedimiento CREATE_CATALOG

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 o AZURE 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 a 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 con el 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 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 donde se almacena la cartera autofirmada.

Este parámetro es obligatorio.

library_ssl_server_cert_dn

Especifica el nombre distintivo (DN) del certificado del servidor.

Este parámetro es obligatorio.

Con 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 transfieren valores de parámetros incorrectos.

  • El valor library_name no es único al crear una biblioteca.

ORA-20001

Este error se produce 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 library_listener_url al crear una biblioteca.

ORA-20002

Este error se produce en cualquiera de las siguientes condiciones:

  • Este error se produce cuando el catálogo ya existe.

  • El directorio de certificados 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 (   
    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 sobre lo siguiente:

    • DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE

    • DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE_INVOKE_FUNCTION_RESPONSE_T

    • DBMS_CLOUD

    • Privilegio de lectura en USER_CLOUD_FUNCTION

    • Privilegio de lectura en USER_CLOUD_FUNCTION_CATALOG

Procedimiento CREATE_FUNCTION

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

Sintaxis de CREATE_FUNCTION

El procedimiento DBMS_CLOUD_FUNCTION.CREATE_FUNCTION solo está soportado 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
);

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 de CREATE_FUNCTION

CREATE_FUNCTION Excepciones

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

Este parámetro es obligatorio.

input_args

Especifica el par de 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 datos CLOB.

response_handler

Especifica la devolución de llamada definida por el usuario para gestionar la respuesta.
Código de Error Descripción

ORA-20001

Este error se produce 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 produce 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 existe.

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 retorno o no es válido.

ORA-20008

Este error se produce cuando falta el manejador de respuestas o no es válido.

Ejemplo de CREATE_FUNCTION 

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

Sintaxis de CREATE_FUNCTION 

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 de CREATE_FUNCTION

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 no se proporciona el valor para function_id, se utiliza el valor de function_name.

plsql_params

Especifica el par de 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 C externa 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.

Ejemplo de CREATE_FUNCTION 

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

Procedimiento DROP_CATALOG

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

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.

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

Por ejemplo: 

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

Procedimiento DROP_FUNCTION

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

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

Procedimiento LIST_FUNCTIONS

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

Con 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 produce 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 crea un envoltorio PL/SQL para agregar nuevas funciones al catálogo y eliminar envoltorios para 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

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 de este parámetro es DAILY.

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