Documentação do Oracle Cloud Infrastructure

Chamar Scripts Genéricos em uma Instância do Autonomous Database

Você pode chamar scripts genéricos do tipo BASH, C ou Python no seu Autonomous Database.

Tópico principal: Chamar Funções Definidas pelo Usuário

Sobre a Execução de Scripts Genéricos no Autonomous Database

Você pode chamar scripts genéricos, incluindo scripts gravados em Bash, C ou Python, de uma instância do Autonomous Database.

Você não pode executar um script genérico diretamente em uma instância do Autonomous Database. Em vez disso, o script é hospedado remotamente em uma imagem de contêiner do Oracle Autonomous Database Extproc em execução em uma VCN (Virtual Cloud Network) da Oracle Cloud Infrastructure. Você chama scripts genéricos do seu Autonomous Database usando jobs do Oracle Scheduler. O job do Oracle Scheduler criado deve ser um job executável. Os trabalhos executáveis podem executar scripts de shell ou outros executáveis.

Observação

Esse recurso só é suportado para a release 19c do banco de dados Oracle.

Os scripts genéricos do seu Autonomous Database só são suportados quando o seu banco de dados está em um ponto final privado. Para executar scripts genéricos, obtenha, instale e configure a imagem do contêiner do Oracle Autonomous Database com o agente EXTPROC instalado. A imagem do contêiner EXTPROC do Autonomous Database permite chamar procedimentos externos e scripts gravados em BASH, C ou Python pelo seu Autonomous Database. A instância do agente EXTPROC é hospedada em uma sub-rede privada e o Autonomous Database acessa o agente EXTPROC por meio de um RCE (Reverse Connection Endpoint).

Scripts genéricos são implementados usando:

  • Uma imagem de contêiner do Autonomous Database fornecida pela Oracle com o agente EXTPROC instalado. O sistema Oracle fornece a imagem do contêiner nos pacotes GitHub.

    Consulte GitHub README para obter instruções e configurar a imagem do contêiner EXTPROC:

    A instância do agente EXTPROC é hospedada remotamente em uma imagem de contêiner em execução em uma VCN (Virtual Cloud Network) do Oracle Cloud Infrastructure. A comunicação segura entre o seu Autonomous Database e a instância do agente EXTPROC é protegida pela definição de regras de NSG (Grupo de Segurança de Rede) de modo que o tráfego seja permitido da sua instância do Autonomous Database em execução em um ponto final privado para a instância do agente EXTPROC. A imagem do agente EXTPROC é pré-configurada para hospedar e executar procedimentos externos na porta 16000.

  • Procedimentos PL/SQL para registrar ambientes de ponto final e gerenciar privilégios nos pontos finais registrados. Consulte DBMS_CLOUD_FUNCTION_ADMIN Package para obter mais informações.

  • Procedimentos PL/SQL para criar e gerenciar jobs e programas do scheduler para chamar scripts genéricos.

    Consulte DBMS_SCHEDULER para saber mais.

Siga estas etapas para executar um script genérico de uma instância do Autonomous Database:

Fazer Upload da Wallet para Criar Conexão Segura com a Instância do Agente EXTPROC

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 de uma instância do Autonomous Database.

Para executar scripts genéricos na instância do agente EXTPROC, o Autonomous Database e o agente EXTPROC se conectam usando o mTLS (Mutual Transport Layer Security). Ao estabelecer conexão com o agente EXTPROC com o mTLS, você usa uma conexão de banco de dados TCPS (TCP Seguro) usando o TLS 1.2 padrão com um certificado de autoridade de certificação (CA) cliente confiável. Consulte Sobre a Conexão com uma Instância do Autonomous Database para obter mais informações.

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 para o serviço Object Storage do diretório /u01/app/oracle/wallets/extproc_wallet/ na VM em que o EXTPROC é executado. Isso permite que o Autonomous Database use a wallet para acessar com segurança o EXTPROC.

