DBMS_CLOUD_FUNCTION - Pacote

O pacote DBMS_CLOUD_FUNCTION permite chamar funções remotas da OCI e do AWS Lambda em seu Autonomous AI Database como funções SQL.

Observação: O suporte a DBMS_CLOUD_FUNCTION está disponível no Oracle Database 19c a partir da versão 19.29 e no Oracle AI Database 26ai a partir da versão 23.26.

Resumo dos Subprogramas DBMS_CLOUD_FUNCTION

Esta tabela resume os subprogramas incluídos no pacote DBMS_CLOUD_FUNCTION.

Tabela - Subprogramas DBMS_CLOUD_FUNCTION

Subprograma	Descrição
Procedimento CREATE_CATALOG	Este procedimento cria um catálogo.
Procedimento CREATE_FUNCTION	Este procedimento cria funções em um catálogo.
Procedimento DROP_CATALOG	Este procedimento elimina um catálogo e funções criadas usando o catálogo.
Procedimento DROP_FUNCTION	Este procedimento elimina funções de um catálogo.
Procedimento LIST_FUNCTIONS	Este procedimento lista todas as funções em um catálogo.
Procedimento SYNC_FUNCTIONS	Este procedimento permite adicionar novas funções ao catálogo e remover funções que foram excluídas do catálogo.

Procedimento CREATE_CATALOG

O procedimento DBMS_CLOUD_FUNCTION.CREATE_CATALOG cria um catálogo no banco de dados. Um catálogo é um conjunto de funções que cria a infraestrutura necessária para executar sub-rotinas. Este procedimento é sobrecarregado.

Variante de Sintaxe 1

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

Parâmetros da Variante 1

Parâmetro	Descrição
`credential_name`	Especifica o nome da credencial para autenticação. Este parâmetro é obrigatório.
`service_provider`	Especifica o tipo de prestador de serviço. Esse parâmetro pode ter `OCI` ou `AWS` como um valor de parâmetro. Este parâmetro é obrigatório.
`catalog_name`	Especifica o nome do catálogo. Este parâmetro é obrigatório.
`cloud_params`	Fornece parâmetro para a função. Por exemplo, OCID do Compartimento e Regiões. Este parâmetro é obrigatório.

Exemplos para a 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;
/

Você deve usar o procedimento sobrecarregado para criar uma biblioteca com Procedimentos externos. Este procedimento não requer um objeto de credencial. Os parâmetros exigem especificações da VM EXTPROC e da biblioteca compartilhada que contém os procedimentos externos.

Variante de Sintaxe 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 da Variante 2

Parâmetro	Descrições
`library_name`	Especifica o nome fornecido ao catálogo/biblioteca no banco de dados. Este parâmetro é obrigatório.
`library_listener_url`	Especifica o FQDN (nome de domínio totalmente qualificado) da VM EXTPROC que está hospedando a biblioteca compartilhada que contém os procedimentos externos gravados em uma linguagem de terceira geração como C/C++ e o Número da Porta na qual o listener SQL*Net em execução no contêiner de VMs EXTPROC está aceitando solicitações de conexão. O parâmetro é especificado como uma string no formato `host_name:port_number`. Por exemplo: `'extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com:16000'` Este parâmetro é obrigatório.
`library_wallet_dir_name`	Especifica o nome do DIRECTORY no banco de dados no qual a wallet autoassinada foi importada e armazenada.
`library_ssl_server_cert_dn`	Especifica o DN (Distinguished Name) do certificado do servidor obtido da wallet. Por exemplo: `'CN=extproc-agent-170798'` Este parâmetro é obrigatório.
`library_remote_path`	Especifica o nome do caminho completo do diretório na VM EXTPROC, onde a biblioteca que contém os procedimentos externos é armazenada. Por exemplo: `'/u01/app/oracle/extproc_libs/helloCextproc.so'` Este parâmetro é obrigatório.

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

Erros

Código de Erro	Descrição
`ORA-20000`	Este erro é gerado na seguinte condição: - O valor `cloud_params` está ausente ou valores de parâmetro incorretos foram transmitidos.
`ORA-20001`	Este erro é gerado na seguinte condição: - A credencial referenciada no `credential_name` não existe.
`ORA-20002`	Este erro é gerado na seguinte condição: - Este erro é gerado quando o catálogo já existe.
`ORA-20009`	Este erro é gerado quando o prestador de serviço não existe.

Observações de Uso

Para criar um catálogo, você deve estar conectado como usuário ADMIN ou ter privilégios no seguinte:
- DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE
- DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE_INVOKE_FUNCTION_RESPONSE_T
- DBMS_CLOUD
- Privilégio de leitura em USER_CLOUD_FUNCTION
- Privilégio de leitura em USER_CLOUD_FUNCTION_CATALOG

Procedimento CREATE_FUNCTION

Você pode criar manualmente uma Função SQL que chame sua função de nuvem correspondente em seu catálogo. Enquanto SYNC_FUNCTIONS recupera e cria automaticamente wrappers para todas as funções de nuvem em um catálogo, CREATE_FUNCTION permite que você crie funções com tipos de retorno personalizados e handlers de resposta. O Procedimento CREATE_FUNCTION só se aplica ao Cloud Functions.

Sintaxe

O procedimento DBMS_CLOUD_FUNCTION.CREATE_FUNCTION só é suportado para funções de nuvem.

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

O response_handler deve ser definido neste formato:

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

O valor de retorno do response_handler é 'Tipo Definido pelo Usuário' e o response_json é um documento JSON com dois campos, no seguinte formato:

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

Parâmetros

