Chamar Funções da Nuvem e Procedimentos Externos

Em um Oracle Database local (Enterprise, Standard, Express, Personal Editions), você pode criar funções definidas pelo usuário em PL/SQL, Java ou C para fornecer uma funcionalidade que não está disponível em funções incorporadas SQL ou SQL. Você pode chamar essas funções definidas pelo usuário em uma instrução SQL sempre que uma expressão puder ocorrer. Consulte Sobre Funções Definidas pelo Usuário.

A partir do Oracle Database 19c, você pode criar, armazenar e executar scripts Python usando o recurso de execução Python Embedded no SQL. Consulte Execução de Python Incorporada usando OML4Py.

O Autonomous AI Database on Dedicated Exadata Infrastructure da Oracle estende o recurso de funções definidas pelo usuário para a nuvem, permitindo que você grave Funções SQL que chamem serviços de computação sem servidor na nuvem, como a OCI Functions e AWS Lambda Functions ou External Procedures - que incluem rotinas C/C++, scripts Shell ou Python - em execução em uma VM de computação do OCI externa ao Autonomous AI Database.

Tópicos Relacionados

Sobre o Serviço Cloud Functions e External Procedures

As funções definidas pelo usuário permitem chamar funções disponíveis externamente do código PL/SQL ou SQL no banco de dados. Você pode chamar as seguintes funções externas usando funções definidas pelo usuário:

  • Oracle Cloud Infrastructure Functions: O Oracle Cloud Infrastructure Functions é uma plataforma Functions-as-a-Service totalmente gerenciada, multitenant, altamente escalável e sob demanda. O Oracle Cloud Infrastructure Functions é criado no Oracle Cloud Infrastructure de nível corporativo e com tecnologia pelo mecanismo de código aberto do Projeto Fn. Consulte Visão Geral do Serviço OCI Functions para obter mais informações.
  • Funções AWS Lambda: O AWS Lambda é um serviço de computação orientado a eventos e sem servidor que permite executar código para praticamente qualquer aplicativo ou serviço de backend sem provisionar ou gerenciar servidores. Consulte AWS Lambda para obter mais informações.
  • Procedimentos Externos: OS procedimentos externos são funções escritas em uma linguagem de terceira geração (C, por exemplo), scripts de shell do SO ou scripts Python que podem ser chamados como funções SQL ou procedimentos ou funções PL/SQL. Consulte O que é um Procedimento Externo para obter mais informações.

Chamar o OCI Cloud Functions como Funções SQL

Mostra as etapas para chamar funções de nuvem do OCI como funções SQL em seu Autonomous AI Database on Dedicated Exadata Infrastructure.

Antes de prosseguir com essas etapas, supõe-se que você tenha criado e implantado o OCI Functions em uma tenancy e compartimento do OCI. Consulte Funções do OCI para obter detalhes.

Depois de trabalhar com as Funções do OCI, você usará as APIs PL/SQL DBMS_CLOUD e DBMS_CLOUD_FUNCTION para criar um catálogo de funções de encapsulador SQL no Autonomous AI Database que fazem referência e chamam sua respectiva função de nuvem por meio de seus pontos finais de API. Você usará a API DBMS_CLOUD_FUNCTION para gerenciar as funções do seu aplicativo de banco de dados.

  1. Crie credenciais usando o Procedimento DBMS_CLOUD.CREATE_CREDENTIAL.

    Informe a chave Privada da API do usuário da tenancy do OCI (conteúdo do arquivo dot-pem que você fez download ao criar a chave de API) como o objeto de credencial, a impressão digital da chave, o OCID da tenancy e o OCID do usuário. Consulte Chaves e OCIDs Obrigatórios. 

    SET DEFINE OFF
BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL (
       credential_name => 'OCI_CRED', -- provide a string as the name
       user_ocid       => 'user_ocid', -- provide the OCID string for the user, obtained from OCI Console User Profile
       tenancy_ocid    => 'tenancy_ocid', -- provide the OCID string for the tenancy, obtained from OCI Console User Profile
       private_key     => 'private_key', -- provide the content of the dot-pem file that you downloaded when you created the API Key
       fingerprint     => 'fingerprint' -- provide the fingerprint string for the API key
  );
END;
/

    Isso cria o objeto de credencial OCI_CRED.

    Consulte CREATE_CREDENTIAL Procedures para obter mais informações.

  2. Crie um objeto Catálogo usando o Procedimento DBMS_CLOUD_FUNCTION.CREATE_CATALOG.

    Um catálogo é uma coleção de funções wrapper que fazem referência e chamam suas respectivas funções de nuvem por meio de seus pontos finais de API. Forneça o objeto de credencial, o nome do provedor de serviços em nuvem - neste caso, o OCI e o ID da Região do OCI (PHX neste exemplo) e o ID do Compartimento do OCI no qual as Funções do OCI estão localizadas.

    BEGIN
DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
    credential_name  => 'OCI_CRED',
    catalog_name     => 'OCI_DEMO_CATALOG',
    service_provider => 'OCI',
    cloud_params     => '{"region_id":"phx", "compartment_id":"compartment_id"}'
);
END;
/

    Isso cria o objeto de catálogo OCI_DEMO_CATALOG.

    Consulte CREATE_CATALOG Procedures para obter mais informações. Você pode consultar DBA_CLOUD_FUNCTION_CATALOG View e USER_CLOUD_FUNCTION_CATALOG View para recuperar a lista de todos os catálogos de funções na nuvem no seu banco de dados.

  3. Você pode listar todas as funções de nuvem no catálogo usando o Procedimento DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS.

    SET PAGESIZE 1000

VAR function_list CLOB;

BEGIN
    DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS (
      credential_name  => 'OCI_CRED', 
      catalog_name     => 'OCI_DEMO_CATALOG',
      function_list    => :function_list
 );
END;
/

PL/SQL procedure successfully completed.

SELECT JSON_QUERY (:function_list, '$' RETURNING VARCHAR2(32676) pretty) AS search_results FROM dual;

SEARCH_RESULTS
------------------------------------------------------------------------------------------------
[
  {
    "functionName"   : "create_par",
    "functionId"     : "ocid.funfc.oc1.phx.aaaa_example", 
    "invokeEndpoint" : "https://dw.us.func.oci.oraclecloud_example.com"
  },
  {
    "functionName"   : "fintech",
    "functionId"     : "ocid.funfc.oc1.phx.bbbb_example"
    "invokeEndpoint" : "https://dw.us.func.oci.oraclecloud.com_example"
  },
  {
    "functionName"   : "jwt_codec",
    "functionId"     : "ocid.funfc.oc1.phx.jwt_code_example", 
    "invokeEndpoint" : "https://dw.us.func.oci.oraclecloud_example.com"
  },
  {
    "functionName"   : "oci-objectstorage-create-par-python",
    "functionId"     : "ocid.funfc.oc1.phx.aaaaaaaas_example", 
    "invokeEndpoint" : "https://dw.us.func.oci.oraclecloud_example.com"
  },
  {
    "functionName"   : "run_dbt",
    "functionId"     : "ocid.funfc.oc1.phx.aaaaaaaav_example",
    "invokeEndpoint" : "https://dw.us.func.oci.oraclecloud_example.com"
  }
]

    Consulte LIST_FUNCTIONS Procedures para obter mais informações.

  4. Crie a Função SQL Wrapper. Você pode usar um dos dois métodos a seguir para criar as funções SQL wrapper do catálogo, que chamam suas respectivas funções de nuvem:

    • Você pode usar o DBMS_CLOUD_FUNCTION. SYNC_FUNCTIONS Procedimento para gerar wrappers SQL do objeto do catálogo.
    • Você pode criar manualmente funções de encapsulador individuais usando DBMS_CLOUD_FUNCTION. CREATE_FUNCTION Procedimento.
    1. SYNC_FUNCTIONS: SYNC_FUNCTIONS sincroniza automaticamente (cria e/ou atualiza) funções de encapsulador no catálogo com a lista completa de funções de nuvem definidas na região, no compartimento e na tenancy com as quais o catálogo foi criado.
      BEGIN
 DBMS_CLOUD_FUNCTION.SYNC_FUNCTIONS (
        catalog_name => 'OCI_DEMO_CATALOG'
 );
END;
/

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

      Você pode verificar os resultados da sincronização usando a consulta a seguir para um determinado usuário atual.

      SHOW user
TEST_USER

SELECT object_name FROM sys.all_objects WHERE owner='TEST_USER' AND object_type='FUNCTION';

OBJECT_NAME
--------------------------------------------------------------------------------
CREATE_PAR
FINTECH
JWT_CODEC
OCI-OBJECTSTORAGE-CREATE-PAR-PYTHON
RUN_DBT

      Consulte SYNC_FUNCTIONS Procedures para obter mais informações.

    2. CREATE_FUNCTION: Você pode criar manualmente uma Função SQL no seu catálogo que chame sua respectiva função de nuvem usando DBMS_CLOUD.CREATE_FUNCTION. 

      VAR function_args CLOB;

EXEC :function_args := TO_CLOB('{"command": "VARCHAR2", "value": "VARCHAR2"}');

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       => :function_args
 );
END;
/

      Isso cria a função FINTECH_FUN no catálogo OCI_DEMO_CATALOG, como referência à respectiva função de nuvem cujo ponto final é referenciado pelo parâmetro FUNCTION_ID. Chamar a função no catálogo junto com seus argumentos executa a função de nuvem correspondente no OCI e fornece a saída retornada pela função de nuvem.

      Observação:

      O nome da Função do OCI pode ser totalmente diferente de FINTECH_FUNCTION. Somente o OCID da Função do OCI que você fornece como entrada para o parâmetro function_id é levado em consideração para criar essa referência.

    3. CREATE_FUNCTION com tipos de retorno personalizados e handlers de resposta: A criação manual de funções permite que você crie tipos de retorno personalizados e handlers de resposta, e mostrados no exemplo a seguir.

      Primeiro, crie um tipo de retorno e o handler de resposta da função.

      CREATE OR REPLACE TYPE fintech_rt AS OBJECT (
    status VARCHAR2(1000),  
    output CLOB
);
/
Type created.

