Richiama funzioni cloud e procedure esterne

In un Oracle Database on-premise (Enterprise, Standard, Express, Personal Editions), puoi scrivere funzioni definite dall'utente in PL/SQL, Java o C per fornire funzionalità non disponibili nelle funzioni integrate SQL o SQL. È possibile richiamare queste funzioni definite dall'utente in un'istruzione SQL ovunque possa verificarsi un'espressione. Vedere Informazioni sulle funzioni definite dall'utente.

Da Oracle Database 19c in poi, è possibile creare, memorizzare ed eseguire script Python utilizzando la funzione di esecuzione Embedded Python in SQL. Vedere Embedded Python Execution using OML4Py.

Oracle Autonomous AI Database on Dedicated Exadata Infrastructure estende la funzionalità delle funzioni definite dall'utente al cloud consentendoti di scrivere funzioni SQL che richiamano servizi di computazione serverless nel cloud, come OCI Functions e AWS Lambda Functions o External Procedures - che includono routine C/C++, script Shell o Python - in esecuzione in una VM di computazione OCI esterna al Autonomous AI Database.

Argomenti correlati

Informazioni sulle funzioni cloud e sulle procedure esterne

Le funzioni definite dall'utente consentono di richiamare funzioni disponibili esternamente dal codice PL/SQL o SQL all'interno del database. È possibile richiamare le seguenti funzioni esterne utilizzando le funzioni definite dall'utente:

  • Oracle Cloud Infrastructure Functions: le Oracle Cloud Infrastructure Functions sono piattaforme completamente gestite, multi-tenant, altamente scalabili, on-demand, Functions-as-a-Service. Le Oracle Cloud Infrastructure Functions sono basate su Oracle Cloud Infrastructure di livello enterprise e basate sul motore open-source di Fn Project. Per ulteriori informazioni, vedere Panoramica delle funzioni OCI.
  • Funzioni Lambda AWS: AWS Lambda è un servizio di computazione serverless basato su eventi che ti consente di eseguire codice praticamente per qualsiasi applicazione o servizio backend senza eseguire il provisioning o la gestione dei server. Per ulteriori informazioni, vedere AWS Lambda.
  • Procedure esterne: le procedure esterne sono funzioni scritte in un linguaggio di terza generazione (ad esempio C), o script shell del sistema operativo o script Python che possono essere richiamati come funzioni SQL o procedure o funzioni PL/SQL. Per ulteriori informazioni, vedere Informazioni sulle procedure esterne.

Richiama le funzioni cloud OCI come funzioni SQL

Mostra i passi per richiamare le funzioni cloud OCI come funzioni SQL nell'Autonomous AI Database on Dedicated Exadata Infrastructure.

Prima di procedere con questi passi, si presuppone che le funzioni OCI siano state create e distribuite in una tenancy e in un compartimento OCI. Per informazioni dettagliate, vedere Funzioni OCI.

Dopo aver utilizzato le funzioni OCI, utilizzerai le API PL/SQL DBMS_CLOUD e DBMS_CLOUD_FUNCTION per creare un catalogo di funzioni wrapper SQL nel database AI autonomo che fanno riferimento e chiamano la rispettiva funzione cloud tramite i loro endpoint API. Si utilizzerà l'API DBMS_CLOUD_FUNCTION per gestire le funzioni dall'applicazione di database.

  1. Creare le credenziali utilizzando la procedura DBMS_CLOUD.CREATE_CREDENTIAL.

    Fornire la chiave privata API dell'utente della tenancy OCI (contenuto del file dot-pem scaricato durante la creazione della chiave API) come oggetto credenziale, impronta digitale della chiave, OCID tenancy e OCID utente. Vedere Chiavi e OCID obbligatori. 

    SET DEFINE OFF
BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL (
       credential_name => 'OCI_CRED', -- provide a string as the name
       user_ocid       => 'user_ocid', -- provide the OCID string for the user, obtained from OCI Console User Profile
       tenancy_ocid    => 'tenancy_ocid', -- provide the OCID string for the tenancy, obtained from OCI Console User Profile
       private_key     => 'private_key', -- provide the content of the dot-pem file that you downloaded when you created the API Key
       fingerprint     => 'fingerprint' -- provide the fingerprint string for the API key
  );
END;
/

    In questo modo viene creato l'oggetto credenziale OCI_CRED.

    Per ulteriori informazioni, vedere CREATE_CREDENTIAL Procedure.

  2. Creare un oggetto catalogo utilizzando la procedura DBMS_CLOUD_FUNCTION.CREATE_CATALOG.

    Un catalogo è una raccolta di funzioni wrapper che fanno riferimento e richiamano le rispettive funzioni cloud tramite gli endpoint API. Fornire l'oggetto credenziale, il nome del provider di servizi cloud, in questo caso OCI, l'ID dell'area OCI (PHX in questo esempio) e l'ID del compartimento OCI in cui si trovano le funzioni OCI.

    BEGIN
DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
    credential_name  => 'OCI_CRED',
    catalog_name     => 'OCI_DEMO_CATALOG',
    service_provider => 'OCI',
    cloud_params     => '{"region_id":"phx", "compartment_id":"compartment_id"}'
);
END;
/

    In questo modo viene creato l'oggetto catalogo OCI_DEMO_CATALOG.

    Per ulteriori informazioni, vedere CREATE_CATALOG Procedure. È possibile eseguire una query su DBA_CLOUD_FUNCTION_CATALOG View e USER_CLOUD_FUNCTION_CATALOG View per recuperare la lista di tutti i cataloghi di funzioni cloud nel database.

  3. È possibile elencare tutte le funzioni cloud nel catalogo utilizzando la procedura DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS.

    SET PAGESIZE 1000

