Documentação do Oracle Cloud Infrastructure

Chamar Scripts Python com WITH_CONTEXT no Autonomous AI Database

Mostra as etapas para chamar scripts Python usando WITH_CONTEXT no seu banco de dados.

Tópicos

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

Sobre a Chamada de Scripts Python com WITH_CONTEXT no Autonomous AI Database

Você pode executar scripts Python em uma instância do Autonomous AI Database usando jobs do Oracle Scheduler com o atributo WITH_CONTEXT.

Quando você chama scripts Python com WITH_CONTEXT no Autonomous AI Database, um ponteiro de contexto é passado para o script que permite que o script chame de volta ao banco de dados. O contexto refere-se à sessão, à conexão e a qualquer estado ou dados associados que o script precise acessar ou manipular.

Você não pode executar um script Python diretamente em uma instância do Autonomous AI Database. Em vez disso, você hospeda o script remotamente em uma imagem de contêiner do Oracle Autonomous AI Database Extproc em execução em uma VCN (Virtual Cloud Network) da Oracle Cloud Infrastructure. A imagem do contêiner é pré-configurada com o agente EXTPROC e inclui todas as bibliotecas necessárias, como utils, onnx e python-oracledb, para executar o script.

Você chama scripts Python do seu Autonomous AI Database usando jobs do Oracle Scheduler. O job do Scheduler que você cria deve ser um job executável e é executado com o atributo WITH_CONTEXT. Os jobs executáveis podem executar scripts de shell ou outros executáveis e o atributo WITH_CONTEXT do Oracle Scheduler permite que um script herde os privilégios de sessão atuais ao chamar um procedimento, programa ou script externo. O atributo WITH_CONTEXT permite que rotinas externas acessem informações específicas da sessão, como esquema, privilégios e outras variáveis de contexto.

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

Observação

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

Você implanta scripts Python usando:

  • Uma imagem de contêiner do Autonomous AI 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 Autonomous AI Database e a instância do agente EXTPROC é protegida por meio da definição de regras do Grupo de Segurança de Rede (NSG), de modo que o tráfego seja permitido da instância do Autonomous AI 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 Python.

    Consulte DBMS_SCHEDULER para saber mais.

Siga estas etapas para executar um script Python com WITH_CONTEXT em uma instância do Autonomous AI Database:

Criar um Script Python

Mostra um exemplo de criação de um script Python

  • Exemplo: script Python para criar uma tabela no seu banco de dados.

    #!/usr/bin/env python1

import oracledb
import utils
 def gsf_main(argc, argv):
    table_name = argv[0]
    table_pk = argv[1]
    print(f"Total number of args: {argc}")
    print(f"Arg1: {table_name}")
    print(f"Arg2: {table_pk}")
    print(f"Arg3: {argv[2]}")
    print(f"Arg4: {argv[3]}")
    print(f"Arg5: {argv[4]}")
     
    # Step 1: Get connection object
    con = utils.getconnection()
    if con is None:
        print("Failed to establish database connection.")
        return -1
      try:
        # Step 2: Create a table
        cur = con.cursor()
        create_table_query = f"""
            CREATE TABLE {table_name} (
                employee_id NUMBER GENERATED ALWAYS AS IDENTITY (START WITH 1 INCREMENT BY 1),
                employee_name VARCHAR2(4000),
                employee_age NUMBER,
                CONSTRAINT {table_pk} PRIMARY KEY (employee_id)
            )
            """
        cur.execute(create_table_query)
    except Exception as e:
        print(f"Error performing operations: {e}")
        return -1
    finally:
        if cur:
            cur.close()

    Este exemplo cria o script python1.py. O script define uma função gsf_main(argc, argv) do Python que aceita argumentos de um job do Scheduler, cria uma tabela no banco de dados com os atributos fornecidos e trata exceções.

    O driver oracledb permite que o script se conecte ao banco de dados.

    O pacote utils fornece uma função auxiliar getconnection() para obter uma conexão de banco de dados.

Consulte a documentação do Python para obter mais informações.

Configurar Imagem do Contêiner EXTPROC do Oracle Autonomous AI Database