CREATE OR REPLACE FUNCTION fintech_response_handler(function_response IN CLOB) 
RETURN fintech_rt
IS
      l_comp     fintech_rt;
      l_json_obj JSON_OBJECT_T;
      status     VARCHAR2(1000);
      output     CLOB;
BEGIN
      l_json_obj := JSON_OBJECT_T.parse(function_response); 
      status     := l_json_obj.get('STATUS').to_string;
      output     := l_json_obj.get('RESPONSE_BODY').to_string;
      l_comp     := fintech_rt(status,output);
      RETURN l_comp;
END;
/
Function created.

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

      Você pode consultar as exibições DBA_CLOUD_FUNCTION View e USER_CLOUD_FUNCTION View para recuperar a lista de todas as funções do seu banco de dados.

      Consulte CREATE_FUNCTION Procedures para obter mais informações.

      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 os valores para 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.

  5. Você pode eliminar uma função existente usando o procedimento DROP_FUNCTION.

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

    Isso elimina a função FINTECH_FUN do catálogo OCI_DEMO_CATALOG.

    Consulte DROP_FUNCTION Procedures para obter mais informações.

  6. Você pode eliminar um catálogo existente usando o procedimento DROP_CATALOG.

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

    Isso elimina o OCI_DEMO_CATALOG do seu banco de dados.

    Consulte DROP_CATALOG Procedures para obter mais informações.

Chamar Funções do AWS Lambda como Funções SQL

Mostra as etapas para chamar funções remotas da AWS como funções SQL no Autonomous AI Database on Dedicated Exadata Infrastructure.

Antes de prosseguir com essas etapas, presume-se que você tenha criado e implantado o AWS Lambda Functions em uma tenancy da AWS. Consulte AWS Lambda para obter detalhes.

Para acessar as funções do AWS lambda, você precisa configurar as políticas necessárias no Oracle Cloud Infrastructure. Consulte Criando uma política do serviço IAM para acessar recursos do AWS Lambda e Usando políticas baseadas em recursos para o Lambda para obter mais informações.

Após trabalhar nas funções do AWS Lambda, você usará as APIs PL/SQL DBMS_CLOUD e DBMS_CLOUD_FUNCTION para criar um catálogo de funções de encapsulador SQL no Autonomous AI Database que fazem referência e chamam sua respectiva função de nuvem por meio de seus pontos finais de API. Você usará a API DBMS_CLOUD_FUNCTION para gerenciar as funções do seu aplicativo de banco de dados.

  1. Crie uma credencial usando o procedimento DBMS_CLOUD.CREATE_CREDENTIAL usando a Chave Secreta da AWS como objeto de credencial.
    SET DEFINE OFF

BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL (
    credential_name => 'AWS_CRED',
    username        => 'access_key_ID', -- ID of Secret Key
    password        => 'secret_access_key' -- Secret Key password
  );
END;
/

    Isso cria o objeto de credencial AWS_CRED.

    Consulte CREATE_CREDENTIAL Procedures para obter mais informações.

  2. Crie um objeto Catálogo usando o Procedimento DBMS_CLOUD_FUNCTION.CREATE_CATALOG.

    Um catálogo é uma coleção de funções wrapper que fazem referência e chamam suas respectivas funções de nuvem por meio de seus pontos finais de API. Forneça o objeto de credencial, o nome do provedor de serviços em nuvem - neste caso, a AWS e o ID da Região da AWS (ap-northeast-1 neste exemplo) no qual as Funções do AWS Lambda estão localizadas. 

    BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
        credential_name  => 'AWS_CRED', 
        catalog_name     => 'AWS_DEMO_CATALOG', 
        service_provider => 'AWS',
        cloud_params     => '{"region_id":"ap-northeast-1"}'
 );
END;
/

    Isso cria o objeto de catálogo AWS_DEMO_CATALOG.

    Consulte CREATE_CATALOG Procedures para obter mais informações. Você pode consultar DBA_CLOUD_FUNCTION_CATALOG View e USER_CLOUD_FUNCTION_CATALOG View para recuperar a lista de todos os catálogos do seu banco de dados.

    O restante das etapas/operações - ou seja, Procedimento LIST_FUNCTIONS, Procedimento SYNC_FUNCTIONS, Procedimento CREATE_FUNCTION, Procedimento DROP_FUNCTION e Procedimento DROP_CATALOG - têm o mesmo uso descrito para funções de nuvem do OCI. Consulte Chamar OCI Cloud Functions como SQL Functions.

Visão geral de procedimentos externos

Fornece uma visão geral de Procedimentos Externos e seu uso em aplicativos Autonomous AI Database on Dedicated Infrastructure.

procedures externos são funções escritas em uma linguagem de terceira geração e chamadas como funções SQL ou procedimentos ou funções PL/SQL. O SQL e o PL/SQL são adequados para um processamento rápido e eficiente de dados e transações no banco de dados. Os procedimentos externos podem complementar SQL e PL/SQL executando tarefas de computação e memória intensiva em uma VM externa dedicada e fornecendo os resultados de volta ao banco de dados. Exemplos típicos de tais tarefas são problemas científicos e de engenharia cujas bibliotecas computacionais existem no sistema operacional Linux (e não são facilmente portáveis para uma plataforma de dados), análise de dados off-line, controle de dispositivos e processos em tempo real e assim por diante.