VAR function_list CLOB;

BEGIN
    DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS (
      credential_name  => 'OCI_CRED', 
      catalog_name     => 'OCI_DEMO_CATALOG',
      function_list    => :function_list
 );
END;
/

PL/SQL procedure successfully completed.

SELECT JSON_QUERY (:function_list, '$' RETURNING VARCHAR2(32676) pretty) AS search_results FROM dual;

SEARCH_RESULTS
------------------------------------------------------------------------------------------------
[
  {
    "functionName"   : "create_par",
    "functionId"     : "ocid.funfc.oc1.phx.aaaa_example", 
    "invokeEndpoint" : "https://dw.us.func.oci.oraclecloud_example.com"
  },
  {
    "functionName"   : "fintech",
    "functionId"     : "ocid.funfc.oc1.phx.bbbb_example"
    "invokeEndpoint" : "https://dw.us.func.oci.oraclecloud.com_example"
  },
  {
    "functionName"   : "jwt_codec",
    "functionId"     : "ocid.funfc.oc1.phx.jwt_code_example", 
    "invokeEndpoint" : "https://dw.us.func.oci.oraclecloud_example.com"
  },
  {
    "functionName"   : "oci-objectstorage-create-par-python",
    "functionId"     : "ocid.funfc.oc1.phx.aaaaaaaas_example", 
    "invokeEndpoint" : "https://dw.us.func.oci.oraclecloud_example.com"
  },
  {
    "functionName"   : "run_dbt",
    "functionId"     : "ocid.funfc.oc1.phx.aaaaaaaav_example",
    "invokeEndpoint" : "https://dw.us.func.oci.oraclecloud_example.com"
  }
]

    Per ulteriori informazioni, vedere LIST_FUNCTIONS Procedure.

  4. Creare la funzione wrapper SQL. È possibile utilizzare uno dei due metodi seguenti per creare le funzioni SQL wrapper dal catalogo, che richiamano le rispettive funzioni cloud:

    • È possibile utilizzare DBMS_CLOUD_FUNCTION. SYNC_FUNCTIONS Procedura per generare wrapper SQL dall'oggetto catalogo.
    • È possibile creare manualmente singole funzioni wrapper utilizzando DBMS_CLOUD_FUNCTION. CREATE_FUNCTION Procedura.
    1. SYNC_FUNCTIONS: SYNC_FUNCTIONS sincronizza automaticamente le funzioni wrapper (creazioni e/o aggiornamenti) nel catalogo con la lista completa delle funzioni cloud definite nell'area, nel compartimento e nella tenancy con cui è stato creato il catalogo.
      BEGIN
 DBMS_CLOUD_FUNCTION.SYNC_FUNCTIONS (
        catalog_name => 'OCI_DEMO_CATALOG'
 );
END;
/

      In questo modo viene creato un wrapper PL/SQL per l'aggiunta di nuove funzioni al catalogo e la rimozione di wrapper per le funzioni eliminate dal catalogo.

      È possibile verificare i risultati della sincronizzazione utilizzando la query seguente per un determinato utente corrente.

      SHOW user
TEST_USER

SELECT object_name FROM sys.all_objects WHERE owner='TEST_USER' AND object_type='FUNCTION';

OBJECT_NAME
--------------------------------------------------------------------------------
CREATE_PAR
FINTECH
JWT_CODEC
OCI-OBJECTSTORAGE-CREATE-PAR-PYTHON
RUN_DBT

      Per ulteriori informazioni, vedere SYNC_FUNCTIONS Procedure.

    2. CREATE_FUNCTION: è possibile creare manualmente una funzione SQL nel catalogo che richiama la rispettiva funzione cloud utilizzando DBMS_CLOUD.CREATE_FUNCTION. 

      VAR function_args CLOB;

EXEC :function_args := TO_CLOB('{"command": "VARCHAR2", "value": "VARCHAR2"}');

BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
        credential_name  => 'OCI_CRED',
        catalog_name     => 'OCI_DEMO_CATALOG',
        function_name    => 'FINTECH_FUNCTION',
        function_id      => 'ocid1.fnfunc.oc1.phx.aaabbbcccc_example',
        input_args       => :function_args
 );
END;
/

      In questo modo viene creata la funzione FINTECH_FUN nel catalogo OCI_DEMO_CATALOG, come riferimento alla rispettiva funzione cloud a cui il parametro FUNCTION_ID fa riferimento all'endpoint. Il richiamo della funzione nel catalogo insieme ai relativi argomenti esegue la funzione cloud corrispondente in OCI e fornisce l'output restituito dalla funzione cloud.

      Nota

      Il nome della funzione OCI può essere completamente diverso da FINTECH_FUNCTION. Per creare questo riferimento si tiene conto solo dell'OCID della funzione OCI fornito come input per il parametro function_id.

    3. CREATE_FUNCTION con tipi di restituzione e handler di risposte personalizzati: la creazione manuale delle funzioni consente di creare tipi di restituzione e handler di risposte personalizzati, come mostrato nell'esempio riportato di seguito.

      Creare innanzitutto un tipo restituito e l'handler di risposte della funzione.

      CREATE OR REPLACE TYPE fintech_rt AS OBJECT (
    status VARCHAR2(1000),  
    output CLOB
);
/
Type created.

