Documentazione dell'infrastruttura Oracle Cloud

Richiama gli script Python con WITH_CONTEXT in Autonomous AI Database

Mostra i passi per richiamare gli script Python utilizzando WITH_CONTEXT nel database.

Argomenti

Argomento padre: Richiama funzioni definite dall'utente

Informazioni sul richiamo degli script Python con WITH_CONTEXT in Autonomous AI Database

È possibile eseguire script Python su un'istanza di Autonomous AI Database utilizzando i job di Oracle Scheduler con l'attributo WITH_CONTEXT.

Quando si richiamano script Python con WITH_CONTEXT in Autonomous AI Database, allo script viene passato un puntatore di contesto che consente allo script di richiamare il database. Il contesto fa riferimento alla sessione del database, alla connessione e a qualsiasi stato o dato associato a cui lo script deve accedere o manipolare.

Non è possibile eseguire uno script Python direttamente su un'istanza di Autonomous AI Database. Invece, esegui l'hosting dello script in remoto su un'immagine del container Extproc di Oracle Autonomous AI Database in esecuzione in una rete cloud virtuale (VCN) di Oracle Cloud Infrastructure. L'immagine del contenitore è preconfigurata con l'agente EXTPROC e include tutte le librerie necessarie, ad esempio utils, onnx e python-oracledb, per l'esecuzione dello script.

È possibile richiamare gli script Python da Autonomous AI Database utilizzando i job di Oracle Scheduler. Il job Scheduler creato deve essere un job eseguibile ed essere eseguito con l'attributo WITH_CONTEXT. I processi eseguibili possono eseguire script della shell o altri eseguibili e l'attributo WITH_CONTEXT di Oracle Scheduler consente a uno script di ereditare i privilegi della sessione corrente quando si richiama una procedura, un programma o uno script esterno. L'attributo WITH_CONTEXT consente alle routine esterne di accedere a informazioni specifiche della sessione, ad esempio schemi, privilegi e altre variabili di contesto.

Gli script Python di Autonomous AI Database sono supportati solo quando il database si trova su un endpoint privato. Per eseguire gli script Python, è necessario ottenere, installare e configurare l'immagine del contenitore EXTPROC di Oracle Autonomous AI Database con l'agente EXTPROC installato. L'immagine del contenitore Autonomous AI Database EXTPROC consente di chiamare procedure e script esterni scritti in BASH, C o Python dall'Autonomous AI Database. L'istanza dell'agente EXTPROC è ospitata in una subnet privata e Autonomous AI Database accede all'agente EXTPROC tramite un endpoint di connessione inversa (RCE).

Nota

Questa funzione è supportata solo per la release di database Oracle 19c.

È possibile distribuire script Python utilizzando:

  • Un'immagine contenitore di Autonomous AI Database fornita da Oracle con l'agente EXTPROC installato. Oracle fornisce l'immagine del contenitore nei pacchetti GitHub.

    Per istruzioni su come ottenere e configurare l'immagine del contenitore EXTPROC, vedere GitHub README:

    L'istanza dell'agente EXTPROC è ospitata in remoto su un'immagine contenitore in esecuzione in una rete VCN (Virtual Cloud Network) di Oracle Cloud Infrastructure. La comunicazione sicura tra Autonomous AI Database e l'istanza dell'agente EXTPROC viene protetta impostando regole del gruppo di sicurezza di rete (NSG) in modo che il traffico sia consentito dall'istanza di Autonomous AI Database in esecuzione su un endpoint privato all'istanza dell'agente EXTPROC. L'immagine dell'agente EXTPROC è preconfigurata per ospitare ed eseguire procedure esterne sulla porta 16000.

  • Procedure PL/SQL per registrare gli ambienti endpoint e gestire i privilegi sugli endpoint registrati. Per ulteriori informazioni, vedere DBMS_CLOUD_FUNCTION_ADMIN Package.

  • Procedure PL/SQL per creare e gestire job e programmi scheduler per richiamare script Python.

    Per ulteriori informazioni, vedere DBMS_SCHEDULER.

Per eseguire uno script Python con WITH_CONTEXT in un'istanza di Autonomous AI Database, effettuare le operazioni riportate di seguito.

Creare uno script Python

Mostra un esempio di creazione di uno script Python

  • Esempio: script Python per creare una tabella nel database.

    #!/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 questo esempio viene creato lo script python1.py. Lo script definisce una funzione gsf_main(argc, argv) Python che accetta argomenti da un job Scheduler, crea una tabella nel database con gli attributi forniti e gestisce le eccezioni.

    Il driver oracledb consente allo script di connettersi al database.

    Il pacchetto utils fornisce una funzione di supporto getconnection() per ottenere una connessione al database.

Per ulteriori informazioni, consultare la documentazione di Python.

Configurare l'immagine del contenitore EXTPROC di Oracle Autonomous AI Database

Descrive i passi per ottenere e configurare l'immagine del contenitore EXTPROC di Oracle Autonomous AI Database.