Você pode chamar e usar procedimentos externos no seu Autonomous AI Database com funções definidas pelo usuário. Em vez de executar esses procedimentos no banco de dados, você colocará o código executável em uma VM dedicada e personalizada do OCI Linux que é provisionada com um contêiner e runtime para executar programas C, scripts Shell e scripts Python, juntamente com bibliotecas Oracle SQL*Net para permitir a execução remota de SQL do banco de dados.

Observação:

O host remoto para procedimentos externos deve ser uma VM EXTPROC do OCI Linux provisionada pelo OCI Marketplace e configurada em uma VCN (Virtual Cloud Network) do OCI adequada. Consulte Configuração do Sistema no OCI para Scripts e Procedimentos Externos para obter detalhes.

A execução remota na VM EXTPROC do OCI Linux só é suportada pelo Autonomous AI Database on Dedicated Exadata Infrastructure no Oracle Public Cloud a partir da versão 19.30 e no Oracle Database 26ai, começando pela versão 23.26.1. Esse recurso ainda não é suportado pelo banco de dados Autonomous AI Database on Dedicated Exadata Infrastructure no Exadata Cloud@Customer (ExaCC).

Configuração do sistema para scripts e procedimentos externos

Mostra as etapas para provisionar a VM EXTPROC e as etapas para configurar a rede e a computação do OCI para executar procedimentos externos.

Minimamente, a arquitetura consiste nos seguintes recursos:

  • Rede Virtual na Nuvem do OCI provisionada em um Compartimento do OCI na tenancy do OCI.
  • Um Autonomous AI Database, criado como uma instância em um ACD (Autonomous Container Database), que é provisionado de um AVMC (Autonomous Exadata VM Cluster), criado no Exadata Infrastructure no Oracle Public Cloud.
  • Uma VM EXTPROC provisionada como parte de uma Pilha EXTPROC do OCI Marketplace.

Como prática recomendada, o cluster AVM será colocado em uma sub-rede privada em uma VCN. A tabela de roteamento Padrão e as Listas de Segurança da VCN serão configuradas de acordo com os requisitos do Autonomous AI Database na tenancy do OCI. A VCN pode ter uma tabela de Roteamento Padrão e uma Lista de Segurança Padrão, na qual você pode definir todas as regras de roteamento e segurança. Opcionalmente, a VCN poderá ser configurada com um gateway NAT se os aplicativos do Autonomous AI Database e outros recursos na sub-rede privada precisarem de acesso de Saída à Internet.

Siga estas etapas mínimas de configuração do OCI Networking ao introduzir a VM ExtProc nesta topologia.

  • Você deve poder fazer log-in na sua VM ExtProc para criar a biblioteca compartilhada (dot-so) com os procedimentos externos implementados em C/C++, inspecionar e configurar a VM e o contêiner e executar outras operações desse tipo.
  • A prática típica é configurar a VM EXTPROC para estar em uma sub-rede pública na VCN. Nesse caso, você deverá criar um Gateway de Internet na VCN (se ainda não tiver sido configurado pelo administrador).

    Observação:

    A VM EXTPROC NÃO deve estar em uma sub-rede cujo intervalo de CIDRs seja 10.x.x.x. Se o endereço IP da VM EXPROC for 10.x.x.x, ele não poderá se comunicar com o Autonomous AI Database.

  • Você deve definir uma regra de Entrada na Lista de Segurança da VCN para permitir acesso de log-in SSH à VM por meio da Porta 22. Você também deve definir uma regra de Saída na Lista de Segurança da VCN para permitir que o ADBD acesse a Porta de Destino 16000 para ser específica, ou todas as portas de destino, em geral. Consulte Acesso e Segurança de Rede do OCI.
  • Como parte do provisionamento da Pilha de VMs EXTPROC, você fornecerá todos os endereços IP do Cliente do AVMC. Você obterá esses endereços IP de Cliente IPv4 no Painel de Controle do OCI para o Cluster de AVM.
  • Posteriormente, a ferramenta de provisionamento criará automaticamente um grupo de segurança de rede (NSG) - chamado nsg_acl. Esse NSG terá uma Regra de Entrada que permite aos endereços IP do Cliente Dedicado do Autonomous Database serem as únicas origens que podem acessar o destino da Porta 16000.

Tópicos Avançados

  • Se as sub-redes que hospedam a VM ExtProc e o Autonomous AI Database estiverem na mesma VCN, não será necessário especificar nenhuma regra de roteamento especial na tabela de roteamento da VCN. Se as sub-redes que hospedam a VM ExtProc e o ADBD estiverem em VCNs diferentes, você deverá implementar o pareamento de VCN. Consulte Pareamento de VCN.
  • Se você optar por configurar a VM ExtProc para estar em uma sub-rede privada, poderá fazer log-in na VM por meio de um servidor bastion/jump-off e ativar a Entrada somente na VM ExtProc e proteger o acesso aos outros recursos na sub-rede privada, como o Autonomous AI Database. Consulte os Guias de Rede do OCI para obter detalhes.