Faça upload da wallet EXTPROC para sua instância do Autonomous Database:

  1. Importe a wallet, cwallet.sso, que contém os certificados da instância do agente EXTPROC do serviço Object Storage no seu Autonomous Database. Observe o seguinte para o arquivo de wallet:

    • O arquivo da wallet, juntamente com o ID de 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.

  2. Crie credenciais para acessar o Object Storage no qual você armazena o arquivo da 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.
    Não será necessário criar uma credencial para acessar o Oracle Cloud Infrastructure Object Store se você ativar as credenciais do controlador de recursos. Consulte Sobre o Uso do Controlador de Recursos para Acessar os Recursos da Oracle Cloud Infrastructure para obter mais informações.
  3. Crie um diretório no Autonomous Database para o arquivo de wallet cwallet.sso.
    CREATE DIRECTORY wallet_dir AS 'directory_location';

    Consulte Criar Diretório no Autonomous Database para obter mais informações sobre como criar diretórios.

  4. Use DBMS_CLOUD.GET_OBJECT para fazer download da wallet do serviço Object Storage. Por exemplo:
    BEGIN
  DBMS_CLOUD.GET_OBJECT (
    credential_name     => 'DEF_CRED_NAME',
    object_uri          => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/cwallet.sso',
    directory_name      => 'WALLET_DIR'
);
END;
/

    Neste exemplo, namespace-string é o namespace do Oracle Cloud Infrastructure Object Storage e bucketname é o nome do bucket. Consulte Namespaces do Serviço Object Storage para mais informações.

    A wallet é copiada para o diretório criado na etapa anterior, WALLET_DIR. A wallet que permite estabelecer conexão com a instância do agente EXTPROC agora está disponível na sua instância do Autonomous Database.

Etapas para Chamar Scripts Genéricos

Mostra as etapas para chamar scripts genéricos em um Autonomous Database.

Depois de configurar a instância do agente EXTPROC para executar scripts genéricos, você registra um ponto final remoto e cria jobs do Scheduler para chamar scripts genéricos.

Estes são os pré-requisitos para chamar scripts genéricos com o Autonomous Database:

  • Os scripts genéricos devem ser copiados para a instância do agente EXTPROC. Consulte GitHub README para obter mais informações.

  • Para criar e gerenciar jobs do Scheduler para chamar scripts genéricos com um usuário diferente de ADMIN, você deve ter os seguintes privilégios:

    • MANAGE SCHEDULER

    • CREATE JOB

    • Privilégio no ponto final remoto registrado

Tópicos

Tópico principal: Chamar Scripts Genéricos em uma Instância do Autonomous Database

Registrar e Gerenciar Ponto Final Remoto no Autonomous Database

Como usuário ADMIN, execute as etapas a seguir para registrar e gerenciar pontos finais remotos no seu Autonomous Database.

Registrar um Ponto Final Remoto

Use DBMS_CLOUD_FUNCTION_ADMIN.REGISTER_REMOTE_EXECUTION_ENV para registrar um ponto final remoto.

Exemplo:

BEGIN
 DBMS_CLOUD_FUNCTION_ADMIN.REGISTER_REMOTE_EXECUTION_ENV (
        remote_endpoint_name => 'rem_executable',
        remote_endpoint_url  => 'remote_extproc_hostname:16000',
        wallet_dir           => 'WALLET_DIR',
        remote_cert_dn       => 'CN=MACHINENAME'
);
END;
/

Este exemplo cria a biblioteca rem_executable e registra a instância do agente EXTPROC especificada no parâmetro remote_url no seu Autonomous Database. A instância do agente EXTPROC é pré-configurada para hospedar scripts genéricos na porta 16000.

Consulte REGISTER_REMOTE_EXECUTION_ENV Procedures para obter mais informações.

Gerenciar Privilégios em um Ponto Final Registrado

Essa etapa é opcional e só é obrigatória quando um usuário diferente do ADMIN precisa chamar scripts genéricos do Autonomous Database.

Use DBMS_CLOUD_FUNCTION_ADMIN.GRANT_REMOTE_EXECUTION_ENV para conceder privilégio no ponto final registrado a um usuário diferente do ADMIN.

Exemplo:

BEGIN
 DBMS_CLOUD_FUNCTION_ADMIN.GRANT_REMOTE_EXECUTION_ENV (   
    remote_endpoint_name => 'REM_EXECUTABLE',
    user_name            => 'username');
END;
/

Este exemplo concede privilégio em REM_EXECUTABLE para o usuário especificado. Consulte GRANT_REMOTE_EXECUTION_ENV Procedures para obter mais informações.

Depois de conceder privilégio no ponto final registrado, você poderá usar DBMS_CLOUD_FUNCTION_ADMIN.REVOKE_REMOTE_EXECUTION_ENV para revogar o privilégio no ponto final registrado em um usuário.

Exemplo:

BEGIN
 DBMS_CLOUD_FUNCTION_ADMIN.REVOKE_REMOTE_EXECUTION_ENV (   
    remote_endpoint_name => 'REM_EXECUTABLE',
    user_name            => 'username');
END;
/

