Documentation Oracle Cloud Infrastructure

Appeler des scripts Python avec WITH_CONTEXT sur une base de données d'IA autonome

Affiche les étapes permettant d'appeler des scripts Python à l'aide de WITH_CONTEXT sur la base de données.

Sujets

Rubrique parent : Appel de fonctions définies par l'utilisateur

A propos de l'appel de scripts Python avec WITH_CONTEXT sur une base de données Autonomous AI

Vous pouvez exécuter des scripts Python sur une instance de base de données Autonomous AI à l'aide de travaux Oracle Scheduler avec l'attribut WITH_CONTEXT.

Lorsque vous appelez des scripts Python avec WITH_CONTEXT sur une base de données Autonomous AI, un pointeur de contexte est transmis au script qui permet au script de rappeler la base de données. Le contexte fait référence à la session de base de données, à la connexion et à tout état ou donnée associé auquel le script doit accéder ou manipuler.

Vous ne pouvez pas exécuter un script Python directement sur une instance de base de données Autonomous AI. A la place, vous hébergez le script à distance sur une image de conteneur Oracle Autonomous AI Database Extproc exécutée dans un réseau cloud virtuel Oracle Cloud Infrastructure (VCN). L'image de conteneur est préconfigurée avec l'agent EXTPROC et inclut toutes les bibliothèques nécessaires, telles que utils, onnx et python-oracledb, pour l'exécution du script.

Vous appelez des scripts Python à partir de votre base de données Autonomous AI à l'aide des travaux Oracle Scheduler. Le travail du planificateur que vous créez doit être un travail exécutable et est exécuté avec l'attribut WITH_CONTEXT. Les travaux exécutables peuvent exécuter des scripts shell ou d'autres exécutables, et l'attribut Oracle Scheduler WITH_CONTEXT permet à un script d'hériter des privilèges de session en cours lors de l'appel d'une procédure, d'un programme ou d'un script externe. L'attribut WITH_CONTEXT permet aux routines externes d'accéder à des informations propres à la session, telles que le schéma, les privilèges et d'autres variables de contexte.

Les scripts Python de votre base de données Autonomous AI ne sont pris en charge que lorsque votre base de données se trouve sur une adresse privée. Pour exécuter des scripts Python, vous devez obtenir, installer et configurer l'image de conteneur Oracle Autonomous AI Database EXTPROC avec l'agent EXTPROC installé. L'image de conteneur EXTPROC de la base de données Autonomous AI permet d'appeler des procédures et des scripts externes écrits en BASH, C ou Python à partir de votre base de données Autonomous AI. L'instance d'agent EXTPROC est hébergée sur un sous-réseau privé et la base de données Autonomous AI accède à l'agent EXTPROC via une adresse de connexion inverse (RCE).

Remarque

Cette fonctionnalité est uniquement prise en charge pour la version 19c de la base de données Oracle.

Vous déployez des scripts Python à l'aide des éléments suivants :

  • Image de conteneur de base de données Autonomous AI fournie par Oracle avec l'agent EXTPROC installé. Oracle fournit l'image de conteneur sur les packages GitHub.

    Reportez-vous au fichier GitHub README pour obtenir des instructions sur l'obtention et la configuration de l'image de conteneur EXTPROC :

    L'instance d'agent EXTPROC est hébergée à distance sur une image de conteneur exécutée dans un réseau cloud virtuel Oracle Cloud Infrastructure (VCN). La communication sécurisée entre votre base de données Autonomous AI et l'instance d'agent EXTPROC est sécurisée en définissant des règles de groupe de sécurité réseau de sorte que le trafic soit autorisé entre l'instance de base de données Autonomous AI exécutée sur une adresse privée et l'instance d'agent EXTPROC. L'image de l'agent EXTPROC est préconfigurée pour héberger et exécuter des procédures externes sur le port 16000.

  • Procédures PL/SQL permettant d'inscrire des environnements d'adresse et de gérer les privilèges sur les adresses inscrites. Pour plus d'informations, reportez-vous à la section DBMS_CLOUD_FUNCTION_ADMIN Package.

  • Procédures PL/SQL permettant de créer et de gérer des travaux et des programmes de planificateur pour appeler des scripts Python.

    Pour plus d'informations, reportez-vous à DBMS_SCHEDULER.