Implementar Funções Definidas pelo Usuário com Procedimentos Externos

  1. Provisionar e Configurar a VM EXTPROC no OCI MarketPlace

    1. Acesse a Console do OCI em http://cloud.oracle.com. Consulte Acessar a Console do Oracle Cloud Infrastructure para mais informações.
    2. No menu de navegação esquerdo do Oracle Cloud Infrastructure, acesse o Marketplace e, em Marketplace, clique em Todos os Aplicativos.
    3. Insira "EXTPROC" na barra de pesquisa e clique em Pesquisar. Você verá dois widgets - um com label Stack e outro com label Image.
    4. Escolha o widget chamado Pilha (isso é importante). Isso levará você à página de detalhes do Oracle Autonomous Database EXTPROC Agent, fornecendo a versão da pilha, a data da release e as notas da release sobre a Pilha. Nesta página, clique no botão Iniciar Pilha. Isso o levará à próxima página Iniciar Pilha.

    5. Na página Ativar Pilha:

      • Na lista drop-down Versão, escolha a versão do pacote da pilha.
      • Na lista drop-down Compartimento, selecione o nome do compartimento no qual você deseja provisionar a VM EXTPROC. A menos que você tenha motivos específicos para não fazer isso, escolha o mesmo compartimento do ADBD (como prática recomendada, evite o compartimento raiz de qualquer recurso). Revise Configuração do Sistema para Scripts e Procedimentos Externos para fazer a escolha apropriada para o compartimento.
      • Aceite os termos e condições e clique em Iniciar Pilha.

      Isso o levará à próxima página - o assistente Criar Pilha.

    6. Nesta página, forneça um nome, uma descrição, um nome doCompartimento, a versão do Terraform e qualquer informação de Tag. O nome do compartimento é uma entrada obrigatória e mais importante para o assistente nesta página. Clique em Próximo.
    7. Isso leva você à página de variáveis de configuração da VM EXTPROC (também chamada de Agente EXTPROC). A primeira parte desta página reúne as informações sobre as bibliotecas EXTPROC e uma senha de wallet.
      • Para Bibliotecas Externas, forneça uma lista de bibliotecas, separadas por vírgula (,), que você deseja permitir que sejam chamadas do seu Autonomous AI Database on Dedicated Infrastructure. Essas bibliotecas compartilhadas conterão os procedimentos externos escritos em C/C++, que são compilados e construídos idealmente na própria VM (para combinar com a arquitetura e o ambiente).

        Observação:

        Como você ainda está no processo de criação da VM EXTPROC, anote os nomes das bibliotecas compartilhadas que você fornece aqui. Quando a VM estiver disponível e você desenvolver seus procedimentos externos em C/C++, lembre-se de compilar e criar a biblioteca/bibliotecas com o(s) nome(s) exato(s) fornecido(s) acima.
      • Para Senha da Wallet, forneça uma senha para o arquivo da wallet que será criado na VM ExtProc. A wallet e um certificado autoassinado são gerados para autenticação TLS mútua entre o Autonomous AI Database on Dedicated Infrastructure e a VM do Agente EXTPROC.
    8. A segunda parte da página de variáveis de configuração envolve a configuração de rede para a VM EXTPROC.
      • Para Compartimento, escolha no menu pull-down o nome do compartimento da VCN. No exemplo acima, ele é mostrado como adbd. Idealmente, o Autonomous AI Database e a VM EXTPROC serão co-localizados na mesma VCN, mesmo que em sub-redes diferentes (privadas e públicas).
      • Para Estratégia de Rede, escolha "Usar VCN e Sub-rede Existentes". Conforme mencionado em uma seção anterior, nesse estágio do seu esforço de desenvolvimento do ExtProc, você pode ter a arquitetura do sistema em vigor com uma VCN, AVMC e Autonomous AI Database.

        Observação:

        A outra opção é criar uma nova VCN e Sub-rede com sua própria estratégia de configuração para o Agente de VM EXTPROC. Conforme declarado na Configuração do Sistema para Procedimentos e Scripts Externos, se você optar por colocar a VM EXTPROC em uma VCN diferente da do Autonomous AI Database, deverá parear as VCNs.
      • Ignore a próxima entrada para Tipo de Acesso do Agente EXTPROC. Este campo não se aplica ao Autonomous AI Database on Dedicated Exadata Infrastructure.
    9. Em seguida, no campo rotulado "Endereços IP de Ponto Final Privado", insira TODOS os endereços IP do Cliente do AVMC no qual o banco de dados está configurado. Você pode obter esses endereços IP do Cliente no Painel de Controle da Console do OCI para o AVMC.
    10. Em seguida, forneça os detalhes da VCN e da Sub-rede.

      Observação:

      A VM EXTPROC NÃO deve estar em uma sub-rede cujo intervalo de CIDRs seja 10.x.x.x. Se o endereço IP da VM EXPROC for 10.x.x.x, ele não poderá se comunicar com o Autonomous AI Database.
    11. A parte final da página de configuração envolve a configuração de computação do Agente de VM EXTPROC.
      • Para Compartimento, escolha o nome do compartimento no menu pull-down. É recomendável colocar a VM no mesmo compartimento do Autonomous AI Database on Dedicated Infrastructure, da VCN e da sub-rede para minimizar a solução de problemas.
      • Para Forma, Número de OCPUs e Tamanho da memória (GBs), informe valores com base nas características da carga de trabalho de seus procedimentos externos.
      • Para Adicionar chaves SSH, gere OS arquivos de chave pública e privada SSH no sistema Linux OS, MacOS ou Windows. Abra uma janela de terminal e execute um dos seguintes comandos (ED25519 é o algoritmo moderno e mais seguro; sistemas mais antigos suportam o algoritmo de criptografia RSA):
        ssh-keygen -t ed25519 -C "your_email@example.com" (OR)
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

        Isso gerará um arquivo de chave privada ssh-key-<date-time-id>.key e um arquivo de chave pública ssh-key-<date-time-id>.key.pub. Copie e cole o conteúdo da chave pública SSH na janela ou arraste e solte o arquivo .pub na janela.

      • Clique em Próximo.

    12. Isso o levará à página de revisão. Verifique todas as entradas, marque a caixa de seleção Executar Aplicação e clique em Criar.

      Isso iniciará o OCI Resource Manager para criar a Pilha de VMs EXTPROC. Depois que o Job ORM for concluído com sucesso, a VM EXTPROC será criada e executada.

  2. Reunir informações do sistema de VM EXTPROC para entrada da API DBMS_CLOUD_FUNCTION

    Forneça informações do sistema de VMs EXTPROC como entradas para as APIs DBMS_CLOUD_FUNCTION no Autonomous AI Database para permitir a chamada de procedimentos externos do banco de dados.

    1. No menu de navegação esquerdo do Oracle Cloud Infrastructure, drop-down para Compute, escolha o compartimento especificado para o provisionamento de VMs EXTPROC e revise o painel de controle que lista todas as VMs no compartimento. O Job ORM terá criado a VM EXTPROC com um nome canônico EXTPROC-agent ou EXTPROC-agent-<setofnumbers>. Este será o nome do host da sua instância de VM EXTPROC. Clicar nessa entrada o levará à página que mostra os detalhes do sistema - os Endereços Públicos e Privados IPV4 (IPv4 e IPv6), a sub-rede e os detalhes da imagem.
    2. Faça log-in na VM ExtProc usando a chave SSH que você forneceu durante a criação da Pilha ExtProc e o endereço IP. O usuário padrão na VM é opc. sudo para se tornar usuário oracle.
      ➜  ~ ssh -i ssh-key-<date-time-id>.key opc@<Public-IP-Address>