Este exemplo revoga o privilégio em REM_EXECUTABLE do usuário especificado. Consulte REVOKE_REMOTE_EXECUTION_ENV Procedures para obter mais informações.

Você pode consultar o DBA_CLOUD_FUNCTION_REMOTE_EXECUTION_GRANT para listar as permissões concedidas para todos os pontos finais remotos. Consulte DBA_CLOUD_FUNCTION_REMOTE_EXECUTION_GRANT View para obter mais informações.

Remover um Ponto Final Registrado

Use DBMS_CLOUD_FUNCTION_ADMIN.DEREGISTER_REMOTE_EXECUTION_ENV para remover um ponto final remoto registrado.

Exemplo:

BEGIN
 DBMS_CLOUD_FUNCTION_ADMIN.DEREGISTER_REMOTE_EXECUTION_ENV (   
    remote_endpoint_name => 'REM_EXECUTABLE');
END;
/

Isso remove o ponto final remoto rem_executable do seu Autonomous Database. Consulte DEREGISTER_REMOTE_EXECUTION_ENV Procedures para obter mais informações.

Criar e Gerenciar Tarefas do Scheduler para Chamar Scripts Genéricos

Mostra as etapas para criar e gerenciar jobs do scheduler para chamar scripts genéricos do Autonomous Database.

Para executar as etapas a seguir como um usuário diferente de ADMIN, você deve ter os privilégios necessários. Consulte Etapas para Chamar Scripts Genéricos para obter mais informações.
  1. Use DBMS_SCHEDULER.CREATE_JOB para criar um job do scheduler com o tipo de job executable.

    Exemplo:

    BEGIN
 DBMS_SCHEDULER.CREATE_JOB (
    job_name             => 'rem_exec_job',
    job_type             => 'executable',
    job_action           => 'script_location_in_remote_docker_image/name',
    number_of_arguments  => 1,
    enabled              => false,
    auto_drop            => true);
 END;
/

    Este exemplo cria o job do scheduler rem_exec_job do tipo executável.

    O parâmetro job_name especifica o nome do job.

    O parâmetro job_type especifica o tipo de ação do job. Especifique o job_type como executável para chamar scripts genéricos no seu Autonomous Database.

    O parâmetro job_action especifica a ação em linha do job. Este é o local do script no ponto final remoto que você precisa chamar.

    O parâmetro number_of_arguments especifica o número de argumentos do job.

    O parâmetro enabled indica se o job deve ser ativado imediatamente após sua criação.

    O parâmetro auto_drop indica se o job deve ser eliminado depois de concluído.

  2. Use DBMS_SCHEDULER.SET_JOB_ARGUMENT_VALUE para definir o valor do argumento do job.

    Exemplo:

    BEGIN
 DBMS_SCHEDULER.SET_JOB_ARGUMENT_VALUE (
    job_name          => 'rem_exec_job',
    argument_position => 1,
    argument_value    => 'param1');
 END;
/
  3. Use DBMS_SCHEDULER.CREATE_JOB para modificar o atributo destination do job rem_exec_job.

    Exemplo:

    BEGIN
 DBMS_SCHEDULER.SET_ATTRIBUTE (
      name       => 'rem_exec_job',
      attribute  => 'destination',
      value      => 'REMOTE_EXTPROC:remote_endpoint_name');
 END;
/

    Este exemplo modifica o atributo destination do job rem_exec_job para especificar o caminho da biblioteca remota.

    O parâmetro job_name especifica o nome do job.

    O parâmetro attribute especifica o atributo a ser modificado.

    O parâmetro value modifica o atributo destination para especificar o destino do ponto final remoto.

    O parâmetro aceita um valor de String no formato REMOTE_EXTPROC:remote_endpoint_name, em que remote_endpoint_name é o nome do ponto final remoto registrado.

    Um erro será encontrado se você não tiver privilégios no ponto final especificado.

    Consulte DBMS_SCHEDULER Subprograms para obter mais informações.

  4. Execute DBMS_SCHEDULER.ENABLE o job do scheduler.

    Exemplo:

    BEGIN
 DBMS_SCHEDULER.ENABLE (
    name => 'rem_exec_job');
 END; 
/

    Este exemplo ativa o job rem_exec_job. Consulte DBMS_SCHEDULER para saber mais.

    Depois que você ativar o job, o Scheduler começará a executar o job.

    Consulte USER_CLOUD_FUNCTION_RUN_DETAILS View e DBA_CLOUD_FUNCTION_RUN_DETAILS View para exibir o status de seus jobs do Scheduler.