Oracle Cloud Infrastructure-Dokumentation

Python-Skripte mit WITH_CONTEXT in autonomer KI-Datenbank aufrufen

Zeigt die Schritte zum Aufrufen von Python-Skripten mit WITH_CONTEXT in der Datenbank an.

Themen

Übergeordnetes Thema: Benutzerdefinierte Funktionen aufrufen

Informationen zum Aufrufen von Python-Skripten mit WITH_CONTEXT in einer autonomen KI-Datenbank

Sie können Python-Skripte auf einer autonomen KI-Datenbankinstanz mit Oracle Scheduler-Jobs mit dem Attribut WITH_CONTEXT ausführen.

Wenn Sie Python-Skripte mit WITH_CONTEXT in der autonomen KI-Datenbank aufrufen, wird ein Kontextzeiger an das Skript übergeben, mit dem das Skript einen Rückruf zur Datenbank ermöglicht. Der Kontext bezieht sich auf die Datenbanksession, die Verbindung und alle zugehörigen Status oder Daten, auf die das Skript zugreifen oder diese bearbeiten muss.

Sie können ein Python-Skript nicht direkt auf einer autonomen AI-Datenbankinstanz ausführen. Stattdessen hosten Sie das Skript remote auf einem Oracle Autonomous AI Database Extproc-Containerimage, das in einem virtuellen Cloud-Netzwerk (VCN) von Oracle Cloud Infrastructure ausgeführt wird. Das Containerimage ist mit dem EXTPROC-Agent vorkonfiguriert und umfasst alle erforderlichen Librarys, wie utils, onnx und python-oracledb, zur Ausführung des Skripts.

Sie rufen Python-Skripte aus Ihrer autonomen KI-Datenbank mit Oracle Scheduler-Jobs auf. Der erstellte Scheduler-Job muss ein ausführbarer Job sein und wird mit dem Attribut WITH_CONTEXT ausgeführt. Die ausführbaren Jobs können Shellskripte oder andere ausführbare Dateien ausführen. Mit dem Oracle Scheduler-Attribut WITH_CONTEXT kann ein Skript beim Aufrufen einer externen Prozedur, eines externen Programms oder Skripts die aktuellen Sessionberechtigungen übernehmen. Mit dem Attribut WITH_CONTEXT können externe Routinen auf sessionspezifische Informationen wie Schema, Berechtigungen und andere Kontextvariablen zugreifen.

Python-Skripte aus Ihrer autonomen KI-Datenbank werden nur unterstützt, wenn sich Ihre Datenbank auf einem privaten Endpunkt befindet. Um Python-Skripte auszuführen, müssen Sie das Oracle Autonomous AI Database EXTPROC-Containerimage abrufen, installieren und konfigurieren, wobei der Agent EXTPROC installiert ist. Mit dem Containerimage der autonomen KI-Datenbank EXTPROC können Sie externe Prozeduren und Skripte aufrufen, die in BASH, C oder Python aus Ihrer autonomen KI-Datenbank geschrieben wurden. Die Agent-Instanz EXTPROC wird in einem privaten Subnetz gehostet, und die autonome AI-Datenbank greift über einen Reverse Connection Endpoint (RCE) auf den Agent EXTPROC zu.

Hinweis

Dieses Feature wird nur für das Oracle-Datenbankrelease 19c unterstützt.

Sie stellen Python-Skripte bereit, indem Sie:

  • Ein Oracle hat das Containerimage der autonomen KI-Datenbank mit dem installierten Agent EXTPROC bereitgestellt. Oracle stellt das Containerimage in GitHub-Packages bereit.

    Anweisungen zum Abrufen und Konfigurieren des EXTPROC-Containerimages finden Sie unter GitHub README:

    Die Agent-Instanz EXTPROC wird remote auf einem Containerimage gehostet, das in einem virtuellen Oracle Cloud Infrastructure-Cloud-Netzwerk (VCN) ausgeführt wird. Die sichere Kommunikation zwischen der autonomen KI-Datenbank und der Agent-Instanz EXTPROC wird gesichert, indem Network Security Group-(NSG-)Regeln festgelegt werden, sodass der Traffic von der Instanz der autonomen KI-Datenbank, die auf einem privaten Endpunkt ausgeführt wird, zur Agent-Instanz EXTPROC zulässig ist. Das EXTPROC-Agent-Image ist für den Host vorkonfiguriert und führt externe Prozeduren auf Port 16000 aus.

  • PL/SQL-Prozeduren zur Registrierung von Endpunktumgebungen und zur Verwaltung von Berechtigungen für die registrierten Endpunkte. Weitere Informationen finden Sie unter DBMS_CLOUD_FUNCTION_ADMIN Package.

  • PL/SQL-Prozeduren zum Erstellen und Verwalten von Scheduler-Jobs und Programmen zum Aufrufen von Python-Skripten.

    Weitere Informationen finden Sie unter DBMS_SCHEDULER.