Wed Nov 19 10:46:25 GMT 2025: EXTPROC Agent intialization completed.

Activate the web console with: systemctl enable --now cockpit.socket

Last login: Thu Nov 20 20:10:54 2025 from <client-IP-address>

[opc@extproc-agent-170798 ~]$ whoami
opc

[opc@extproc-agent-170798 ~]$ sudo su - oracle
Last login: Wed Nov 19 19:07:24 GMT 2025 on pts/0

      A VM EXTPROC terá um contêiner Podman em execução com um listener do Oracle SQL*Net. No contêiner, um ambiente cliente Oracle com os arquivos de configuração necessários, como sqlnet.ora, listener.ora, estará disponível, juntamente com um arquivo de wallet para comunicação segura com o Autonomous AI Database.

    3. Colete as informações do sistema necessárias para as APIs PL/SQL - no nível do sistema operacional e, em seguida, no contêiner do Podman configurado na VM. O contêiner executa o Oracle Listener para receber solicitações de execução remota do aplicativo SQL e PL/SQL no Autonomous AI Database e é o mecanismo de execução de runtime para o procedimento externo.
      • No sistema operacional Linux, o FQDN (nome de domínio totalmente qualificado) do host de VM EXTPROC.
      • No contêiner Podman, no status do listener, a Porta na VM EXTPROC na qual o banco de dados se conecta à VM.
      • No contêiner do Podman, na especificação sqlnet.ora, a localização do arquivo da wallet.
      • Em uma inspeção do arquivo da wallet usando a ferramenta orapki, o valor do parâmetro DN (Distinguished Name) do certificado da wallet.
      [oracle@extproc-agent-170798 ~]$ hostname -f
extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com

[oracle@extproc-agent-170798 ~]$ podman ps
CONTAINER ID  IMAGE                              COMMAND     CREATED       STATUS                 PORTS       NAMES
86d81c4df6ff  ghcr.io/oracle/adb-extproc:latest              23 hours ago  Up 23 hours (healthy)              adb-extproc

[oracle@extproc-agent-170798 ~]$ podman exec -it 86d81c4df6ff bash

(base) [oracle@extproc-agent-170798 admin]$ lsnrctl status

LSNRCTL for Linux: Version 23.26.0.0.0 - for Oracle Cloud and Engineered Systems on 20-NOV-2025 09:25:54

Copyright (c) 1991, 2025, Oracle.  All rights reserved.

Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=IPC)(KEY=EXTPROC1)))
STATUS of the LISTENER
------------------------
Alias                     LISTENER
Version                   TNSLSNR for Linux: Version 23.26.0.0.0 - for Oracle Cloud and Engineered Systems
Start Date                19-NOV-2025 17:19:58
Uptime                    0 days 16 hr. 5 min. 55 sec
Trace Level               off
Security                  ON: Local OS Authentication
SNMP                      OFF
Listener Parameter File   /u01/app/oracle/product/23.0.0.0/client_1/network/admin/listener.ora
Listener Log File         /u01/app/oracle/diag/tnslsnr/extproc-agent-170798/listener/alert/log.xml
Listening Endpoints Summary...
  (DESCRIPTION=(ADDRESS=(PROTOCOL=ipc)(KEY=EXTPROC1)))
  (DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=0.0.0.0)(PORT=16000)))