Un'immagine contenitore di Autonomous AI Database fornita da Oracle con l'agente EXTPROC installato è ospitata nei package GitHub. Per istruzioni su come ottenere e configurare l'immagine del contenitore EXTPROC, vedere GitHub README.

Carica wallet per creare una connessione sicura all'istanza dell'agente EXTPROC

Viene creato un wallet con firma automatica nell'ambito della creazione dell'applicazione agente Autonomous AI Database EXTPROC. Questo wallet consente di accedere all'istanza dell'agente Extrpoc.

Per eseguire gli script Python nell'istanza dell'agente EXTPROC, Autonomous AI Database e l'agente EXTPROC si connettono utilizzando Mutual Transport Layer Security (mTLS). Quando si utilizza mTLS (Mutual Transport Layer Security), i client si connettono tramite una connessione al database TCPS (Secure TCP) utilizzando la versione TLS 1.2 standard con un certificato CA (Certificate Authority) client affidabile. Per ulteriori informazioni, vedere Informazioni sulla connessione a un'istanza di Autonomous AI Database.
Nota

È anche possibile ottenere e utilizzare un certificato pubblico emesso da un'autorità di certificazione (CA).

È innanzitutto necessario esportare il wallet nello storage degli oggetti dalla directory /u01/app/oracle/extproc_wallet nella VM in cui viene eseguito EXTPROC.

Per caricare il wallet nell'Autonomous AI Database, effettuare le operazioni riportate di seguito.

  1. Importare il wallet, cwallet.sso, contenente i certificati per l'istanza dell'agente EXTPROC in Autonomous AI Database dallo storage degli oggetti. Tenere presente quanto riportato di seguito per il file wallet.

    • Il file wallet, insieme all'ID utente e alla password del database, fornisce l'accesso all'istanza dell'agente EXTPROC. Memorizzare i file wallet in una posizione sicura e condividerli solo con gli utenti autorizzati.

    • Non rinominare il file wallet. Il file wallet nello storage degli oggetti deve essere denominato cwallet.sso.

  2. Creare le credenziali per accedere allo storage degli oggetti in cui memorizzare il file wallet cwallet.sso. Per informazioni sui parametri di nome utente e password per diversi servizi di storage degli oggetti, vedere CREATE_CREDENTIAL Procedure.
    La creazione di una credenziale per accedere all'area di memorizzazione degli oggetti di Oracle Cloud Infrastructure non è necessaria se si abilitano le credenziali del principal risorsa. Per ulteriori informazioni, vedere Informazioni sull'uso del principal risorsa per accedere alle risorse di Oracle Cloud Infrastructure.
  3. Creare una directory in Autonomous AI Database per il file wallet cwallet.sso.
    CREATE DIRECTORY wallet_dir AS 'directory_location';

    Per ulteriori informazioni sulla creazione di directory, vedere Crea directory in Autonomous AI Database.

  4. Utilizzare DBMS_CLOUD.GET_OBJECT per caricare il wallet. Ad esempio:
    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 questo esempio, namespace-string è lo spazio di nomi di Oracle Cloud Infrastructure Object Storage e bucketname è il nome del bucket. Per ulteriori informazioni, vedere Spazi di nomi dello storage degli oggetti.

    Il wallet viene copiato nella directory creata nel passo precedente, WALLET_DIR. Il wallet che consente di connettersi all'istanza dell'agente EXTPROC è ora disponibile nell'istanza di Autonomous AI Database.

Passi per richiamare gli script Python

Mostra i passi per richiamare gli script Python in un Autonomous AI Database.

Dopo aver configurato l'istanza dell'agente EXTPROC per eseguire gli script Python, è possibile registrare un endpoint remoto e creare processi Scheduler per chiamare gli script.

Di seguito sono riportati i prerequisiti per richiamare gli script Python su Autonomous AI Database.

  • Gli script Python devono essere copiati nell'istanza dell'agente EXTPROC.

  • Per creare e gestire job di Scheduler per richiamare script Python con un utente diverso da ADMIN, è necessario disporre dei seguenti privilegi:

    • MANAGE SCHEDULER

    • CREATE JOB

    • Privilegio sull'endpoint remoto registrato

Argomenti

Argomento padre: richiamare gli script Python con WITH_CONTEXT su Autonomous AI Database

Registra e gestisci endpoint remoti su Autonomous AI Database

Come utente ADMIN, eseguire i passi riportati di seguito per registrare e gestire gli endpoint remoti in Autonomous AI Database.

Registra un endpoint remoto

Utilizzare DBMS_CLOUD_FUNCTION_ADMIN.REGISTER_REMOTE_EXECUTION_ENV per registrare un endpoint remoto.

Esempio:

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 questo esempio viene creata la libreria rem_executable e viene registrata l'istanza dell'agente EXTPROC specificata nel parametro remote_endpoint_url in Autonomous AI Database. L'istanza dell'agente EXTPROC è preconfigurata per ospitare gli script Python sulla porta 16000.

Per ulteriori informazioni, vedere REGISTER_REMOTE_EXECUTION_ENV Procedure.

Gestisci privilegi in un endpoint registrato

Questo passo è facoltativo ed è necessario solo quando un utente diverso da ADMIN deve richiamare gli script Python da Autonomous AI Database.