Führen Sie die folgenden Schritte aus, um ein Python-Skript mit WITH_CONTEXT auf einer autonomen AI-Datenbankinstanz auszuführen:

Python-Skript erstellen

Zeigt ein Beispiel für das Erstellen eines Python-Skripts

  • Beispiel: Python-Skript zum Erstellen einer Tabelle in der Datenbank.

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

    In diesem Beispiel wird das Skript python1.py erstellt. Das Skript definiert eine Python-Funktion gsf_main(argc, argv), die Argumente aus einem Scheduler-Job akzeptiert, eine Tabelle in der Datenbank mit den angegebenen Attributen erstellt und Ausnahmen verarbeitet.

    Mit dem Treiber oracledb kann das Skript eine Verbindung zur Datenbank herstellen.

    Das Package utils stellt eine Helper-Funktion getconnection() zum Abrufen einer Datenbankverbindung bereit.

Weitere Informationen finden Sie in der Python-Dokumentation.

EXTPROC-Containerimage von Oracle Autonomous AI Database konfigurieren

Beschreibt die Schritte zum Abrufen und Konfigurieren des Oracle Autonomous AI Database EXTPROC-Containerimages.

Ein von Oracle bereitgestelltes Autonomous AI Database-Containerimage mit dem installierten EXTPROC-Agent wird in GitHub-Packages gehostet. Anweisungen zum Abrufen und Konfigurieren des Containerimages EXTPROC finden Sie unter GitHub README.

Wallet hochladen, um eine sichere Verbindung zur EXTPROC-Agent-Instanz zu erstellen

Im Rahmen der Erstellung der EXTPROC-Agentanwendung der autonomen KI-Datenbank wird ein selbstsigniertes Wallet erstellt. Mit diesem Wallet können Sie auf die Agent-Instanz Extrpoc zugreifen.

Um Python-Skripte in der Agent-Instanz EXTPROC auszuführen, verbinden sich die autonome AI-Datenbank und der Agent EXTPROC mit Mutual Transport Layer Security (mTLS). Mit Mutual Transport Layer Security (mTLS) stellen Clients Verbindungen über eine TCPS-(Secure TCP-)Datenbankverbindung mit dem Standard TLS 1.2 und einem vertrauenswürdigen Client-Certificate-Authority(CA-)Zertifikat her. Weitere Informationen finden Sie unter Verbindung zu einer autonomen KI-Datenbankinstanz herstellen.
Hinweis

Sie können auch ein öffentliches Zertifikat beziehen und verwenden, das von einer Certificate Authority (CA) ausgestellt wurde.

Sie müssen das Wallet zuerst aus dem Verzeichnis /u01/app/oracle/extproc_wallet auf der VM, auf der EXTPROC ausgeführt wird, in Object Storage exportieren.

Führen Sie die folgenden Schritte aus, um das Wallet in Ihre autonome KI-Datenbank hochzuladen:

  1. Importieren Sie das Wallet cwallet.sso mit den Zertifikaten für die Agent-Instanz EXTPROC aus Object Storage in die autonome KI-Datenbank. Beachten Sie Folgendes für die Wallet-Datei:

    • Die Wallet-Datei sowie die Datenbankbenutzer-ID und das Kennwort ermöglichen den Zugriff auf die Agent-Instanz EXTPROC. Speichern Sie Wallet-Dateien an einem sicheren Ort und teilen Sie sie nur mit autorisierten Benutzern.

    • Benennen Sie die Wallet-Datei nicht um. Die Wallet-Datei in Object Storage muss den Namen cwallet.sso haben.

  2. Erstellen Sie Zugangsdaten für den Zugriff auf Object Storage, in dem Sie die Wallet-Datei cwallet.sso speichern. Informationen zu den Benutzernamen- und Kennwortparametern für verschiedene Objektspeicherservices finden Sie unter Prozedur CREATE_CREDENTIAL.
    Das Erstellen von Zugangsdaten für den Zugriff auf den Oracle Cloud Infrastructure-Objektspeicher ist nicht erforderlich, wenn Sie Resource-Principal-Zugangsdaten aktivieren. Weitere Informationen finden Sie unter Resource Principal für den Zugriff auf Oracle Cloud Infrastructure-Ressourcen nutzen.
  3. Erstellen Sie ein Verzeichnis in der autonomen KI-Datenbank für die Wallet-Datei cwallet.sso.
    CREATE DIRECTORY wallet_dir AS 'directory_location';

    Weitere Informationen zum Erstellen von Verzeichnissen finden Sie unter Verzeichnis in Autonomous AI Database erstellen.

  4. Laden Sie das Wallet mit DBMS_CLOUD.GET_OBJECT hoch. Beispiel:
    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;