Services Summary...
Service "extproccontainer.com" has 1 instance(s).
  Instance "extproccontainer", status UNKNOWN, has 1 handler(s) for this service...
The command completed successfully

(base) [oracle@extproc-agent-170798 /]$ cd $ORACLE_HOME/network/admin

(base) [oracle@extproc-agent-170798 admin]$ cat sqlnet.ora

NAMES.DIRECTORY_PATH= (TNSNAMES, EZCONNECT)
WALLET_LOCATION =(SOURCE = (METHOD = FILE)(METHOD_DATA = (DIRECTORY = /u01/app/oracle/wallets/extproc_wallet)))
tcp.invited_nodes=(20.63.19.141,20.63.19.141,20.63.19.143,20.63.19.144)
tcp.validnode_checking=yes

(base) [oracle@extproc-agent-170798 admin]$ orapki wallet display -wallet /u01/app/oracle/wallets/extproc_wallet/cwallet.sso
Oracle PKI Tool Release 23.0.0.0.0 - Production
Version 23.0.0.0.0
Copyright (c) 2004, 2025, Oracle and/or its affiliates. All rights reserved.

Requested Certificates:
User Certificates:
Subject:        CN=extproc-agent-170798
Trusted Certificates:
Subject:        CN=extproc-agent-170798
(base) [oracle@extproc-agent-170798 admin]$ exit
exit
      No exemplo acima, coletamos as entradas a seguir para a API DBMS_CLOUD_FUNCTION.CREATE_CATALOG.
      • A string formada por FQDN + Número da Porta será a entrada para o parâmetro library_listener_url. Neste exemplo, é 'extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com:16000'.
      • sqlnet.ora contém o local do arquivo da wallet na VM: /u01/app/oracle/wallets/extproc_wallet/cwallet.sso. Observe a lista de endereços IP para tcp.invited_nodes. Ele deve conter a lista de endereços IP do Cliente que você forneceu como entrada para a configuração de rede ao criar a Pilha de VMs EXTPROC.
      • O DN (Certificate Distinguished Name) será a entrada do parâmetro library_ssl_server_cert_dn: 'CN=extproc-agent-170798'.
  3. Criar a Biblioteca C e colocá-la no local especificado no Sistema de Arquivos EXTPROC VM

    Codifique as Funções C, crie-as e coloque a biblioteca no diretório designado no sistema de arquivos da VM do Agente ExtProc.

    O nome da biblioteca deve corresponder exatamente ao(s) nome(s) que você forneceu durante a criação da Pilha ExtProc. Caso você o tenha colocado incorretamente, poderá encontrá-lo na entrada EXTPROC_DLLS do arquivo initextproccontainer.ora do contêiner ExtProc, conforme mostrado abaixo, ou na seção "Variáveis" do Job do ORM (Oracle Resource Manager) que criou a Pilha ExtProc. Você deve copiar as bibliotecas para o diretório /u01/app/oracle/extproc_libs na VM do agente EXTPROC.
    • O nome completo do caminho do arquivo (neste exemplo "/u01/app/oracle/extproc_libs/helloCextproc.so") será a entrada para o parâmetro library_remote_path de DBMS_CLOUD_FUNCTION.CREATE_CATALOG(). 
    (base) [oracle@extproc-agent-170798 client_1]$ cat $ORACLE_HOME/hs/admin/initextproccontainer.ora
SET TRACE_LEVEL=ON
SET _EXTPROC_REMOTE=TRUE
SET WHOAMI=FROMDOCKER
SET LD_LIBRARY_PATH=/u01/app/oracle/product/23.0.0.0/client_1/lib:/u01/app/oracle/extproc_libs:/opt/conda/lib
SET EXTPROC_DLLS=ONLY:/u01/app/oracle/product/extprocutils.so:/u01/app/oracle/product/23.0.0.0/client_1/lib/libgsfextproc.so:/u01/app/oracle/extproc_libs/helloCextproc.so
SET PYTHONHOME=/opt/conda
SET SCRIPTS_FOLDER_LOC_ENV=/u01/app/oracle/extproc_scripts
SET TRACE_FILE_LOC_ENV=/u01/app/oracle/extproc_logs
SET PYTHONPATH=/tmp:/u01/app/oracle/extproc_scripts
(base) [oracle@extproc-agent-170798 client_1]$ exit

[oracle@extproc-agent-170798 ~]$ cat > helloCextproc.c
#include <stdio.h>
const char* helloCextproc() {
        return ("\nHello C Extproc from FQDN: extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com\n");
}
^D

[oracle@extproc-agent-170798 ~]$ gcc -shared -fPIC -o /u01/app/oracle/extproc_libs/helloCextproc.so helloCextproc.c