CREATE OR REPLACE FUNCTION fintech_response_handler(function_response IN CLOB) 
RETURN fintech_rt
IS
      l_comp     fintech_rt;
      l_json_obj JSON_OBJECT_T;
      status     VARCHAR2(1000);
      output     CLOB;
BEGIN
      l_json_obj := JSON_OBJECT_T.parse(function_response); 
      status     := l_json_obj.get('STATUS').to_string;
      output     := l_json_obj.get('RESPONSE_BODY').to_string;
      l_comp     := fintech_rt(status,output);
      RETURN l_comp;
END;
/
Function created.

      Utilizzare quindi questo tipo e l'handler di risposte durante la creazione manuale della funzione wrapper SQL.

      VAR input_param CLOB;
VAR l_return_type VARCHAR2(100);
VAR l_response_handler VARCHAR2(1000);

-- Define function parameters
exec :input_param       := TO_CLOB('{"command": "VARCHAR2", "value": "VARCHAR2"}');

PL/SQL procedure successfully completed.

exec :l_return_type     := 'fintech_rt';

PL/SQL procedure successfully completed.

exec :l_response_handler := 'fintech_response_handler';

PL/SQL procedure successfully completed.

BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
        credential_name  => 'OCI_CRED',
        catalog_name     => 'OCI_DEMO_CATALOG',
        function_name    => 'FINTECH_FUNCTION',
        function_id      => 'ocid1.fnfunc.oc1.phx.aaabbbcccc_example',
        input_args       => :input_param,
        return_type      => :l_return_type,
        response_handler => :l_response_handler
 );
END;
/

      È possibile eseguire una query sulle viste DBA_CLOUD_FUNCTION View e USER_CLOUD_FUNCTION View per recuperare la lista di tutte le funzioni del database.

      Per ulteriori informazioni, vedere CREATE_FUNCTION Procedure.

      Una volta creata la funzione, è possibile DESCRIVERE la funzione per ottenere i dettagli di ritorno.

      DESC fintech_fun
COLUMN STATUS format a30
COLUMN OUTPUT format a30

      È quindi possibile richiamare la funzione fornendo i valori per i parametri di input.

      SET SERVEROUTPUT ON

DECLARE
    l_comp fintech_rt;
BEGIN
    l_comp := fintech_fun(command=>'tokenize',value => 'PHI_INFORMATION');

    DBMS_OUTPUT.put_line ('Status of the function   =  '|| l_comp.status);
    DBMS_OUTPUT.put_line ('Response of the function =  '|| l_comp.output);
END;
/

      Viene richiamata la funzione cloud fintech_fun richiamando il riferimento funzione oocid1.funfn.oci.phx.aaaaaa_example nel catalogo OCI_DEMO_CATALOG.

  5. È possibile eliminare una funzione esistente utilizzando la procedura DROP_FUNCTION.

    BEGIN
    DBMS_CLOUD_FUNCTION.DROP_FUNCTION (
        catalog_name  => 'OCI_DEMO_CATALOG',
        function_name => 'fintech_fun');
END;
/

    Questa operazione elimina la funzione FINTECH_FUN dal catalogo OCI_DEMO_CATALOG.

    Per ulteriori informazioni, vedere DROP_FUNCTION Procedure.

  6. È possibile eliminare un catalogo esistente utilizzando la procedura DROP_CATALOG.

    BEGIN
    DBMS_CLOUD_FUNCTION.DROP_CATALOG (
        catalog_name => 'OCI_DEMO_CATALOG'
  );
END;
/

    In questo modo OCI_DEMO_CATALOG viene eliminato dal database.

    Per ulteriori informazioni, vedere DROP_CATALOG Procedure.

Richiama le funzioni AWS Lambda come funzioni SQL

Mostra i passi per richiamare le funzioni remote AWS come funzioni SQL nell'Autonomous AI Database on Dedicated Exadata Infrastructure.

Prima di procedere con questi passaggi, si presume di aver creato e distribuito AWS Lambda Functions in una tenancy AWS. Per i dettagli, vedere AWS Lambda.

Per accedere alle funzioni AWS lambda, devi configurare i criteri necessari in Oracle Cloud Infrastructure. Per ulteriori informazioni, consulta la sezione relativa alla creazione di un criterio IAM per accedere alle risorse AWS Lambda e all'uso di criteri basati sulle risorse per Lambda.

Dopo aver utilizzato le funzioni AWS Lambda, utilizzerai le API PL/SQL DBMS_CLOUD e DBMS_CLOUD_FUNCTION per creare un catalogo di funzioni SQL wrapper nel database AI autonomo che fanno riferimento e chiamano la rispettiva funzione cloud tramite i loro endpoint API. Si utilizzerà l'API DBMS_CLOUD_FUNCTION per gestire le funzioni dall'applicazione di database.

  1. Creare una credenziale utilizzando la procedura DBMS_CLOUD.CREATE_CREDENTIAL utilizzando la chiave segreta AWS come oggetto credenziale.
    SET DEFINE OFF

BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL (
    credential_name => 'AWS_CRED',
    username        => 'access_key_ID', -- ID of Secret Key
    password        => 'secret_access_key' -- Secret Key password
  );
END;
/

    In questo modo viene creato l'oggetto credenziale AWS_CRED.

    Per ulteriori informazioni, vedere CREATE_CREDENTIAL Procedure.

  2. Creare un oggetto catalogo utilizzando la procedura DBMS_CLOUD_FUNCTION.CREATE_CATALOG.

    Un catalogo è una raccolta di funzioni wrapper che fanno riferimento e richiamano le rispettive funzioni cloud tramite gli endpoint API. Fornire l'oggetto credenziale, il nome del provider di servizi cloud, in questo caso AWS, e l'ID regione AWS (ap-northeast-1 in questo esempio) in cui si trovano le funzioni AWS Lambda. 

    BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
        credential_name  => 'AWS_CRED', 
        catalog_name     => 'AWS_DEMO_CATALOG', 
        service_provider => 'AWS',
        cloud_params     => '{"region_id":"ap-northeast-1"}'
 );