/

    In diesem Beispiel ist namespace-string der Oracle Cloud Infrastructure Object Storage-Namespace und bucketname der Bucket-Name. Weitere Informationen finden Sie unter Object Storage-Namespaces.

    Das Wallet wird in das Verzeichnis kopiert, das im vorherigen Schritt WALLET_DIR erstellt wurde. Das Wallet, mit dem Sie eine Verbindung zur Agent-Instanz EXTPROC herstellen können, ist jetzt in der Instanz der autonomen KI-Datenbank verfügbar.

Schritte zum Aufrufen von Python-Skripts

Zeigt die Schritte zum Aufrufen von Python-Skripten in einer autonomen KI-Datenbank an.

Nachdem Sie die Agent-Instanz EXTPROC so konfiguriert haben, dass Python-Skripte ausgeführt werden, registrieren Sie einen Remoteendpunkt und erstellen Scheduler-Jobs, um die Skripte aufzurufen.

Im Folgenden sind die Voraussetzungen zum Aufrufen von Python-Skripten in der autonomen KI-Datenbank aufgeführt:

  • Die Python-Skripte müssen in die EXTPROC-Agentinstanz kopiert werden.

  • Um Scheduler-Jobs zum Aufrufen von Python-Skripten mit einem anderen Benutzer als ADMIN zu erstellen und zu verwalten, benötigen Sie die folgenden Berechtigungen:

    • MANAGE SCHEDULER

    • CREATE JOB

    • Berechtigung für den registrierten Remoteendpunkt

Themen

Übergeordnetes Thema: Python-Skripte mit WITH_CONTEXT in autonomer KI-Datenbank aufrufen

Remoteendpunkt in autonomer KI-Datenbank registrieren und verwalten

Führen Sie als ADMIN-Benutzer die folgenden Schritte aus, um Remoteendpunkte in Ihrer autonomen KI-Datenbank zu registrieren und zu verwalten.

Remoteendpunkt registrieren

Verwenden Sie DBMS_CLOUD_FUNCTION_ADMIN.REGISTER_REMOTE_EXECUTION_ENV, um einen Remoteendpunkt zu registrieren.

Beispiel:

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

In diesem Beispiel wird die rem_executable-Bibliothek erstellt und die EXTPROC-Agentinstanz registriert, die im Parameter remote_endpoint_url in Ihrer autonomen KI-Datenbank angegeben ist. Die Agent-Instanz EXTPROC ist für das Hosten von Python-Skripten auf Port 16000 vorkonfiguriert.

Weitere Informationen finden Sie unter Prozedur REGISTER_REMOTE_EXECUTION_ENV.

Berechtigungen für einen registrierten Endpunkt verwalten

Dieser Schritt ist optional und nur erforderlich, wenn ein anderer Benutzer als ADMIN Python-Skripte aus der autonomen KI-Datenbank aufrufen muss.

Verwenden Sie DBMS_CLOUD_FUNCTION_ADMIN.GRANT_REMOTE_EXECUTION_ENV, um einem anderen Benutzer als ADMIN die Berechtigung für den registrierten Endpunkt zu erteilen.

Beispiel:

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

In diesem Beispiel wird dem angegebenen Benutzer die Berechtigung für REM_EXECUTABLE erteilt. Weitere Informationen finden Sie unter Prozedur GRANT_REMOTE_EXECUTION_ENV.

Nachdem Sie die Berechtigung für den registrierten Endpunkt erteilt haben, können Sie mit DBMS_CLOUD_FUNCTION_ADMIN.REVOKE_REMOTE_EXECUTION_ENV die Berechtigung für den registrierten Endpunkt als Benutzer entziehen.

Beispiel:

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

In diesem Beispiel wird dem angegebenen Benutzer die Berechtigung für REM_EXECUTABLE entzogen. Weitere Informationen finden Sie unter Prozedur REVOKE_REMOTE_EXECUTION_ENV.

Sie können die DBA_CLOUD_FUNCTION_REMOTE_EXECUTION_GRANT abfragen, um die Berechtigungen aufzulisten, die für alle Remoteendpunkte erteilt wurden. Weitere Informationen finden Sie in der Ansicht DBA_CLOUD_FUNCTION_REMOTE_EXECUTION_GRANT.

Registrierten Endpunkt entfernen