Pour exécuter un script Python avec WITH_CONTEXT sur une instance de base de données Autonomous AI, procédez comme suit :

Créer un script Python

Affiche un exemple de création d'un script Python

  • Exemple : script Python permettant de créer une table dans la base de données.

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

    Cet exemple crée le script python1.py. Le script définit une fonction Python gsf_main(argc, argv) qui accepte les arguments d'un travail du planificateur, crée une table dans la base de données avec les attributs fournis et gère les exceptions.

    Le pilote oracledb permet au script de se connecter à la base de données.

    Le package utils fournit une fonction d'aide getconnection() pour obtenir une connexion de base de données.

Pour plus d'informations, reportez-vous à la documentation Python.

Configuration de l'image de conteneur Oracle Autonomous AI Database EXTPROC

Décrit les étapes à suivre pour obtenir et configurer l'image de conteneur Oracle Autonomous AI Database EXTPROC.

Une image de conteneur de base de données Autonomous AI fournie par Oracle avec l'agent EXTPROC installé est hébergée sur les packages GitHub. Pour obtenir des instructions sur l'obtention et la configuration de l'image de conteneur EXTPROC, reportez-vous à GitHub README.

Télécharger le portefeuille pour créer une connexion sécurisée à l'instance d'agent EXTPROC

Un portefeuille auto-signé est créé dans le cadre de la création de l'application d'agent EXTPROC de la base de données Autonomous AI. Ce portefeuille vous permet d'accéder à l'instance d'agent Extrpoc.

Pour exécuter des scripts Python sur l'instance d'agent EXTPROC, la base de données Autonomous AI et l'agent EXTPROC se connectent à l'aide de l'authentification par couche Transport Layer Security (mTLS). Lorsque le protocole mTLS (Mutual Transport Layer Security) est utilisé, les clients se connectent via une connexion de base de données TCP (Secure TCP) à l'aide du Protocole TLS 1.2 standard avec un certificat d'autorité de certificat client sécurisé. Pour plus d'informations, reportez-vous à A propos de la connexion à une instance de base de données Autonomous AI.
Remarque

Vous pouvez également obtenir et utiliser un certificat public émis par une autorité de certification.

Vous devez d'abord exporter le portefeuille vers Object Storage à partir du répertoire /u01/app/oracle/extproc_wallet sur la machine virtuelle où EXTPROC est exécuté.

Pour télécharger le portefeuille vers votre base de données Autonomous AI, procédez comme suit :

  1. Importez le portefeuille, cwallet.sso, contenant les certificats de l'instance d'agent EXTPROC dans votre base de données Autonomous AI à partir d'Object Storage. Pour le fichier de portefeuille, tenez compte des points suivants :

    • Le fichier de portefeuille, ainsi que l'ID utilisateur et le mot de passe de base de données, permettent d'accéder à l'instance d'agent EXTPROC. Stockez les fichiers de portefeuille dans un emplacement sécurisé et partagez-les uniquement avec les utilisateurs autorisés.

    • Ne renommez pas le fichier de portefeuille. Le fichier de portefeuille dans Object Storage doit être nommé cwallet.sso.

  2. Créez des informations d'identification pour accéder à Object Storage dans lequel stocker le fichier de portefeuille cwallet.sso. Pour plus d'informations sur les paramètres de nom utilisateur et de mot de passe des différents services Object Storage, reportez-vous à Procédure CREATE_CREDENTIAL.
    La création d'informations d'identification pour accéder à la banque d'objets Oracle Cloud Infrastructure n'est pas requise si vous activez les informations d'identification de principal de ressource. Pour plus d'informations, reportez-vous à A propos de l'utilisation du principal de ressource pour accéder à des ressources Oracle Cloud Infrastructure.
  3. Créez un répertoire sur la base de données Autonomous AI pour le fichier de portefeuille cwallet.sso.
    CREATE DIRECTORY wallet_dir AS 'directory_location';

    Pour plus d'informations sur la création de répertoires, reportez-vous à Créer un répertoire dans la base de données Autonomous AI.

  4. Utilisez DBMS_CLOUD.GET_OBJECT pour télécharger vers le serveur le portefeuille. Par exemple :
    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;