END;
/

    In questo modo viene creato l'oggetto catalogo AWS_DEMO_CATALOG.

    Per ulteriori informazioni, vedere CREATE_CATALOG Procedure. È possibile eseguire una query su DBA_CLOUD_FUNCTION_CATALOG View e USER_CLOUD_FUNCTION_CATALOG View per recuperare la lista di tutti i cataloghi del database.

    Il resto dei passi/operazioni, ovvero la procedura LIST_FUNCTIONS, la procedura SYNC_FUNCTIONS, la procedura CREATE_FUNCTION, la procedura DROP_FUNCTION e la procedura DROP_CATALOG, hanno lo stesso utilizzo descritto per le funzioni cloud OCI. Vedere Richiama le funzioni cloud OCI come funzioni SQL.

Panoramica procedure esterne

Fornisce una panoramica delle procedure esterne e del relativo utilizzo nelle applicazioni Autonomous AI Database on Dedicated Infrastructure.

Le procedure esterne sono funzioni scritte in un linguaggio di terza generazione e richiamate come funzioni SQL o procedure o funzioni PL/SQL. SQL e PL/SQL sono più adatti per l'elaborazione rapida ed efficiente dei dati e delle transazioni nel database. Le procedure esterne possono completare SQL e PL/SQL eseguendo task di computazione e a uso intensivo di memoria in una VM dedicata e esterna e fornendo i risultati al database. Esempi tipici di tali attività sono i problemi scientifici e ingegneristici le cui librerie computazionali esistono nel sistema operativo Linux (e non sono facilmente portabili su una piattaforma di dati), l'analisi dei dati offline, il controllo di dispositivi e processi in tempo reale e così via.

Puoi richiamare e utilizzare procedure esterne nel tuo database AI autonomo con funzioni definite dall'utente. Anziché eseguire queste procedure all'interno del database, posizionerai il codice eseguibile in una VM Linux OCI dedicata e personalizzata di cui è stato eseguito il provisioning con un container e runtime per eseguire programmi C, script Shell e script Python, insieme alle librerie Oracle SQL*Net per abilitare l'esecuzione SQL remota dal database.

Nota

L'host remoto per le procedure esterne deve essere una VM EXTPROC Linux OCI di cui è stato eseguito il provisioning dal Marketplace OCI e configurata in una rete cloud virtuale (VCN) OCI idonea. Per informazioni dettagliate, vedere Configurazione del sistema in OCI per procedure e script esterni.

L'esecuzione remota su OCI Linux EXTPROC VM è supportata solo da Autonomous AI Database on Dedicated Exadata Infrastructure su Oracle Public Cloud a partire dalla versione 19.30 e in Oracle Database 26ai, a partire dalla versione 23.26.1. Questa funzione non è ancora supportata dal database di Autonomous AI Database on Dedicated Exadata Infrastructure su Exadata Cloud@Customer (ExaCC).

Configurazione di sistema per script e procedure esterne

Mostra i passi per eseguire il provisioning della VM EXTPROC e i passi per configurare la rete e la computazione OCI per l'esecuzione di procedure esterne.

L'architettura è costituita in minima parte dalle risorse indicate di seguito.

  • OCI Virtual Cloud Network di cui è stato eseguito il provisioning in un compartimento OCI nella tenancy OCI.
  • Un Autonomous AI Database, creato come istanza in un Autonomous Container Database (ACD), di cui viene eseguito il provisioning da un cluster VM Autonomous Exadata (AVMC), creato sull'infrastruttura Exadata in Oracle Public Cloud.
  • VM EXTPROC di cui è stato eseguito il provisioning come parte di uno stack EXTPROC da OCI Marketplace.

Come procedura ottimale, il cluster AVM verrà posizionato in una subnet privata in una VCN. La tabella di instradamento predefinita e le liste di sicurezza della VCN verranno configurate in base AI requisiti del database AI autonomo nella tenancy OCI. La VCN potrebbe avere una tabella di instradamento predefinita e una lista di sicurezza predefinita, in cui è possibile definire tutte le regole di instradamento e sicurezza. Facoltativamente, la VCN può essere configurata con un gateway NAT se le applicazioni del database AI autonomo e altre risorse nella subnet privata richiedono l'accesso in uscita a Internet.

