DBMS_CLOUD_FUNCTION Pacote

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

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

Tópico principal: Referência de Pacote Fornecida pelo Autonomous Database

Resumo de Subprogramas DBMS_CLOUD_FUNCTION

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

Subprograma	Descrição
Procedimento CREATE_CATALOG	Esse 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 cria um wrapper PL/SQL para adicionar novas funções ao catálogo e remover wrappers para funções que foram excluídas do catálogo.

Procedimento CREATE_CATALOG
Esse procedimento cria um catálogo no banco de dados. O procedimento DBMS_CLOUD_FUNCTION.CREATE_CATALOG cria um catálogo. Um catálogo é um conjunto de funções que cria a infraestrutura necessária para executar sub-rotinas. Este procedimento é sobrecarregado.
Procedimento CREATE_FUNCTION
Esse procedimento cria funções em um catálogo. Há dois procedimentos DBMS_CLOUD_FUNCTION.CREATE_FUNCTION sobrecarregados.
Procedimento DROP_CATALOG
O procedimento DBMS_CLOUD_FUNCTION.DROP_CATALOG elimina o catálogo e as funções criadas usando o catálogo. Este procedimento é sobrecarregado.
Procedimento DROP_FUNCTION
O procedimento DBMS_CLOUD_FUNCTION.DROP_FUNCTION elimina a função. Este procedimento é sobrecarregado.
Procedimento LIST_FUNCTIONS
Este procedimento lista todas as funções em um catálogo.
Procedimento SYNC_FUNCTIONS
Esse procedimento cria um encapsulador PL/SQL para adicionar novas funções ao catálogo e remover encapsuladores de funções que foram excluídas do catálogo.

Tópico principal: Pacote DBMS_CLOUD_FUNCTION

Procedimento CREATE_CATALOG

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

Sintaxe

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	Descrição
`credential_name`	Especifica o nome da credencial para autenticação. Este parâmetro é obrigatório.
`service_provider`	Especifica o tipo do provedor de serviços. Esse parâmetro pode ter `OCI`, `AWS`, `AZURE` ou `GCP` 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, Regiões e subscription_id do Azure. Este parâmetro é obrigatório.
`library_name`	Especifica o nome da biblioteca ao criar uma biblioteca remota. Este parâmetro é obrigatório.
`library_listener_url`	Especifica a localização remota da biblioteca. O parâmetro aceita um valor de String no formato `host_name:port_number`. Por exemplo: `EHRPMZ_DBDOMAIN.adb-us-phoenix1.com:16000` Este parâmetro é obrigatório.
`library_remote_path`	Especifica o caminho da biblioteca remota. Você deve fornecer o caminho absoluto completo para a biblioteca remota. Por exemplo:`/u01/app/oracle/product/21.0.0.0/client_1/lib/libst_shape.so` Este parâmetro é obrigatório.
`library_wallet_dir_name`	Especifica o diretório no qual a wallet autoassinada é armazenada. Este parâmetro é obrigatório.
`library_ssl_server_cert_dn`	Especifica o DN (Distinguished Name, Nome distinto) do certificado do servidor. Este parâmetro é obrigatório.

Erros

Código do Erro	Descrição
`ORA-20000`	Esse erro é gerado em uma das seguintes condições: O valor `cloud_params` está ausente ou valores de parâmetro incorretos foram informados. O valor `library_name` não é exclusivo ao criar uma biblioteca.
`ORA-20001`	Esse erro é gerado em uma das seguintes condições: A credencial referenciada em `credential_name` não existe. O Listener especificado em `library_listener_url` não pode ser acessado ao criar uma biblioteca.
`ORA-20002`	Esse erro é gerado em uma das seguintes condições: Este erro é gerado quando o catálogo já existe. O diretório de certificado do Servidor especificado está vazio ao criar uma biblioteca.
`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;
/

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

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

Nota de Uso

Para criar um catálogo, você deve estar conectado como o 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

Tópico principal: Resumo de Subprogramas DBMS_CLOUD_FUNCTION

Procedimento CREATE_FUNCTION

Este procedimento cria funções em um catálogo. Há dois procedimentos DBMS_CLOUD_FUNCTION.CREATE_FUNCTION sobrecarregados.

Sintaxe CREATE_FUNCTION

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 desse tipo é definido pelo usuário ou tipo PL/SQL. O function_response é de JSON com campos.

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

CREATE_FUNCTION Parâmetros

CREATE_FUNCTION Exceções

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` refere-se à função do OCI, AWS Lambda ou Azure. Este parâmetro é obrigatório.
`input_args`	Especifica o par JSON de valor-chave que aceita 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.