/

    Dans cet exemple, namespace-string est l'espace de noms d'objet Oracle Cloud Infrastructure Object Storage et bucketname est le nom du bucket. Pour plus d'informations, reportez-vous à Espaces de nom Object Storage.

    Le portefeuille est copié dans le répertoire créé à l'étape précédente, WALLET_DIR. Le portefeuille qui vous permet de vous connecter à l'instance d'agent EXTPROC est désormais disponible sur votre instance de base de données Autonomous AI.

Etapes d'appel de scripts Python

Affiche les étapes permettant d'appeler des scripts Python sur une base de données Autonomous AI.

Une fois que vous avez configuré l'instance d'agent EXTPROC pour exécuter des scripts Python, vous inscrivez une adresse distante et créez des travaux de planificateur pour appeler les scripts.

Les prérequis suivants permettent d'appeler des scripts Python sur une base de données Autonomous AI :

  • Les scripts Python doivent être copiés dans l'instance d'agent EXTPROC.

  • Pour créer et gérer des travaux du planificateur afin d'appeler des scripts Python avec un utilisateur autre qu'ADMIN, vous devez disposer des privilèges suivants :

    • MANAGE SCHEDULER

    • CREATE JOB

    • Privilège sur l'adresse distante inscrite

Sujets

Rubrique parent : Appel de scripts Python avec WITH_CONTEXT sur une base de données d'IA autonome

Inscription et gestion de l'adresse distante sur la base de données Autonomous AI

En tant qu'utilisateur ADMIN, effectuez les étapes suivantes pour inscrire et gérer les adresses distantes dans votre base de données Autonomous AI.

Inscription d'une adresse distante

Utilisez DBMS_CLOUD_FUNCTION_ADMIN.REGISTER_REMOTE_EXECUTION_ENV pour inscrire une adresse distante.

Exemple :

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

Cet exemple crée la bibliothèque rem_executable et inscrit l'instance d'agent EXTPROC indiquée dans le paramètre remote_endpoint_url dans votre base de données Autonomous AI. L'instance d'agent EXTPROC est préconfigurée pour héberger les scripts Python sur le port 16000.

Pour plus d'informations, reportez-vous à Procédure REGISTER_REMOTE_EXECUTION_ENV.

Gestion des privilèges sur une adresse inscrite

Cette étape est facultative et n'est requise que lorsqu'un utilisateur autre que l'administrateur doit appeler des scripts Python à partir d'une base de données Autonomous AI.

Utilisez DBMS_CLOUD_FUNCTION_ADMIN.GRANT_REMOTE_EXECUTION_ENV pour accorder le privilège sur l'adresse inscrite à un utilisateur autre que l'administrateur.

Exemple :

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

Cet exemple accorde le privilège sur REM_EXECUTABLE à l'utilisateur indiqué. Pour plus d'informations, reportez-vous à Procédure GRANT_REMOTE_EXECUTION_ENV.

Une fois que vous avez accordé le privilège sur l'adresse inscrite, vous pouvez utiliser DBMS_CLOUD_FUNCTION_ADMIN.REVOKE_REMOTE_EXECUTION_ENV pour révoquer le privilège sur l'adresse inscrite en tant qu'utilisateur.

Exemple :

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

Cet exemple révoque le privilège sur REM_EXECUTABLE de l'utilisateur indiqué. Pour plus d'informations, reportez-vous à Procédure REVOKE_REMOTE_EXECUTION_ENV.

Vous pouvez interroger DBA_CLOUD_FUNCTION_REMOTE_EXECUTION_GRANT pour répertorier les droits d'accès accordés à toutes les adresses distantes. Pour plus d'informations, reportez-vous à DBA_CLOUD_FUNCTION_REMOTE_EXECUTION_GRANT View.