Seguire questi passi minimi di configurazione di OCI Networking quando si introduce la VM ExtProc in questa topologia.

  • È necessario poter eseguire il login alla VM ExtProc per creare la libreria condivisa (dot-so) con le procedure esterne implementate in C/C++, ispezionare e configurare la VM e il contenitore ed eseguire altre operazioni di questo tipo.
  • La procedura standard consiste nel configurare la VM EXTPROC in modo che si trovi in una subnet pubblica nella VCN. In questo caso, è necessario creare un gateway Internet nella VCN (se non è già configurato dall'amministratore).

    Nota

    La VM EXTPROC NON deve trovarsi in una subnet il cui intervallo CIDR è 10.x.x.x. Se l'indirizzo IP della VM EXPROC è 10.x.x.x, non sarà in grado di comunicare con l'Autonomous AI Database.

  • È necessario definire una regola di entrata nella lista di sicurezza della VCN per consentire l'accesso al login SSH alla VM tramite la porta 22. È inoltre necessario definire una regola di uscita nella lista di sicurezza della VCN per consentire ad ADBD di accedere alla porta di destinazione 16000 in modo che sia specifica o che tutte le porte di destinazione in generale. Vedere OCI Networking Access and Security.
  • Nell'ambito del provisioning dello stack VM EXTPROC, verranno forniti tutti gli indirizzi IP client di AVMC. Si otterranno questi indirizzi IP client IPv4 dal dashboard OCI per il cluster AVM.
  • Successivamente, lo strumento di provisioning creerà automaticamente un gruppo di sicurezza di rete (NSG) denominato nsg_acl. Questo gruppo NSG disporrà di una regola di entrata che consentirà agli indirizzi IP del client dedicato di Autonomous Database di essere le uniche origini che possono accedere alla destinazione Port 16000.

Argomenti avanzati

  • Se le subnet che ospitano la VM ExtProc e il database AI autonomo si trovano nella stessa VCN, non è necessario specificare regole di instradamento speciali nella tabella di instradamento della VCN. Se le subnet che ospitano la VM ExtProc e l'ADBD si trovano in VCN diverse, è necessario implementare il peering VCN. Vedere Peering VCN.
  • Se si sceglie di configurare la VM ExtProc in modo che si trovi in una subnet privata, è necessario essere in grado di eseguire il login alla VM tramite un server bastion/jump-off e abilitare l'ingresso solo nella VM ExtProc e l'accesso sicuro alle altre risorse nella subnet privata, ad esempio l'Autonomous AI Database. Per informazioni dettagliate, vedere le guide per la rete OCI.

Implementazione delle funzioni definite dall'utente con le procedure esterne

  1. Provisioning e configurazione della VM EXTPROC da OCI MarketPlace

    1. Connettersi a OCI Console all'indirizzo http://cloud.oracle.com. Per ulteriori informazioni, consulta la sezione Accedi alla console di Oracle Cloud Infrastructure.
    2. Dal menu di navigazione a sinistra di Oracle Cloud Infrastructure, vai al Marketplace e, in Marketplace, fai clic su Tutte le applicazioni.
    3. Immettere "EXTPROC" nella barra di ricerca e fare clic su Cerca. Vedrai due widget: uno etichettato Stack e un altro etichettato Image.
    4. Scegliere il widget denominato Stack (importante). Questo ti porterà alla pagina dei dettagli dell'agente Oracle Autonomous Database EXTPROC, fornendo la versione dello stack, la data di rilascio e le note di rilascio sullo stack. In questa pagina, fare clic sul pulsante Avvia stack. Viene visualizzata la pagina Avvia stack successiva.

    5. Nella pagina Avvia stack:

      • Dall'elenco a discesa Versione, scegliere la versione del pacchetto dello stack.
      • Dall'elenco a discesa Compartimento selezionare il nome del compartimento in cui si desidera eseguire il provisioning della VM EXTPROC. A meno che non si disponga di motivi specifici, scegliere lo stesso compartimento di quello dell'ADBD (come procedura ottimale, evitare il compartimento radice per qualsiasi risorsa). Esaminare System Configuration for External Procedures and Scripts per effettuare la scelta appropriata per il compartimento.
      • Accettare i termini e condizioni e fare clic su Avvia stack.

      Viene visualizzata la pagina successiva, ovvero la procedura guidata Crea stack.

    6. In questa pagina, fornire un nome, una descrizione, un nomecompartimento, la versione Terraform ed eventuali informazioni sulla tag. Il nome del compartimento è obbligatorio e, più importante, l'input per la procedura guidata in questa pagina. Fare clic su Successivo.
    7. Viene visualizzata la pagina delle variabili di configurazione per la VM EXTPROC (chiamata anche agente EXTPROC). La prima parte di questa pagina raccoglie le informazioni sulle librerie EXTPROC e una password del wallet.
      • Per le Librerie esterne, fornire una lista di librerie, separate da virgole (,), che si desidera consentire di richiamare dall'Autonomous AI Database on Dedicated Infrastructure. Queste librerie condivise conterranno le procedure esterne scritte in C/C++, che sono idealmente compilate e costruite nella VM stessa (per corrispondere all'architettura e all'ambiente).

        Nota

        Dato che si è ancora in procinto di creare la VM EXTPROC, annotare i nomi delle librerie condivise fornite qui. Quando la VM è disponibile e si sviluppano le procedure esterne in C/C++, è necessario ricordarsi di compilare e creare la libreria/librerie con i nomi esatti forniti in precedenza.
      • Per Password wallet, fornire una password per il file wallet che verrà creato nella VM ExtProc. Il wallet e un certificato autofirmato vengono generati per l'autenticazione TLS reciproca tra Autonomous AI Database on Dedicated Infrastructure e EXTPROC Agent VM.
    8. La seconda parte della pagina delle variabili di configurazione prevede la configurazione di rete per la VM EXTPROC.
      • Per il compartimento, scegliere il nome del compartimento per la VCN dal menu a discesa. Nell'esempio precedente, è mostrato come adbd. Idealmente, il database AI autonomo e la VM EXTPROC avranno una stessa struttura logistica nella stessa VCN, anche se si trovano in subnet (private e pubbliche) diverse.
      • Per la strategia di rete scegliere "Usa VCN e subnet esistenti". Come indicato in una sezione precedente, in questa fase del tuo impegno di sviluppo ExtProc, potresti avere l'architettura di sistema in atto con una VCN, AVMC e un database AI autonomo.

        Nota

        L'altra scelta consiste nel creare una nuova VCN e una nuova subnet con la propria strategia di configurazione per l'agente VM EXTPROC. Come indicato nella Configurazione del sistema per procedure e script esterni, se si sceglie di posizionare la VM EXTPROC in una VCN diversa da quella del database AI autonomo, è necessario eseguire il peer delle VCN.
      • Saltare la voce successiva per Tipo di accesso agente EXTPROC. Questo campo non è applicabile per Autonomous AI Database on Dedicated Exadata Infrastructure.
    9. Successivamente, nel campo denominato "Indirizzi IP endpoint privati", immettere TUTTI gli indirizzi IP client dell'AVMC su cui è configurato il database. È possibile ottenere questi indirizzi IP client dal dashboard della console OCI per AVMC.
    10. Successivamente, fornire i dettagli della VCN e della subnet.

      Nota

      La VM EXTPROC NON deve trovarsi in una subnet il cui intervallo CIDR è 10.x.x.x. Se l'indirizzo IP della VM EXPROC è 10.x.x.x, non sarà in grado di comunicare con l'Autonomous AI Database.
    11. La parte finale della pagina di configurazione prevede la configurazione di computazione per l'agente VM EXTPROC.
      • Per il compartimento, scegliere il nome del compartimento dal menu a discesa. Si consiglia di collocare la VM nello stesso compartimento di quella di Autonomous AI Database on Dedicated Infrastructure, della VCN e della subnet per ridurre al minimo la risoluzione dei problemi.
      • Per Forma, Numero di OCPU e Dimensione memoria (GB), immettere i valori in base alle caratteristiche del carico di lavoro delle procedure esterne.
      • Per Aggiungi chiavi SSH, generare i file di chiavi pubbliche e private SSH nel sistema operativo Linux, MacOS o Windows. Aprire una finestra di terminale ed eseguire uno dei seguenti comandi (ED25519 è l'algoritmo moderno e più sicuro; i sistemi meno recenti supportano l'algoritmo di crittografia RSA):
        ssh-keygen -t ed25519 -C "your_email@example.com" (OR)
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

        Verrà generato un file di chiavi private ssh-key-<date-time-id>.key e un file di chiavi pubbliche ssh-key-<date-time-id>.key.pub. Copiare e incollare il contenuto della chiave pubblica SSH nella finestra o trascinare la selezione del file .pub nella finestra.

      • Fare clic su Successivo.

    12. Viene visualizzata la pagina Revisione. Rivedere tutti gli input, quindi selezionare la casella di controllo Esegui applicazione e fare clic su Crea.

      In questo modo verrà avviato OCI Resource Manager per creare lo stack VM EXTPROC. Una volta completato correttamente il job ORM, la VM EXTPROC verrà creata ed eseguita.

  2. Raccogliere informazioni sul sistema VM EXTPROC per l'input API DBMS_CLOUD_FUNCTION

    È necessario fornire informazioni sul sistema VM EXTPROC come input per le API DBMS_CLOUD_FUNCTION nel database AI autonomo per abilitare il richiamo di procedure esterne dal database.

    1. Dal menu di navigazione a sinistra di Oracle Cloud Infrastructure, andare a Compute, scegliere il compartimento specificato per il provisioning della VM EXTPROC ed esaminare il dashboard che elenca tutte le VM nel compartimento. Il job ORM avrà creato la VM EXTPROC con un nome canonico EXTPROC-agent o EXTPROC-agent-<setofnumbers>. Questo sarà il nome host dell'istanza VM EXTPROC. Facendo clic su questa voce si accede alla pagina che mostra i dettagli del sistema: gli indirizzi pubblici e privati IPV4 (IPv4 e IPv6), la subnet e i dettagli dell'immagine.
    2. Eseguire il login alla VM ExtProc utilizzando la chiave SSH fornita durante la creazione dello stack ExtProc e l'indirizzo IP. L'utente predefinito nella VM è opc. sudo per diventare utente oracle.
      ➜  ~ ssh -i ssh-key-<date-time-id>.key opc@<Public-IP-Address>
Wed Nov 19 10:46:25 GMT 2025: EXTPROC Agent intialization completed.

Activate the web console with: systemctl enable --now cockpit.socket

Last login: Thu Nov 20 20:10:54 2025 from <client-IP-address>

[opc@extproc-agent-170798 ~]$ whoami
opc

[opc@extproc-agent-170798 ~]$ sudo su - oracle
Last login: Wed Nov 19 19:07:24 GMT 2025 on pts/0

      La VM EXTPROC avrà un contenitore Podman in esecuzione con un listener Oracle SQL*Net. All'interno del contenitore, sarà disponibile un ambiente client Oracle con i file di configurazione necessari come sqlnet.ora, listener.ora, insieme a un file wallet per una comunicazione sicura con l'Autonomous AI Database.

    3. Raccoglie le informazioni di sistema necessarie per le API PL/SQL a livello di sistema operativo e, successivamente, dal contenitore Podman configurato nella VM. Il contenitore esegue Oracle Listener per ricevere richieste di esecuzione remota dall'applicazione SQL e PL/SQL su Autonomous AI Database ed è il motore di esecuzione runtime per la procedura esterna.
      • Dal sistema operativo Linux, il nome FQDN (nome di dominio completamente qualificato) dell'host VM EXTPROC.
      • Dal contenitore Podman, dallo stato del listener, la porta sulla VM EXTPROC su cui il database si connette alla VM.
      • Dal contenitore Podman, dalla specifica sqlnet.ora, la posizione del file wallet.
      • Da un'ispezione del file wallet utilizzando lo strumento orapki, il valore del parametro Nome distinto (DN) per il certificato wallet.
      [oracle@extproc-agent-170798 ~]$ hostname -f
extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com

[oracle@extproc-agent-170798 ~]$ podman ps
CONTAINER ID  IMAGE                              COMMAND     CREATED       STATUS                 PORTS       NAMES
86d81c4df6ff  ghcr.io/oracle/adb-extproc:latest              23 hours ago  Up 23 hours (healthy)              adb-extproc

[oracle@extproc-agent-170798 ~]$ podman exec -it 86d81c4df6ff bash

(base) [oracle@extproc-agent-170798 admin]$ lsnrctl status

LSNRCTL for Linux: Version 23.26.0.0.0 - for Oracle Cloud and Engineered Systems on 20-NOV-2025 09:25:54

Copyright (c) 1991, 2025, Oracle.  All rights reserved.

Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=IPC)(KEY=EXTPROC1)))
STATUS of the LISTENER
------------------------
Alias                     LISTENER
Version                   TNSLSNR for Linux: Version 23.26.0.0.0 - for Oracle Cloud and Engineered Systems
Start Date                19-NOV-2025 17:19:58
Uptime                    0 days 16 hr. 5 min. 55 sec
Trace Level               off
Security                  ON: Local OS Authentication
SNMP                      OFF
Listener Parameter File   /u01/app/oracle/product/23.0.0.0/client_1/network/admin/listener.ora
Listener Log File         /u01/app/oracle/diag/tnslsnr/extproc-agent-170798/listener/alert/log.xml
Listening Endpoints Summary...
  (DESCRIPTION=(ADDRESS=(PROTOCOL=ipc)(KEY=EXTPROC1)))
  (DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=0.0.0.0)(PORT=16000)))
