Documentación de Oracle Cloud Infrastructure

Llamada a scripts de Python con WITH_CONTEXT en una base de datos de IA autónoma

Muestra los pasos para llamar a scripts de Python mediante WITH_CONTEXT en la base de datos.

Temas

Tema principal: Llamada a funciones definidas por el usuario

Acerca de la llamada de scripts de Python con WITH_CONTEXT en una base de datos de IA autónoma

Puede ejecutar scripts de Python en una instancia de base de datos de IA autónoma mediante trabajos de Oracle Scheduler con el atributo WITH_CONTEXT.

Al llamar a scripts de Python con WITH_CONTEXT en Autonomous AI Database, se transfiere un puntero de contexto al script que permite que el script vuelva a llamar a la base de datos. El contexto hace referencia a la sesión de base de datos, la conexión y cualquier estado o datos asociados a los que el script necesita acceder o manipular.

No puede ejecutar un script de Python directamente en una instancia de base de datos de IA autónoma. En su lugar, aloja el script de forma remota en una imagen de contenedor de Oracle Autonomous AI Database Extproc que se ejecuta en una red virtual en la nube (VCN) de Oracle Cloud Infrastructure. La imagen de contenedor está preconfigurada con el agente EXTPROC e incluye todas las bibliotecas necesarias, como utils, onnx y python-oracledb, para ejecutar el script.

Llamará a scripts de Python desde su base de datos de IA autónoma mediante trabajos de Oracle Scheduler. El trabajo del programador que cree debe ser un trabajo ejecutable y se ejecuta con el atributo WITH_CONTEXT. Los trabajos ejecutables pueden ejecutar scripts de shell u otros ejecutables, y el atributo WITH_CONTEXT de Oracle Scheduler permite que un script herede los privilegios de sesión actuales al llamar a un procedimiento, programa o script externo. El atributo WITH_CONTEXT permite a las rutinas externas acceder a información específica de la sesión, como el esquema, los privilegios y otras variables de contexto.

Los scripts de Python de la base de datos de IA autónoma solo están soportados cuando la base de datos está en un punto final privado. Para ejecutar scripts de Python, debe obtener, instalar y configurar la imagen de contenedor de Oracle Autonomous AI Database EXTPROC con el agente EXTPROC instalado. La imagen de contenedor EXTPROC de la base de datos de IA autónoma permite llamar a procedimientos y scripts externos escritos en BASH, C o Python desde su base de datos de IA autónoma. La instancia del agente EXTPROC se aloja en una subred privada, y la base de datos de IA autónoma accede al agente EXTPROC a través de un punto final de conexión inversa (RCE).

Nota

Esta función solo está soportada para la versión 19c de la base de datos Oracle.

Los scripts de Python se despliegan mediante:

  • Una imagen de contenedor de base de datos de IA autónoma proporcionada por Oracle con el agente EXTPROC instalado. Oracle proporciona la imagen de contenedor en paquetes GitHub.

    Consulte GitHub README para obtener instrucciones para obtener y configurar la imagen de contenedor EXTPROC:

    La instancia del agente EXTPROC se aloja de forma remota en una imagen de contenedor que se ejecuta en una red virtual en la nube (VCN) de Oracle Cloud Infrastructure. La comunicación segura entre la base de datos de IA autónoma y la instancia de agente EXTPROC se protege mediante la definición de reglas del grupo de seguridad de red (NSG) para permitir el tráfico desde la instancia de la base de datos de IA autónoma que se ejecuta en un punto final privado a la instancia de agente EXTPROC. La imagen del agente EXTPROC está preconfigurada para alojar y ejecutar procedimientos externos en el puerto 16000.

  • Procedimientos PL/SQL para registrar entornos de punto final y gestionar privilegios en los puntos finales registrados. Consulte DBMS_CLOUD_FUNCTION_ADMIN Package para obtener más información.

  • Procedimientos PL/SQL para crear y gestionar trabajos y programas del programador para llamar a scripts de Python.

    Consulte DBMS_SCHEDULER para obtener más información.

Siga estos pasos para ejecutar un script de Python con WITH_CONTEXT en una instancia de base de datos de IA autónoma:

Creación de un script de Python

Muestra un ejemplo de creación de un script de Python

  • Ejemplo: script de Python para crear una tabla en la base de datos.

    #!/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()

    En este ejemplo, se crea el script python1.py. El script define una función de Python gsf_main(argc, argv) que acepta argumentos de un trabajo del programador, crea una tabla en la base de datos con los atributos proporcionados y maneja excepciones.

    El controlador oracledb permite que el script se conecte a la base de datos.

    El paquete utils proporciona una función auxiliar getconnection() para obtener una conexión a la base de datos.

Consulte la documentación de Python para obtener más información.

Configurar imagen de contenedor de Oracle Autonomous AI Database EXTPROC

Describe los pasos para obtener y configurar la imagen de contenedor de Oracle Autonomous AI Database EXTPROC.

Una imagen de contenedor de base de datos de IA autónoma proporcionada por Oracle con el agente EXTPROC instalado se aloja en paquetes GitHub. Consulte GitHub README para obtener instrucciones para obtener y configurar la imagen de contenedor EXTPROC.