Descreve as etapas para obter e configurar a imagem do contêiner EXTPROC do Oracle Autonomous AI Database.

Uma imagem de contêiner do Autonomous AI Database fornecida pela Oracle com o agente EXTPROC instalado é hospedada nos pacotes GitHub. Consulte GitHub README para obter instruções e configurar a imagem do contêiner EXTPROC.

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 do Autonomous AI Database EXTPROC. Essa wallet permite que você acesse a instância do agente Extrpoc.

Para executar scripts Python na instância do agente EXTPROC, o Autonomous AI Database e o agente EXTPROC se conectam usando 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. Consulte Sobre a Conexão com uma Instância do Autonomous AI 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).

Primeiro, exporte a wallet para o serviço Object Storage do diretório /u01/app/oracle/extproc_wallet na VM em que o EXTPROC é executado.

Siga estas etapas para fazer upload da wallet para o Autonomous AI Database:

  1. Importe a wallet, cwallet.sso, que contém os certificados da instância do agente EXTPROC para o Autonomous AI Database do serviço Object Storage. 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 AI Database para o arquivo de wallet cwallet.sso.
    CREATE DIRECTORY wallet_dir AS 'directory_location';

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

  4. Use DBMS_CLOUD.GET_OBJECT para fazer upload da wallet. 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 que você se conecte à instância do agente EXTPROC agora está disponível na sua instância do Autonomous AI Database.

Etapas para Chamar Scripts Python

Mostra as etapas para chamar scripts Python em um Autonomous AI Database.

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

Estes são os pré-requisitos para chamar scripts Python no Autonomous AI Database:

  • Os scripts Python devem ser copiados para a instância do agente EXTPROC.

  • Para criar e gerenciar jobs do Scheduler para chamar scripts Python 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 Python com WITH_CONTEXT no Autonomous AI Database

Registrar e Gerenciar Ponto Final Remoto no Autonomous AI Database

Como usuário ADMIN, execute as etapas a seguir para registrar e gerenciar pontos finais remotos no Autonomous AI 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_endpoint_url no seu Autonomous AI Database. A instância do agente EXTPROC é pré-configurada para hospedar scripts Python 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ó é necessária quando um usuário diferente do ADMIN precisa chamar scripts Python do Autonomous AI 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 AI Database. Consulte DEREGISTER_REMOTE_EXECUTION_ENV Procedures para obter mais informações.

Criar e Gerenciar Jobs do Scheduler para Chamar Scripts Python

Mostra as etapas para criar e gerenciar jobs do scheduler para chamar scripts Python do Autonomous AI 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 Python para obter mais informações.
  1. Use DBMS_SCHEDULER.CREATE_JOB para criar um job do scheduler com o tipo de job como executable. Por exemplo:
    BEGIN
 DBMS_SCHEDULER.CREATE_JOB (
    job_name             => 'rem_exec_job',
    job_type             => 'executable',
    job_action           => '/script_location_on_extproc_agent_image/python1.py',
    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 Python no seu Autonomous AI 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. Este exemplo chama o script python1.py, criado em uma etapa anterior.

    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. Não é possível ativar um job do Oracle Scheduler que chame um script Python na criação; use DBMS_SCHEDULER.ENABLE para ativar o job após a criação do job.

    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    => 'job_param');
 END;
/

    Este exemplo define o primeiro argumento do job rem_exec_job como um valor String job_param. Quando o job é executado, ele passa job_param como o valor de seu primeiro parâmetro.

  3. Use DBMS_SCHEDULER.SET_ATTRIBUTE para modificar o atributo destination do job rem_exec_job. O atributo destination especifica o destino do ponto final remoto.

    Exemplo:

    BEGIN
 DBMS_SCHEDULER.SET_ATTRIBUTE (
      name       => 'rem_exec_job',
      attribute  => 'destination',
      value      => 'REMOTE_EXTPROC:remote_endpoint_name:WITH_CONTEXT');
 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:WITH_CONTEXT, em que remote_endpoint_name é o nome do ponto final remoto registrado. A cláusula WITH_CONTEXT permite que um script herde os privilégios de sessão atuais ao chamar um procedimento, programa ou script externo.

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