Services Summary...
Service "extproccontainer.com" has 1 instance(s).
  Instance "extproccontainer", status UNKNOWN, has 1 handler(s) for this service...
The command completed successfully

(base) [oracle@extproc-agent-170798 /]$ cd $ORACLE_HOME/network/admin

(base) [oracle@extproc-agent-170798 admin]$ cat sqlnet.ora

NAMES.DIRECTORY_PATH= (TNSNAMES, EZCONNECT)
WALLET_LOCATION =(SOURCE = (METHOD = FILE)(METHOD_DATA = (DIRECTORY = /u01/app/oracle/wallets/extproc_wallet)))
tcp.invited_nodes=(20.63.19.141,20.63.19.141,20.63.19.143,20.63.19.144)
tcp.validnode_checking=yes

(base) [oracle@extproc-agent-170798 admin]$ orapki wallet display -wallet /u01/app/oracle/wallets/extproc_wallet/cwallet.sso
Oracle PKI Tool Release 23.0.0.0.0 - Production
Version 23.0.0.0.0
Copyright (c) 2004, 2025, Oracle and/or its affiliates. All rights reserved.

Requested Certificates:
User Certificates:
Subject:        CN=extproc-agent-170798
Trusted Certificates:
Subject:        CN=extproc-agent-170798
(base) [oracle@extproc-agent-170798 admin]$ exit
exit
      Nell'esempio precedente, abbiamo raccolto i seguenti input per l'API DBMS_CLOUD_FUNCTION.CREATE_CATALOG.
      • La stringa formata da FQDN + Numero porta sarà l'input per il parametro library_listener_url. In questo esempio, è 'extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com:16000'.
      • sqlnet.ora contiene la posizione del file wallet nella VM: /u01/app/oracle/wallets/extproc_wallet/cwallet.sso. Prendere nota dell'elenco degli indirizzi IP per tcp.invited_nodes. Deve contenere la lista degli indirizzi IP client forniti come input per la configurazione di rete durante la creazione dello stack VM EXTPROC.
      • Il nome distinto del certificato (DN) sarà l'input per il parametro library_ssl_server_cert_dn: 'CN=extproc-agent-170798'.
  3. Creare la libreria C e posizionarla nella posizione specificata nel file system VM EXTPROC

    Definire le funzioni C, crearle e posizionare la libreria nella directory designata nel file system della VM dell'agente ExtProc.

    Il nome della libreria deve corrispondere esattamente al nome o ai nomi forniti durante la creazione dello stack ExtProc. In caso di posizionamento errato, è possibile trovarlo nella voce EXTPROC_DLLS del file initextproccontainer.ora del contenitore ExtProc come mostrato di seguito o nella sezione "Variabili" del job ORM (Oracle Resource Manager) che ha creato lo stack ExtProc. È necessario copiare le librerie nella directory /u01/app/oracle/extproc_libs nella VM dell'agente EXTPROC.
    • Il percorso del file completo (in questo esempio "/u01/app/oracle/extproc_libs/helloCextproc.so") sarà l'input per il parametro library_remote_path di DBMS_CLOUD_FUNCTION.CREATE_CATALOG(). 
    (base) [oracle@extproc-agent-170798 client_1]$ cat $ORACLE_HOME/hs/admin/initextproccontainer.ora