Verwenden Sie DBMS_CLOUD_FUNCTION_ADMIN.DEREGISTER_REMOTE_EXECUTION_ENV, um einen registrierten Remoteendpunkt zu entfernen.

Beispiel:

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

Dadurch wird der Remoteendpunkt rem_executable aus der autonomen KI-Datenbank entfernt. Weitere Informationen finden Sie unter Prozedur DEREGISTER_REMOTE_EXECUTION_ENV.

Scheduler-Jobs zum Aufrufen von Python-Skripten erstellen und verwalten

Zeigt die Schritte zum Erstellen und Verwalten von Scheduler-Jobs zum Aufrufen von Python-Skripten aus der autonomen KI-Datenbank an.

Um die folgenden Schritte als anderer Benutzer als ADMIN ausführen zu können, benötigen Sie die erforderlichen Berechtigungen. Weitere Informationen finden Sie unter Schritte zum Aufrufen von Python-Skripten.
  1. Verwenden Sie DBMS_SCHEDULER.CREATE_JOB, um einen Scheduler-Job mit dem Jobtyp executable zu erstellen. Beispiel:
    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;
/

    In diesem Beispiel wird der Scheduler-Job rem_exec_job vom Typ "Executable" erstellt.

    Mit dem Parameter job_name wird der Name des Jobs angegeben.

    Der Parameter job_type gibt den Jobaktionstyp an. Sie müssen job_type als ausführbare Datei angeben, um Python-Skripte in Ihrer autonomen KI-Datenbank aufzurufen.

    Der Parameter job_action gibt die Inlineaktion des Jobs an. Dies ist der Speicherort des Skripts auf dem Remoteendpunkt, den Sie aufrufen müssen. In diesem Beispiel wird das Skript python1.py aufgerufen, das in einem vorherigen Schritt erstellt wurde.

    Der Parameter number_of_arguments gibt die Anzahl der Jobargumente an.

    Der Parameter enabled gibt an, ob der Job unmittelbar nach der Erstellung aktiviert werden soll. Sie können keinen Oracle Scheduler-Job aktivieren, der beim Erstellen ein Python-Skript aufruft. Aktivieren Sie den Job mit DBMS_SCHEDULER.ENABLE, nachdem der Job erstellt wurde.

    Der Parameter auto_drop gibt an, ob der Job nach Abschluss gelöscht werden soll.

  2. Verwenden Sie DBMS_SCHEDULER.SET_JOB_ARGUMENT_VALUE, um den Wert des Jobarguments festzulegen.

    Beispiel:

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

    In diesem Beispiel wird das erste Argument des Jobs rem_exec_job auf den Wert String job_param gesetzt. Wenn der Job ausgeführt wird, übergibt er job_param als Wert für den ersten Parameter.

  3. Verwenden Sie DBMS_SCHEDULER.SET_ATTRIBUTE, um das Attribut destination des Jobs rem_exec_job zu ändern. Das Attribut destination gibt das Remoteendpunktziel an.

    Beispiel:

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

    In diesem Beispiel wird das Attribut destination des Jobs rem_exec_job geändert, um den Remote-Bibliothekspfad anzugeben.

    Mit dem Parameter job_name wird der Name des Jobs angegeben.

    Der Parameter attribute gibt das zu ändernde Attribut an.

    Der Parameter value ändert das Attribut destination, um das Remoteendpunktziel anzugeben.

    Der Parameter akzeptiert einen Zeichenfolgenwert im Format REMOTE_EXTPROC:remote_endpoint_name:WITH_CONTEXT, wobei remote_endpoint_name der Name des registrierten Remoteendpunkts ist. Mit der Klausel WITH_CONTEXT kann ein Skript beim Aufrufen einer externen Prozedur, eines Programms oder eines Skripts die aktuellen Sessionberechtigungen erben.

    Ein Fehler ist aufgetreten, wenn Sie keine Berechtigungen für den angegebenen Endpunkt haben.

    Weitere Informationen finden Sie unter DBMS_SCHEDULER-Unterprogramme.

  4. Führen Sie DBMS_SCHEDULER.ENABLE aus, um den Scheduler-Job zu aktivieren.

    Beispiel:

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

    In diesem Beispiel wird der Job rem_exec_job aktiviert. Weitere Informationen finden Sie unter DBMS_SCHEDULER.

    Nachdem Sie den Job aktiviert haben, beginnt der Scheduler, den Job auszuführen.

    Fragen Sie USER_CLOUD_FUNCTION_RUN_DETAILS View und DBA_CLOUD_FUNCTION_RUN_DETAILS View ab, um den Status Ihrer Scheduler-Jobs anzuzeigen.