Código do Erro	Descrição
`ORA-20001`	Este erro é gerado quando a credencial referenciada em `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 ARN (Amazon Resource Names) 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.

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

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

CREATE_FUNCTION Parâmetros

Parâmetro	Descrição
`library_name`	Especifica o nome da biblioteca remota. 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` refere-se aos procedimentos externos (`extproc`). Se o valor de `function_id` não for fornecido, o valor em `function_name` será usado.
`plsql_params`	Especifica o par JSON de valor-chave que aceita os parâmetros do wrapper PL/SQL. Os valores devem ser fornecidos no formato `"var_name":"modetype, datatype"`. `var_name` : é o nome da variável. Este parâmetro é obrigatório. `modetype` : especifica o modo de variável. O modo de variável pode ser um dos seguintes: `IN` `OUT` `IN OUT` `datatype` : especifica o tipo de dados variável. Este parâmetro é obrigatório. O valor default para `plsql_params` é `NULL`.
`external_params`	Especifica os parâmetros que precisam ser fornecidos para a função C externa. Se o valor não for fornecido para `external_params`, os parâmetros PL/SQL serão usados.
`api_type`	Especifica o tipo de API (função ou procedimento). O valor padrão para `api_type` é `function`.
`with_context`	Especifica que um ponteiro de contexto é passado para o procedimento externo. Esse contexto é usado pela biblioteca C externa para estabelecer conexão com o banco de dados. O valor padrão para `with_context` é `FALSE`.
`return_type`	Especifica o tipo de retorno da função criada.

CREATE_FUNCTION Exemplo

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

Tópico principal: Resumo de Subprogramas DBMS_CLOUD_FUNCTION

Procedimento DROP_CATALOG

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

Sintaxe

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    catalog_name      IN VARCHAR2
 );

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    library_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.
`library_name`	Especifica o nome da biblioteca. Este parâmetro é obrigatório.

catalog_name

Especifica o nome do catálogo.

Este parâmetro é obrigatório.

library_name

Especifica o nome da biblioteca.

Este parâmetro é obrigatório.

Erros

Código do 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;
/

Exemplo:

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

Tópico principal: Resumo de Subprogramas DBMS_CLOUD_FUNCTION

Procedimento DROP_FUNCTION

O procedimento DBMS_CLOUD_FUNCTION.DROP_FUNCTION elimina a função. Este procedimento é sobrecarregado.

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

DBMS_CLOUD_FUNCTION.DROP_FUNCTION (
    library_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.
`library_name`	Especifica o nome da biblioteca. 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.

library_name

Especifica o nome da biblioteca.

Este parâmetro é obrigatório.

Exemplos

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

Tópico principal: Resumo de Subprogramas DBMS_CLOUD_FUNCTION

Procedimento LIST_FUNCTIONS

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 do Erro	Descrição
`ORA-20000`	Este erro é gerado quando o valor `cloud_params` está ausente ou quando valores de parâmetro incorretos são informados.
`ORA-20001`	Este erro é gerado quando a credencial referenciada em `credential_name` não existe.
`ORA-20003`	Este erro é gerado quando o catálogo especificado não existe.

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

Tópico principal: Resumo de Subprogramas DBMS_CLOUD_FUNCTION

Procedimento SYNC_FUNCTIONS

Este procedimento cria um wrapper PL/SQL para adicionar novas funções ao catálogo e remover wrappers para 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 desse 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 desse parâmetro é DAILY.

Erros

Código do 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`.

Por exemplo:


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

Tópico principal: Resumo de Subprogramas DBMS_CLOUD_FUNCTION

Documentação do Oracle Cloud Infrastructure