Carga de Cartera para Crear una Conexión Segura a la Instancia del Agente EXTPROC

Se crea una cartera autofirmada como parte de la creación de la aplicación del agente EXTPROC de la base de datos de IA autónoma. Esta cartera permite acceder a la instancia de agente Extrpoc.

Para ejecutar scripts de Python en la instancia de agente EXTPROC, la base de datos de IA autónoma y el agente EXTPROC se conectan mediante la seguridad de capa de transporte mutuo (mTLS). Al utilizar la seguridad de capa de transporte mutuo (mTLS), los clientes se conectan a través de una conexión del TCPS (TCP seguro) con un certificado TLS 1.2 con una autoridad de certificado (CA) de cliente (CA) de confianza. Consulte Acerca de la conexión a una instancia de base de datos de IA autónoma para obtener más información.
Nota

También puede obtener y utilizar un certificado público emitido por una autoridad de certificación (CA).

Primero debe exportar la cartera a Object Storage desde el directorio /u01/app/oracle/extproc_wallet de la máquina virtual en la que se ejecuta EXTPROC.

Siga estos pasos para cargar la cartera en su base de datos de IA autónoma:

  1. Importe la cartera, cwallet.sso, que contiene los certificados para la instancia de agente EXTPROC en la base de datos de IA autónoma desde Object Storage. Tenga en cuenta lo siguiente para el archivo de cartera:

    • El archivo de cartera, junto con el ID de usuario y la contraseña de la base de datos, proporcionan acceso a la instancia del agente EXTPROC. Almacene los archivos de cartera en una ubicación segura y compártalos solo con usuarios autorizados.

    • No cambie el nombre del archivo de cartera. El archivo de cartera de Object Storage debe tener el nombre cwallet.sso.

  2. Cree credenciales para acceder a Object Storage donde almacene el archivo de cartera cwallet.sso. Consulte el procedimiento CREATE_CREDENTIAL para obtener información sobre los parámetros de nombre de usuario y contraseña para diferentes servicios de almacenamiento de objetos.
    No es necesario crear una credencial para acceder al almacén de objetos de Oracle Cloud Infrastructure si activa las credenciales de entidad de recurso. Consulte Acerca del uso de la entidad de recurso para acceder a recursos de Oracle Cloud Infrastructure para obtener más información.
  3. Cree un directorio en la base de datos de IA autónoma para el archivo de cartera cwallet.sso.
    CREATE DIRECTORY wallet_dir AS 'directory_location';

    Consulte Creación de directorio en base de datos de IA autónoma para obtener más información sobre la creación de directorios.

  4. Utilice DBMS_CLOUD.GET_OBJECT para cargar la cartera. Por ejemplo:
    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;
/

    En este ejemplo, namespace-string es el espacio del nombre de Oracle Cloud Infrastructure Object Storage y bucketname es el nombre del cubo. Consulte Espacios de nombres de Object Storage para más información.

    La cartera se copia en el directorio creado en el paso anterior, WALLET_DIR. La cartera que le permite conectarse a la instancia de agente EXTPROC ahora está disponible en su instancia de base de datos de IA autónoma.

Pasos para llamar a scripts de Python

Muestra los pasos para llamar a scripts de Python en una base de datos de IA autónoma.

Después de configurar la instancia del agente EXTPROC para que ejecute scripts de Python, registre un punto final remoto y cree trabajos del programador para llamar a los scripts.

Los siguientes son requisitos para llamar a scripts de Python en una base de datos de IA autónoma:

  • Los scripts de Python se deben copiar en la instancia del agente EXTPROC.

  • Para crear y gestionar trabajos del programador para llamar a scripts de Python con un usuario que no sea ADMIN, debe tener los siguientes privilegios:

    • MANAGE SCHEDULER

    • CREATE JOB

    • Privilegio en el punto final remoto registrado

Temas

Tema principal: Llamada a scripts de Python con WITH_CONTEXT en una base de datos de IA autónoma

Registrar y gestionar punto final remoto en una base de datos de IA autónoma

Como usuario ADMIN, realice los siguientes pasos para registrar y gestionar puntos finales remotos en su base de datos de IA autónoma.

Registro de un punto final remoto

Utilice DBMS_CLOUD_FUNCTION_ADMIN.REGISTER_REMOTE_EXECUTION_ENV para registrar un punto final remoto.

Ejemplo:

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

En este ejemplo, se crea la biblioteca rem_executable y se registra la instancia del agente EXTPROC especificada en el parámetro remote_endpoint_url de la base de datos de IA autónoma. La instancia del agente EXTPROC está preconfigurada para alojar scripts de Python en el puerto 16000.

Consulte REGISTER_REMOTE_EXECUTION_ENV Procedure para obtener más información.

Gestión de privilegios en un punto final registrado

Este paso es opcional y solo es necesario cuando un usuario que no sea el administrador necesita llamar a scripts de Python desde la base de datos de IA autónoma.