Utilizzare DBMS_CLOUD_FUNCTION_ADMIN.GRANT_REMOTE_EXECUTION_ENV per concedere il privilegio sull'endpoint registrato a un utente diverso da ADMIN.

Esempio:

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

Questo esempio concede il privilegio su REM_EXECUTABLE all'utente specificato. Per ulteriori informazioni, vedere GRANT_REMOTE_EXECUTION_ENV Procedure.

Dopo aver concesso il privilegio sull'endpoint registrato, è possibile utilizzare DBMS_CLOUD_FUNCTION_ADMIN.REVOKE_REMOTE_EXECUTION_ENV per revocare il privilegio sul form dell'endpoint registrato di un utente.

Esempio:

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

In questo esempio il privilegio su REM_EXECUTABLE viene revocato dall'utente specificato. Per ulteriori informazioni, vedere REVOKE_REMOTE_EXECUTION_ENV Procedure.

È possibile eseguire una query su DBA_CLOUD_FUNCTION_REMOTE_EXECUTION_GRANT per elencare le autorizzazioni concesse per tutti gli endpoint remoti. Per ulteriori informazioni, vedere DBA_CLOUD_FUNCTION_REMOTE_EXECUTION_GRANT View.

Rimuovi un endpoint registrato

Utilizzare DBMS_CLOUD_FUNCTION_ADMIN.DEREGISTER_REMOTE_EXECUTION_ENV per rimuovere un endpoint remoto registrato.

Esempio:

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

In questo modo, l'endpoint remoto rem_executable viene rimosso da Autonomous AI Database. Per ulteriori informazioni, vedere DEREGISTER_REMOTE_EXECUTION_ENV Procedure.

Creare e gestire job scheduler per richiamare gli script Python

Mostra i passi per creare e gestire i job scheduler per richiamare gli script Python da Autonomous AI Database.

Per eseguire i passi riportati di seguito come utente diverso da ADMIN, è necessario disporre dei privilegi necessari. Per ulteriori informazioni, vedere Passi per richiamare gli script Python.
  1. Utilizzare DBMS_SCHEDULER.CREATE_JOB per creare un job scheduler con tipo di job executable. Ad esempio:
    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 questo esempio viene creato il job dello scheduler rem_exec_job di tipo eseguibile.

    Il parametro job_name specifica il nome del job.

    Il parametro job_type specifica il tipo di azione job. È necessario specificare job_type come eseguibile per richiamare gli script Python in Autonomous AI Database.

    Il parametro job_action specifica l'azione in linea del job. Questa è la posizione dello script sull'endpoint remoto che è necessario richiamare. In questo esempio viene richiamato lo script python1.py, creato in un passo precedente.

    Il parametro number_of_arguments specifica il numero di argomenti del job.

    Il parametro enabled indica se il job deve essere abilitato immediatamente dopo la sua creazione. Non è possibile abilitare un job di Oracle Scheduler che richiama uno script Python al momento della creazione. Utilizzare DBMS_SCHEDULER.ENABLE per abilitare il job dopo la creazione del job.

    Il parametro auto_drop indica se il job deve essere eliminato una volta completato.

  2. Usare DBMS_SCHEDULER.SET_JOB_ARGUMENT_VALUE per impostare il valore dell'argomento del job.

    Esempio:

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

    Questo esempio imposta il primo argomento del job rem_exec_job su un valore String job_param. Quando viene eseguito, il job passa job_param come valore per il primo parametro.

  3. Utilizzare DBMS_SCHEDULER.SET_ATTRIBUTE per modificare l'attributo destination del job rem_exec_job. L'attributo destination specifica la destinazione endpoint remoto.

    Esempio:

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

    Questo esempio modifica l'attributo destination del job rem_exec_job per specificare il percorso della libreria remota.

    Il parametro job_name specifica il nome del job.

    Il parametro attribute specifica l'attributo da modificare.

    Il parametro value modifica l'attributo destination per specificare la destinazione dell'endpoint remoto.

    Il parametro accetta un valore String in formato REMOTE_EXTPROC:remote_endpoint_name:WITH_CONTEXT, dove remote_endpoint_name è il nome dell'endpoint remoto registrato. La clausola WITH_CONTEXT consente a uno script di ereditare i privilegi della sessione corrente quando si richiama una procedura, un programma o uno script esterno.

    Si è verificato un errore se non si dispone dei privilegi per l'endpoint specificato.

    Per ulteriori informazioni, vedere DBMS_SCHEDULER Subprogrammi.

  4. Eseguire DBMS_SCHEDULER.ENABLE per abilitare il job dello scheduler.

    Esempio:

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

    Questo esempio abilita il job rem_exec_job. Per ulteriori informazioni, vedere DBMS_SCHEDULER.

    Dopo aver abilitato il job, lo scheduler inizia a eseguire il job.

    Eseguire una query su USER_CLOUD_FUNCTION_RUN_DETAILS View e DBA_CLOUD_FUNCTION_RUN_DETAILS View per visualizzare lo stato dei job dello scheduler.