SET TRACE_LEVEL=ON
SET _EXTPROC_REMOTE=TRUE
SET WHOAMI=FROMDOCKER
SET LD_LIBRARY_PATH=/u01/app/oracle/product/23.0.0.0/client_1/lib:/u01/app/oracle/extproc_libs:/opt/conda/lib
SET EXTPROC_DLLS=ONLY:/u01/app/oracle/product/extprocutils.so:/u01/app/oracle/product/23.0.0.0/client_1/lib/libgsfextproc.so:/u01/app/oracle/extproc_libs/helloCextproc.so
SET PYTHONHOME=/opt/conda
SET SCRIPTS_FOLDER_LOC_ENV=/u01/app/oracle/extproc_scripts
SET TRACE_FILE_LOC_ENV=/u01/app/oracle/extproc_logs
SET PYTHONPATH=/tmp:/u01/app/oracle/extproc_scripts
(base) [oracle@extproc-agent-170798 client_1]$ exit

[oracle@extproc-agent-170798 ~]$ cat > helloCextproc.c
#include <stdio.h>
const char* helloCextproc() {
        return ("\nHello C Extproc from FQDN: extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com\n");
}
^D

[oracle@extproc-agent-170798 ~]$ gcc -shared -fPIC -o /u01/app/oracle/extproc_libs/helloCextproc.so helloCextproc.c