Utilice DBMS_CLOUD_FUNCTION_ADMIN.GRANT_REMOTE_EXECUTION_ENV para otorgar privilegios en el punto final registrado a un usuario que no sea el administrador.

Ejemplo:

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

En este ejemplo, se otorga el privilegio en REM_EXECUTABLE al usuario especificado. Consulte GRANT_REMOTE_EXECUTION_ENV Procedure para obtener más información.

Después de otorgar el privilegio en el punto final registrado, puede utilizar DBMS_CLOUD_FUNCTION_ADMIN.REVOKE_REMOTE_EXECUTION_ENV para revocar el privilegio en el punto final registrado como usuario.

Ejemplo:

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

En este ejemplo, se revoca el privilegio en REM_EXECUTABLE del usuario especificado. Consulte REVOKE_REMOTE_EXECUTION_ENV Procedure para obtener más información.

Puede consultar DBA_CLOUD_FUNCTION_REMOTE_EXECUTION_GRANT para mostrar los permisos otorgados para todos los puntos finales remotos. Consulte DBA_CLOUD_FUNCTION_REMOTE_EXECUTION_GRANT View para obtener más información.

Eliminación de un punto final registrado

Utilice DBMS_CLOUD_FUNCTION_ADMIN.DEREGISTER_REMOTE_EXECUTION_ENV para eliminar un punto final remoto registrado.

Ejemplo:

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

Esto elimina el punto final remoto rem_executable de su base de datos de IA autónoma. Consulte DEREGISTER_REMOTE_EXECUTION_ENV Procedure para obtener más información.

Creación y gestión de trabajos del programador para llamar a scripts de Python

Muestra los pasos para crear y gestionar trabajos del programador para llamar a scripts de Python desde la base de datos de IA autónoma.

Para ejecutar los siguientes pasos como usuario que no sea ADMIN, debe tener los privilegios necesarios. Consulte Pasos para llamar a scripts de Python para obtener más información.
  1. Utilice DBMS_SCHEDULER.CREATE_JOB para crear un trabajo del programador con el tipo de trabajo executable. Por ejemplo:
    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;
/

    En este ejemplo se crea el trabajo del programador rem_exec_job de tipo ejecutable.

    El parámetro job_name especifica el nombre del trabajo.

    El parámetro job_type especifica el tipo de acción de trabajo. Debe especificar job_type como ejecutable para llamar a scripts de Python en la base de datos de IA autónoma.

    El parámetro job_action especifica la acción en línea del trabajo. Esta es la ubicación del script en el punto final remoto que debe llamar. En este ejemplo se llama al script python1.py, creado en un paso anterior.

    El parámetro number_of_arguments especifica el número de argumentos de trabajo.

    El parámetro enabled indica si el trabajo se debe activar inmediatamente después de crearlo. No puede activar un trabajo de Oracle Scheduler que llame a un script de Python al crearlo; utilice DBMS_SCHEDULER.ENABLE para activar el trabajo después de crearlo.

    El parámetro auto_drop indica si el trabajo se debe borrar una vez finalizado.

  2. Utilice DBMS_SCHEDULER.SET_JOB_ARGUMENT_VALUE para definir el valor del argumento de trabajo.

    Ejemplo:

    BEGIN
 DBMS_SCHEDULER.SET_JOB_ARGUMENT_VALUE (
    job_name          => 'rem_exec_job',
    argument_position => 1,
    argument_value    => 'job_param');
 END;
/

    En este ejemplo se define el primer argumento del trabajo rem_exec_job en un valor String job_param. Cuando se ejecuta el trabajo, transfiere job_param como valor para su primer parámetro.

  3. Utilice DBMS_SCHEDULER.SET_ATTRIBUTE para modificar el atributo destination del trabajo rem_exec_job. El atributo destination especifica el destino de punto final remoto.

    Ejemplo:

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

    En este ejemplo, se modifica el atributo destination del trabajo rem_exec_job para especificar la ruta de la biblioteca remota.

    El parámetro job_name especifica el nombre del trabajo.

    El parámetro attribute especifica el atributo que se va a modificar.

    El parámetro value modifica el atributo destination para especificar el destino de punto final remoto.

    El parámetro acepta un valor de cadena en formato REMOTE_EXTPROC:remote_endpoint_name:WITH_CONTEXT, donde remote_endpoint_name es el nombre del punto final remoto registrado. La cláusula WITH_CONTEXT permite a un script heredar los privilegios de sesión actuales al llamar a un procedimiento, programa o script externo.

    Se ha encontrado un error si no tiene privilegios en el punto final especificado.

    Consulte DBMS_SCHEDULER Subprograms para obtener más información.

  4. Ejecute DBMS_SCHEDULER.ENABLE para activar el trabajo del programador.

    Ejemplo:

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

    Este ejemplo activa el trabajo rem_exec_job. Consulte DBMS_SCHEDULER para obtener más información.

    Después de activar el trabajo, el programador comienza a ejecutar el trabajo.

    Consulte la vista USER_CLOUD_FUNCTION_RUN_DETAILS y la vista DBA_CLOUD_FUNCTION_RUN_DETAILS para ver el estado de los trabajos del programador.