[oracle@extproc-agent-170798 ~]$ ls -al /u01/app/oracle/extproc_libs/
total 8
drwxr-xr-x. 2 oracle oinstall   30 Nov 19 11:14 .
drwxr-xr-x. 6 root   root       91 Nov 14 02:19 ..
-rwxr-xr-x. 1 oracle oinstall 8184 Nov 19 11:14 helloCextproc.so
[oracle@extproc-agent-170798 ~]$

    Isso concluirá todas as entradas de parâmetro necessárias para criar o objeto Catálogo/Biblioteca no aplicativo de banco de dados.

  4. Faça upload do arquivo da wallet da VM ExtProc para o OCI Object Storage

    Uma wallet autoassinada é criada como parte da criação do aplicativo do agente EXTPROC. Essa wallet permite que você acesse a instância do agente Extproc.

    Para executar procedimentos remotos na instância do agente EXTPROC, o Autonomous AI Database e o agente EXTPROC se conectam usando o mTLS (Mutual Transport Layer Security). Ao usar o mTLS (Mutual Transport Layer Security), os clientes se conectam por meio de uma conexão do banco de Dados TCPS (Secure TCP) usando o TLS 1.2 padrão com um certificado da autoridade de certificado (CA) do cliente confiável.

    Observação:

    Você também pode obter e usar um certificado público emitido por uma Autoridade de Certificação (CA).

    Como pré-requisito, você deve exportar a wallet do diretório /u01/app/oracle/extproc_wallet na VM em que o EXTPROC é executado para o OCI Object Storage.

    Observação:

    • Proteja o arquivo da wallet. O arquivo da wallet, juntamente com o ID do usuário e a senha do Banco de Dados, fornecem acesso à instância do agente EXTPROC. Armazene os arquivos da wallet em um local seguro e compartilhe-os somente com usuários autorizados.
    • Não renomeie o arquivo da wallet. O arquivo da wallet no serviço Object Storage deve ser nomeado cwallet.sso.
  5. Criar o catálogo, definir Funções SQL e Chamar Procedimentos Externos como Funções SQL

    Nas etapas anteriores, temos todas as entradas necessárias para que as APIs DBMS_CLOUD_FUNCTION executem procedimentos remotos de aplicativos de banco de dados SQL ou PL/SQL.

    Em seguida, importe a wallet, cwallet.sso, que contém os certificados da instância do agente EXTPROC do serviço Object Storage para um DIRECTORY no seu Autonomous AI Database.

    Crie uma credencial para acessar o Object Storage no qual você armazenou o arquivo de wallet cwallet.sso. Consulte Procedimento CREATE_CREDENTIAL para obter informações sobre os parâmetros de nome de usuário e senha para diferentes serviços de armazenamento de objetos.

    Crie um objeto DIRECTORY no banco de dados e faça download da wallet no diretório usando a API DBMS_CLOUD.GET_OBJECT.

    SQL> SET DEFINE OFF

SQL> BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL (
	credential_name => 'OCI_CREDENTIAL',
	user_ocid       => '<oci_user_ocid>',
	tenancy_ocid    => '<oci_tenancy_ocid>',
	private_key     => '<API-key-dot-pem-file-contents>',
	fingerprint     => '<fingerprint-created-with-API-key>');
END;
/

SQL> CREATE DIRECTORY extprocwalletdir AS 'extprocwalletdir';

Directory created.

SQL> SELECT directory_name, directory_path FROM dba_directories WHERE directory_name LIKE '%EXTPROC%';

DIRECTORY_NAME    DIRECTORY_PATH
----------------  -------------------------------------------------------------------------
EXTPROCWALLETDIR  /u02/data/dbfs/<adbd-name>/42E945D608E16DF9E0630301000AF88D/extprocwalletdir

SQL> BEGIN
  DBMS_CLOUD.GET_OBJECT (
  credential_name     => 'OCI_CREDENTIAL',
  object_uri          => 'https://objectstorage.us-ashburn-1.oraclecloud.com/p/aN.../n/zr.../b/bucket-name-20260129/o/cwallet.sso',
  directory_name      => 'EXTPROCWALLETDIR'
  );
END;
/

    Em seguida, crie o Objeto da Biblioteca no banco de dados que representa a Biblioteca C no ExtProc, com os parâmetros de entrada que você reuniu na etapa anterior.

    SQL> 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;
/
PL/SQL procedure successfully completed.

SQL> SELECT catalog_name from DBA_CLOUD_FUNCTION_CATALOG WHERE catalog_name LIKE '%EXTPROC%';

CATALOG_NAME
---------------
EXTPROC_LIBRARY

    Crie a função SQL mapeada para a função ExtProc C. Veja o nome da função C do programa escrito acima.

    SQL> CREATE OR REPLACE FUNCTION HELLOCEXTPROC RETURN VARCHAR2 AS
    LANGUAGE C
    LIBRARY EXTPROC_LIBRARY
    NAME "helloCextproc";
/

Function created.

SQL>

    Chamar a Função SQL. É uma execução bem sucedida (veja o corpo da Função C da rotina C acima).

    SQL> SELECT HELLOCEXTPROC() FROM dual;

HELLOCEXTPROC()
----------------------------------------------------------------------------------
Hello C Extproc from FQDN: extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com