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, puoi 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 all'Autonomous AI Database.

Informazioni sulle funzioni cloud e sulle procedure esterne

Le funzioni definite dall'utente consentono di richiamare le funzioni disponibili esternamente dal codice PL/SQL o SQL nel 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 in 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.

Una volta che si utilizzano le funzioni OCI, si utilizzeranno le API PL/SQL DBMS_CLOUD e DBMS_CLOUD_FUNCTION per creare un catalogo di funzioni wrapper SQL nell'Autonomous AI Database che fanno riferimento e chiamano la rispettiva funzione cloud tramite gli endpoint API. Si utilizzerà l'API DBMS_CLOUD_FUNCTION per gestire le funzioni dall'applicazione di database.

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 Procedura CREDENTIAL.

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 Procedura CREATE_CATALOG. È possibile eseguire una query su Vista DBA_CLOUD_FUNCTION_CATALOG e Vista UTENTE_CLOUD_FUNCTION_CATALOG per recuperare la lista di tutti i cataloghi di funzioni cloud nel database.

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

 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.

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. Procedura CREATE_FUNCTION.

SYNC_FUNCTIONS: SYNC_FUNCTIONS sincronizza automaticamente (crea e/o aggiorna) le funzioni wrapper 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 Procedura SYNC_FUNCTIONS.
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, viene preso in considerazione solo l'OCID della funzione OCI fornito come input per il parametro function_id.

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 e USER_CLOUD_FUNCTION per recuperare l'elenco di tutte le funzioni del database.

Per ulteriori informazioni, vedere Procedura CREATE_FUNCTION.

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.

È 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 Procedura DROP_FUNCTION.
È 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 Procedura DROP_CATALOG.

Richiama le funzioni AWS Lambda come funzioni SQL

Mostra i passi per richiamare le funzioni remote AWS come funzioni SQL in 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 nell'Autonomous AI Database 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.

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 Procedura CREDENTIAL.

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 Lambda AWS.
```
 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 Procedura CREATE_CATALOG. È possibile eseguire una query su Vista DBA_CLOUD_FUNCTION_CATALOG e Vista UTENTE_CLOUD_FUNCTION_CATALOG per recuperare l'elenco di tutti i cataloghi del database.

Gli altri 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.

È possibile richiamare e utilizzare procedure esterne in Autonomous AI Database 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 VCN (Virtual Cloud Network) OCI appropriata.

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 da Autonomous AI Database on Dedicated Exadata Infrastructure Database on 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.
Autonomous AI Database, creato come istanza in 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 di Autonomous AI Database 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 di Autonomous AI Database e altre risorse nella subnet privata richiedono l'accesso in uscita a Internet.

Segui questi passaggi minimi di configurazione di OCI Networking quando introduci 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.x. Se l'indirizzo IP della VM EXPROC è 10.x.x.x, non sarà in grado di comunicare con 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. È possibile ottenere questi indirizzi IP del 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 Autonomous AI Database 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 scegli di configurare la VM ExtProc in modo che si trovi in una subnet privata, devi essere in grado di eseguire il login alla VM tramite un server bastion/jump-off e abilitare l'ingresso solo nella VM ExtProc e accedere in modo sicuro alle altre risorse della subnet privata, ad esempio Autonomous AI Database. Per informazioni dettagliate, vedere le guide per la rete OCI.

Implementazione delle funzioni definite dall'utente con le procedure esterne

Provisioning e configurazione della VM EXTPROC da OCI MarketPlace

a. Connettersi a OCI Console all'indirizzo http://cloud.oracle.com. Per ulteriori informazioni, consulta la sezione Accedi alla console di Oracle Cloud Infrastructure.

b. Dal menu di navigazione a sinistra di Oracle Cloud Infrastructure, vai al Marketplace e, in Marketplace, fai clic su Tutte le applicazioni.

c. Immettere "EXTPROC" nella barra di ricerca e fare clic su Cerca. Vedrai due widget: uno etichettato Stack e un altro etichettato Image.

d. Scegliere il widget denominato Stack (importante). Questo ti porterà alla pagina dei dettaglidell'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.

e. 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).
- Accettare termini e condizioni e fare clic su Avvia stack.
Viene visualizzata la pagina successiva, ovvero la procedura guidata Crea stack.

f. 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 Avanti.

g. 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: poiché si è ancora in fase di creazione della VM EXTPROC, prendere nota dei 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.
h. 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, Autonomous AI Database e la VM EXTPROC verranno collocati nella stessa rete VCN, anche se si trovano in subnet diverse (private e pubbliche).
- Per la strategia di rete scegliere "Usa VCN e subnet esistenti". Come indicato in una sezione precedente, in questa fase dello sviluppo di ExtProc, potresti avere l'architettura di sistema in atto con una VCN, AVMC e Autonomous AI Database.
  
  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. Se si sceglie di posizionare la VM EXTPROC in una VCN diversa da quella di Autonomous AI Database, è necessario eseguire il peer delle VCN.
- Saltare la voce successiva per Tipo di accesso agente EXTPROC. Questo campo non è applicabile per Autonomous AI Database su un'infrastruttura Exadata dedicata.
i. 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 di OCI Console per AVMC.
- Per la rete cloud virtuale, fornire il nome della VCN in cui si desidera creare l'agente VM EXTPROC.
- Per la subnet EXTPROC, fornire il nome della subnet in cui si desidera creare l'agente VM EXTPROC.
j. 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.x. Se l'indirizzo IP della VM EXPROC è 10.x.x.x, non sarà in grado di comunicare con Autonomous AI Database.

k. 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 più vecchi 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 Avanti.
l. 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.

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

È necessario fornire le informazioni sul sistema VM EXTPROC come input alle API DBMS_CLOUD_FUNCTION nell'Autonomous AI Database per abilitare il richiamo delle procedure esterne dal database.

a. 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 arriva alla pagina che mostra i dettagli del sistema: IPV4 Public and Private Addresses (IPv4 e IPv6), la subnet e i dettagli dell'immagine.

b. 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 Autonomous AI Database.

c. 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, sono stati raccolti 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'.

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 ExtProc Agent.

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.

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, 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 emesso 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.

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 nell'Autonomous AI Database.

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 Procedura CREDENTIAL.

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

  SET DEFINE OFF

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

 CREATE DIRECTORY extprocwalletdir AS 'extprocwalletdir';

 Directory created.

 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

  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.

 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.

  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.

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

 Function created.

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

  SELECT HELLOCEXTPROC() FROM dual;

 HELLOCEXTPROC()

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

Argomenti correlati

Package DBMS_CLOUD_FUNCTION