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.

Pré-requisitos

Para usar subprogramas no pacote DBMS_CLOUD_FUNCTION, você deve estar conectado como usuário ADMIN e conceder os seguintes privilégios:

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

Resumo dos Subprogramas DBMS_CLOUD_FUNCTION

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

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

CREATE_CATALOG Procedimento

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 de prestador de serviço. Esse parâmetro pode ter `OCI`, `AWS`, `AZURE` ou `GCP` 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, Regiões e Azure subscription_id. 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 de Erro	Descrição
`ORA-20000`	Este 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`	Este 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`	Este 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 durante a criação de 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 (
        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;
/

Observação do 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

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 o valor `cloud_params` está ausente ou valores de parâmetro incorretos são transmitidos.
`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:

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 Procedimento

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

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, AWS Lambda ou Azure. 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.

Exceções

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

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 Sintaxe 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 Tipo de Sintaxe 2

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 no `function_name` será usado.
`plsql_params`	Especifica o par JSON de valor de 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 variável. O modo variável pode ser uma das seguintes: `IN` `OUT` `IN OUT` `datatype` : especifica o tipo de dados da variável. Este parâmetro é obrigatório. O valor padrão 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 de volta com o banco de dados. O valor padrão para `with_context` é `FALSE`.
`return_type`	Especifica o tipo de retorno da função criada.

SYNC_FUNCTIONS Procedimento

Este procedimento cria um encapsulador PL/SQL para adicionar novas funções ao catálogo e remover encapsuladores 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 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;
/

DROP_FUNCTION Procedimento

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

DROP_CATALOG Procedimento

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 de Erro	Descrição
`ORA-20003`	Este erro é gerado quando o catálogo especificado não existe.

Exemplos

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

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

Documentação do Oracle Cloud Infrastructure

DBMS_CLOUD_FUNCTION - Pacote

Pré-requisitos

Resumo dos Subprogramas DBMS_CLOUD_FUNCTION

CREATE_CATALOG Procedimento

Sintaxe

Parâmetros

Erros

Exemplos

Observação do Uso

LIST_FUNCTIONS Procedimento

Sintaxe

Parâmetros

Erros

Exemplo:

CREATE_FUNCTION Procedimento

Sintaxe

Parâmetros

Exceções

Exemplo

Tipo de Sintaxe 2

Parâmetros para Tipo de Sintaxe 2

SYNC_FUNCTIONS Procedimento

Sintaxe

Parâmetros

Erros

Exemplo:

DROP_FUNCTION Procedimento

Sintaxe

Parâmetros

Exemplos

DROP_CATALOG Procedimento

Sintaxe

Parâmetros

Erros

Exemplos