DBMS_CLOUD_FUNCTION

DBMS_CLOUD_FUNCTION - Pacote

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

Observação:

O suporte para 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
CREATE_CATALOG Procedimento	Este procedimento cria um catálogo.
CREATE_FUNCTION Procedimento	Este procedimento cria funções em um catálogo.
DROP_CATALOG Procedimento	Este procedimento elimina um catálogo e funções criadas usando o catálogo.
DROP_FUNCTION Procedimento	Este procedimento elimina funções de um catálogo.
LIST_FUNCTIONS Procedimento	Este procedimento lista todas as funções em um catálogo.
SYNC_FUNCTIONS Procedimento	Este procedimento permite adicionar novas funções ao catálogo e remover funções que foram excluídas do catálogo.

CREATE_CATALOG Procedimento

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.

Sintaxe

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

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

Exemplos

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

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

CREATE_FUNCTION Procedimento

Este procedimento cria funções em um catálogo.

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

Assinatura do Handler de Resposta

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

O tipo de retorno é do tipo definido pelo usuário ou PL/SQL. O function_response é de JSON com campos.

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

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

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

DROP_CATALOG Procedimento

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

DROP_FUNCTION Procedimento

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

LIST_FUNCTIONS Procedimento

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

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;

SYNC_FUNCTIONS Procedimento

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

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 padrão 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 padrão 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;
/

Título e Informações de Copyright

Oracle e/ou suas empresas afiliadas.