Parâmetro	Descrição
`credential_name`	Especifica o nome da credencial para autenticação. Este parâmetro é obrigatório.
`catalog_name`	Especifica o nome do catálogo. Este parâmetro é obrigatório.
`function_name`	Especifica o nome da função PL/SQL. Este parâmetro é obrigatório.
`function_id`	O valor do parâmetro `function_id` se refere à função OCI ou ao AWS Lambda. Este parâmetro é obrigatório.
`input_args`	Especifica o par JSON de valor de chave aceitando argumentos de entrada e seus tipos.
`return_type`	Define o tipo de retorno da função. O tipo de retorno é do tipo de dados `CLOB`.
`response_handler`	Especifica o callback definido pelo usuário para tratar a resposta.

Erros

Código de Erro	Descrição
`ORA-20001`	Esse erro é gerado quando a credencial referenciada no `credential_name` não existe.
`ORA-20003`	Este erro é gerado quando o catálogo especificado não existe.
`ORA-20004`	Este erro é gerado quando a função especificada já existe.
`ORA-20005`	Este erro é gerado quando o ID da função ou a função Amazon Resource Names (ARN) não existe.
`ORA-20006`	Este erro é gerado quando os argumentos de entrada são inválidos.
`ORA-20007`	Este erro é gerado quando o tipo de retorno está ausente ou é inválido.
`ORA-20008`	Este erro é gerado quando o handler de resposta está ausente ou é inválido.

Exemplo

O caso simples com apenas parâmetros de entrada para a função:

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

Exemplo com tipo de retorno e handler de resposta:

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

Em seguida, use esse tipo e handler de resposta durante a criação manual da Função SQL Wrapper.

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

Assim que a função é criada, você pode DESCRIBE para obter os detalhes de retorno dela.

DESC fintech_fun
COLUMN STATUS format a30
COLUMN OUTPUT format a30

Você pode então chamar a função, fornecendo valores para os 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;
/

Isso chama a função de nuvem fintech_fun chamando a referência de função oocid1.funfn.oci.phx.aaaaaa_example no catálogo OCI_DEMO_CATALOG.

Observações sobre Uso

Para chamar Procedimentos Externos, você pode usar a mesma sintaxe usada para Funções Definidas pelo Usuário. Por exemplo, se você tiver criado uma biblioteca chamada EXTPROC_LIBRARY em seu banco de dados usando o Procedimento CREATE_CATALOG para Procedimentos Externos, poderá definir uma função SQL como mostrado neste exemplo e chamá-la de uma instrução 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

Procedimento DROP_CATALOG

O procedimento DBMS_CLOUD_FUNCTION.DROP_CATALOG elimina o catálogo e as funções criadas usando o catálogo.

Sintaxe

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    catalog_name      IN VARCHAR2
 );

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`catalog_name`	Especifica o nome do catálogo. Este parâmetro é obrigatório.

catalog_name

Especifica o nome do catálogo.

Este parâmetro é obrigatório.

Erros

Código de Erro	Descrição
`ORA-20003`	Este erro é gerado quando o catálogo especificado não existe.

Exemplo:

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

Procedimento DROP_FUNCTION

O procedimento DBMS_CLOUD_FUNCTION.DROP_FUNCTION elimina a função.

Sintaxe

O procedimento DBMS_CLOUD_FUNCTION.DROP_FUNCTION só é suportado para funções de nuvem.

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

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`catalog_name`	Especifica o nome do catálogo. Este parâmetro é obrigatório.
`function_name`	Especifica o nome da função a ser eliminada. Este parâmetro é obrigatório.

catalog_name

Especifica o nome do catálogo.

Este parâmetro é obrigatório.

function_name

Especifica o nome da função a ser eliminada.

Este parâmetro é obrigatório.

Erros

Código de Erro	Descrição
`ORA-20003`	Este erro é gerado quando a função especificada não existe.

Exemplos

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

Procedimento LIST_FUNCTIONS

Este procedimento lista todas as funções em um catálogo.

Observação: O Procedimento LIST_FUNCTIONS só se aplica a Funções da Nuvem.

Sintaxe

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

Parâmetros

Parâmetro Descrição

credential_name

Especifica o nome da credencial para autenticação.

Este parâmetro é obrigatório.

function_list

Retorna a lista de funções no formato JSON.

Este parâmetro é obrigatório.

catalog_name

Especifica o nome do catálogo.

Este parâmetro é obrigatório.

Erros

Código de Erro	Descrição
`ORA-20000`	Este erro é gerado quando valores de parâmetro incorretos são passados.
`ORA-20001`	Esse erro é gerado quando a credencial referenciada no `credential_name` não existe.
`ORA-20003`	Este erro é gerado quando o catálogo especificado não existe.

Exemplo:

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;

Procedimento SYNC_FUNCTIONS

Este procedimento permite adicionar novas funções ao catálogo e remover funções que foram excluídas do catálogo.

Observação: O Procedimento SYNC_FUNCTIONS só se aplica a Funções do Cloud.

Sintaxe

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

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`catalog_name`	Especifica o nome do catálogo. Este parâmetro é obrigatório.
`refresh_rate`	Especifica a taxa de atualização da função. `refresh_rate` pode aceitar os seguintes valores: `HOURLY` `DAILY` `WEEKLY` `MONTHLY` O valor default para esse parâmetro é `DAILY`.

catalog_name

Especifica o nome do catálogo.

Este parâmetro é obrigatório.

refresh_rate

Especifica a taxa de atualização da função.

refresh_rate pode aceitar os seguintes valores:

HOURLY
DAILY
WEEKLY
MONTHLY

O valor default para esse parâmetro é DAILY.

Erros

Código de Erro	Descrição
`ORA-20003`	Este erro é gerado quando o catálogo especificado não existe.
`ORA-20004`	Este erro é gerado quando um valor inválido é informado para o parâmetro `refresh_rate`.

Exemplo:

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