Suppression d'une adresse inscrite

Utilisez DBMS_CLOUD_FUNCTION_ADMIN.DEREGISTER_REMOTE_EXECUTION_ENV pour enlever une adresse distante inscrite.

Exemple :

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

Cette opération enlève l'adresse distante rem_executable de votre base de données Autonomous AI. Pour plus d'informations, reportez-vous à Procédure DEREGISTER_REMOTE_EXECUTION_ENV.

Créer et gérer des travaux du planificateur pour appeler des scripts Python

Affiche les étapes permettant de créer et de gérer des travaux de planificateur pour appeler des scripts Python à partir d'une base de données Autonomous AI.

Pour exécuter les étapes suivantes en tant qu'utilisateur autre que l'administrateur, vous devez disposer des privilèges requis. Pour plus d'informations, reportez-vous à Etapes d'appel de scripts Python.
  1. Utilisez DBMS_SCHEDULER.CREATE_JOB pour créer un travail de planificateur avec le type de travail executable. Par exemple :
    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;
/

    Cet exemple crée le travail de planificateur rem_exec_job de type exécutable.

    Le paramètre job_name spécifie le nom du travail.

    Le paramètre job_type indique le type d'action de travail. Vous devez indiquer job_type comme exécutable pour appeler des scripts Python sur votre base de données Autonomous AI.

    Le paramètre job_action indique l'action en ligne du travail. Il s'agit de l'emplacement du script sur l'adresse distante que vous devez appeler. Cet exemple appelle le script python1.py, créé à une étape précédente.

    Le paramètre number_of_arguments indique le nombre d'arguments de travail.

    Le paramètre enabled indique si le travail doit être activé immédiatement après sa création. Vous ne pouvez pas activer un travail Oracle Scheduler qui appelle un script Python lors de sa création. Utilisez DBMS_SCHEDULER.ENABLE pour activer le travail après sa création.

    Le paramètre auto_drop indique si le travail doit être supprimé une fois terminé.

  2. Utilisez DBMS_SCHEDULER.SET_JOB_ARGUMENT_VALUE pour définir la valeur de l'argument de travail.

    Exemple :

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

    Cet exemple définit le premier argument du travail rem_exec_job sur une valeur String job_param. Lorsque le travail est exécuté, il transmet job_param comme valeur de son premier paramètre.

  3. Utilisez DBMS_SCHEDULER.SET_ATTRIBUTE pour modifier l'attribut destination du travail rem_exec_job. L'attribut destination indique la destination de l'adresse distante.

    Exemple :

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

    Cet exemple modifie l'attribut destination du travail rem_exec_job pour spécifier le chemin de bibliothèque distante.

    Le paramètre job_name spécifie le nom du travail.

    Le paramètre attribute indique l'attribut à modifier.

    Le paramètre value modifie l'attribut destination pour indiquer la destination d'adresse distante.

    Le paramètre accepte une valeur de chaîne au format REMOTE_EXTPROC:remote_endpoint_name:WITH_CONTEXT, où remote_endpoint_name est le nom de l'adresse distante enregistrée. La clause WITH_CONTEXT permet à un script d'hériter des privilèges de session en cours lors de l'appel d'une procédure, d'un programme ou d'un script externe.

    Une erreur est détectée si vous ne disposez pas de privilèges sur l'adresse indiquée.

    Pour plus d'informations, reportez-vous à sous-programmes DBMS_SCHEDULER.

  4. Exécutez DBMS_SCHEDULER.ENABLE pour activer le travail de planificateur.

    Exemple :

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

    Cet exemple active le travail rem_exec_job. Pour plus d'informations, reportez-vous à DBMS_SCHEDULER.

    Une fois le travail activé, le planificateur commence à l'exécuter.

    Interrogez les vues USER_CLOUD_FUNCTION_RUN_DETAILS et DBA_CLOUD_FUNCTION_RUN_DETAILS pour visualiser le statut des travaux du planificateur.