[oracle@extproc-agent-170798 ~]$ ls -al /u01/app/oracle/extproc_libs/
total 8
drwxr-xr-x. 2 oracle oinstall   30 Nov 19 11:14 .
drwxr-xr-x. 6 root   root       91 Nov 14 02:19 ..
-rwxr-xr-x. 1 oracle oinstall 8184 Nov 19 11:14 helloCextproc.so
[oracle@extproc-agent-170798 ~]$

    In questo modo verranno completati tutti gli input dei parametri necessari per la creazione dell'oggetto Catalogo/Libreria nell'applicazione di database.

  4. Caricare il file wallet dalla VM ExtProc nello storage degli oggetti OCI

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

    Per eseguire procedure remote nell'istanza dell'agente EXTPROC, l'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.

    Nota

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

    Come prerequisito, è necessario esportare il wallet dalla directory /u01/app/oracle/extproc_wallet nella VM in cui viene eseguito EXTPROC nello storage degli oggetti OCI.

    Nota

    • Proteggere 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.
  5. Creare il catalogo, definire le funzioni SQL e richiamare le procedure esterne come funzioni SQL

    Dai passaggi precedenti, abbiamo tutti gli input di cui abbiamo bisogno per le API DBMS_CLOUD_FUNCTION per eseguire procedure remote da applicazioni di database SQL o PL/SQL.

    Successivamente, importare il wallet, cwallet.sso, contenente i certificati per l'istanza dell'agente EXTPROC dallo storage degli oggetti in una DIRECTORY nel database AI autonomo.

    Creare una credenziale per accedere allo storage degli oggetti in cui è stato memorizzato 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.

    Creare un oggetto DIRECTORY nel database e scaricare il wallet nella DIRECTORY utilizzando l'API DBMS_CLOUD.GET_OBJECT.

    SQL> SET DEFINE OFF

SQL> BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL (
	credential_name => 'OCI_CREDENTIAL',
	user_ocid       => '<oci_user_ocid>',
	tenancy_ocid    => '<oci_tenancy_ocid>',
	private_key     => '<API-key-dot-pem-file-contents>',
	fingerprint     => '<fingerprint-created-with-API-key>');
END;
/

SQL> CREATE DIRECTORY extprocwalletdir AS 'extprocwalletdir';

Directory created.

SQL> SELECT directory_name, directory_path FROM dba_directories WHERE directory_name LIKE '%EXTPROC%';

DIRECTORY_NAME    DIRECTORY_PATH
----------------  -------------------------------------------------------------------------
EXTPROCWALLETDIR  /u02/data/dbfs/<adbd-name>/42E945D608E16DF9E0630301000AF88D/extprocwalletdir

SQL> BEGIN
  DBMS_CLOUD.GET_OBJECT (
  credential_name     => 'OCI_CREDENTIAL',
  object_uri          => 'https://objectstorage.us-ashburn-1.oraclecloud.com/p/aN.../n/zr.../b/bucket-name-20260129/o/cwallet.sso',
  directory_name      => 'EXTPROCWALLETDIR'
  );
END;
/

    Successivamente, creare l'oggetto libreria nel database che rappresenta la libreria C in ExtProc, con i parametri di input raccolti nel passo precedente.

    SQL> BEGIN
  DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
     library_name               => 'EXTPROC_LIBRARY',
     library_listener_url       => 'extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com:16000',
     library_wallet_dir_name    => 'EXTPROCWALLETDIR',
     library_ssl_server_cert_dn => 'CN=extproc-agent-170798',
     library_remote_path        => '/u01/app/oracle/extproc_libs/helloCextproc.so'
  );
END;
/
PL/SQL procedure successfully completed.

SQL> SELECT catalog_name from DBA_CLOUD_FUNCTION_CATALOG WHERE catalog_name LIKE '%EXTPROC%';

CATALOG_NAME
---------------
EXTPROC_LIBRARY

    Creare la funzione SQL mappata alla funzione ExtProc C. Vedere il nome della funzione C dal programma scritto sopra.

    SQL> CREATE OR REPLACE FUNCTION HELLOCEXTPROC RETURN VARCHAR2 AS
    LANGUAGE C
    LIBRARY EXTPROC_LIBRARY
    NAME "helloCextproc";
/

Function created.

SQL>

    Richiama la funzione SQL. Si tratta di una corsa di successo (vedi il corpo della funzione C dalla routine C sopra).

    SQL> SELECT HELLOCEXTPROC() FROM dual;

HELLOCEXTPROC()
----------------------------------------------------------------------------------
Hello C Extproc from FQDN: extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com