Richiama procedure esterne come funzioni SQL

Mostra i passi per richiamare le procedure esterne utilizzando PL/SQL all'interno del database.

Panoramica delle procedure esterne

Le procedure esterne sono funzioni scritte in un linguaggio di terza generazione e richiamabili dall'interno di PL/SQL o SQL come se fossero una routine o una funzione PL/SQL.

Le procedure esterne promuovono la riutilizzabilità, l'efficienza e la modularità. Le librerie di collegamenti dinamici esistenti (DLL) scritte in altre lingue possono essere richiamate dai programmi PL/SQL. Le DLL vengono caricate solo quando necessario e possono essere migliorate senza influire sui programmi di chiamata.

L'utilizzo di procedure esterne migliora anche le prestazioni, poiché i linguaggi di terza generazione eseguono determinati task in modo più efficiente rispetto a PL/SQL, che è più adatto per l'elaborazione delle transazioni SQL.

Le procedure esterne sono utili quando:

  • Risolvere problemi scientifici e ingegneristici

  • Analisi dei dati

  • Controllo di dispositivi e processi in tempo reale

Per ulteriori informazioni, vedere Informazioni su una procedura esterna.

Informazioni sull'uso delle procedure esterne in Autonomous Database

È possibile richiamare e utilizzare procedure esterne in Autonomous Database con funzioni definite dall'utente.

Non si installano procedure esterne su un'istanza di Autonomous Database. Per utilizzare una procedura esterna, la procedura viene gestita in hosting in remoto su una VM in esecuzione in una rete cloud virtuale (VCN) Oracle Cloud Infrastructure.

Le procedure esterne sono supportate solo quando Autonomous Database si trova in un endpoint privato. L'istanza dell'agente EXTPROC viene gestita in hosting in una subnet privata e Autonomous Database accede all'agente EXTPROC tramite un endpoint di connessione inversa (RCE).

Nota

Autonomous Database supporta solo le procedure esterne in linguaggio C.

Le procedure esterne vengono distribuite utilizzando:

  • Un'immagine container fornita da Oracle con l'agente EXTPROC installata e configurata come parte dello stack Oracle Cloud Infrastructure (OCI) Marketplace.

    L'istanza dell'agente EXTPROC viene gestita in hosting in remoto su una VM in esecuzione in una rete cloud virtuale (VCN) Oracle Cloud Infrastructure. La comunicazione sicura tra l'istanza dell'agente Autonomous Database e EXTPROC viene garantita impostando le regole del gruppo di sicurezza di rete (NSG) in modo che il traffico sia consentito dall'istanza di Autonomous 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 creare una libreria e registrare e richiamare funzioni e procedure esterne.

    Per ulteriori informazioni, vedere DBMS_CLOUD_FUNCTION Package.

Attenersi alla procedura riportata di seguito per richiamare una procedura esterna su Autonomous Database.

Definizione della procedura C

Definire la procedura C utilizzando uno di questi prototipi.

  • prototipi in stile Kernighan & Ritchie. Ad esempio:

    void UpdateSalary(x)
     float x;
    ...
    
  • Prototipi ISO/ANSI diversi dai tipi di dati numerici inferiori alla larghezza completa (ad esempio float, short, char). Ad esempio:

    void UpdateSalary(double x)
    ...
    
  • Altri tipi di dati che non modificano la dimensione nelle promozioni argomenti predefinite.

    Questo esempio modifica le dimensioni nelle promozioni argomenti predefinite:

    void UpdateSalary(float x)
    ...

Creazione di un file di libreria condivisa (.so)

Creare una libreria di oggetti condivisi (file .so). La libreria di oggetti condivisi contiene la procedura C (procedura esterna) definita nel passo precedente.

È possibile generare una libreria di oggetti condivisi utilizzando il comando seguente:

gcc -I/u01/app/oracle/extproc_libs/ -shared -fPIC -o extproc.so UpdateSalary.c

In questo modo viene creato l'oggetto condiviso (.so), la libreria extproc.so. La procedura UpdateSalary, definita nel passo precedente, è contenuta nella libreria extproc.so. Le librerie di oggetti condivisi (.so) vengono caricate in modo dinamico in fase di esecuzione.

Scarica l'applicazione stack EXTPROC OCI Marketplace

Mostra i passi per ottenere l'applicazione stack EXTPROC Marketplace OCI.

Effettuare le seguenti operazioni:
  1. Collegarsi a OCI Console all'indirizzo http://cloud.oracle.com. Per ulteriori informazioni, consulta Accedi alla console di Oracle Cloud Infrastructure.
  2. Dal menu di navigazione a sinistra di Oracle Cloud Infrastructure fare clic su Marketplace, quindi in Marketplace fare clic su Tutte le applicazioni. Viene visualizzato il dashboard Tutte le applicazioni del Marketplace.
  3. Immettere EXTPROC nel campo di ricerca e fare clic su ricerca.
  4. Fare clic sul widget EXTPROC di Tipo: stack.
Viene visualizzata la pagina dei dettagli dell'agente EXTPROC di Oracle Autonomous Database.

Avvia applicazione stack EXTPROC

Avviare l'applicazione stack EXTPROC dalla pagina Dettagli applicazione EXTPROC.

  1. Nella pagina Agente EXTPROC di Oracle Autonomous Database, in Stack tipi, eseguire le operazioni riportate di seguito.
    • Dall'elenco a discesa Versione, selezionare la versione del pacchetto dello stack. Per impostazione predefinita, nel menu viene visualizzata la versione più recente.

    • Dall'elenco a discesa Compartimento selezionare il nome del compartimento in cui si desidera avviare l'istanza.

      Nota

      Se non si dispone dell'autorizzazione per avviare l'istanza nel compartimento selezionato, l'istanza viene avviata nel compartimento radice.
    • Selezionare la casella di controllo Ho esaminato e accettato i termini e le limitazioni standard Oracle.

  2. Fare clic su Avvia stack.

Viene visualizzata la pagina Crea stack, che consente di creare lo stack per l'agente EXTPROC.

Crea stack per applicazione agente EXTPROC

Mostra i passi per creare lo stack per l'istanza EXTPROC.

Nella procedura guidata Crea stack, effettuare le operazioni riportate di seguito.
  1. Nella pagina Informazioni sullo stack, rivedere e modificare le informazioni riportate di seguito, se necessario.
    • Informazioni stack

    • Provider personalizzati

    • Nome (facoltativo): è possibile modificare il nome dello stack predefinito. Evitare di fornire informazioni riservate.

    • Descrizione (facoltativa): è possibile modificare la descrizione dello stack predefinita. Evitare di fornire informazioni riservate.

    • Crea nel compartimento

    • Versione di Terraform

    • Tag: fornire quanto segue per assegnare le tag allo stack.

      • Spazio di nomi tag: per aggiungere una tag definita, selezionare uno spazio di nomi esistente. Per aggiungere un tag di origine libera, lasciare vuoto il valore.

      • Chiave tag: per aggiungere una tag definita, selezionare una chiave di tag esistente. Per aggiungere un tag in formato libero, digitare il nome della chiave desiderata.

      • Valore tag: digitare il valore della tag desiderato.

      Aggiungi tag: fare clic per aggiungere un'altra tag.

      Per ulteriori informazioni sull'applicazione di tag, vedere Tag risorsa.

  2. Successivo.
    Viene visualizzata la pagina Configura variabili, che consente di configurare le variabili per le risorse dell'infrastruttura create dallo stack quando si esegue il job di applicazione per questo piano di esecuzione.
  3. Nella pagina Configura variabili immettere le informazioni nelle aree: Configura agente EXTPROC, Configurazione di rete e Configurazione del calcolo.
    1. Fornire le informazioni nell'area Configura agente EXTPROC.
      • Librerie esterne: fornire una lista di librerie, separate da virgole (,), che si desidera consentire di richiamare dall'Autonomous Database. Ad esempio, extproc.so, extproc1.so.

        Dopo aver creato lo stack, è necessario copiare le librerie nella directory /u01/app/oracle/extproc_libs sulla VM dell'agente EXTPROC.

      • Password wallet: fornire la password del wallet.

        Il wallet e un certificato con firma automatica vengono generati per l'autenticazione TLS reciproca tra Autonomous Database e la VM dell'agente EXTPROC. Il wallet viene creato nella directory /u01/app/oracle/extproc_wallet.
        Nota

        Una volta creato il wallet, la password del wallet non può essere modificata.
    2. Fornire informazioni nell'area Configurazione di rete.
      • Compartimento: dall'elenco a discesa, scegliere il compartimento in cui si desidera inserire la configurazione.

      • Strategia di rete: scegliere una delle opzioni dall'elenco a discesa, Crea nuova VCN e subnet o Usa VCN e subnet esistenti.

        • Crea nuova VCN e nuova subnet: scegliere questa opzione se un endpoint privato non è configurato per Autonomous Database. In questo modo, viene creata una nuova VCN con subnet pubblica e privata preconfigurata con regole di sicurezza.

          Se si seleziona questa opzione, nella pagina viene visualizzato anche l'elenco a discesa Strategia di configurazione:

          Scegliere Usa configurazione consigliata dall'elenco a discesa Strategia di configurazione.

        • Usa VCN e subnet esistenti: selezionare questa opzione per creare l'agente EXTPROC utilizzando una VCN esistente. Questa operazione crea l'istanza dell'agente EXTPROC nella subnet fornita.

          Quando si seleziona questa opzione, fornire le informazioni riportate di seguito per la VCN e la subnet esistenti.

          • Nella sezione Rete cloud virtuale:

            Dall'elenco a discesa VCN esistente scegliere una VCN esistente. Se la VCN specificata non esiste, viene creata una nuova VCN.

          • Nella sezione Subnet EXTPROC:

            Dall'elenco a discesa Subnet esistente scegliere una subnet esistente.

            Quando si sceglie di utilizzare una VCN e una subnet esistenti, aggiungere una regola di entrata per la porta 16000 dell'istanza dell'agente EXTPROC. Inoltre, aggiungi una regola di uscita nella subnet pubblica.

            Per ulteriori informazioni, vedere Configurazione dell'accesso di rete con endpoint privati.

      • Tipo di accesso agente EXTPROC: scegliere una delle seguenti opzioni dall'elenco a discesa.

        • Accesso sicuro da database endpoint privati ADB-S specifici nella VCN: scegliere questa opzione per consentire solo agli IP endpoint privati specificati all'interno della rete VCN (Virtual Cloud Network) di connettersi all'agente EXTPROC.

          Quando si sceglie questa opzione, fornire una lista di indirizzi IP di endpoint privati consentiti nel passo successivo.

        • Accesso sicuro da tutti i database degli endpoint privati ADB-S nella VCN: scegliere questa opzione per consentire a qualsiasi endpoint privato all'interno della rete VCN (Virtual Cloud Network) di connettersi all'agente EXTPROC.

      • Indirizzi IP degli endpoint privati

        Fornire una lista di indirizzi IP di endpoint privati separati da virgole (,) per la variabile Indirizzi IP di endpoint privati. ad esempio 10.0.0.0, 10.0.0.1.

        Nota

        Questo campo viene visualizzato solo quando si seleziona Accesso sicuro da database endpoint privati ADB-S specifici nella VCN per il tipo di accesso agente EXTPROC.
    3. Fornire le informazioni sulla configurazione di computazione.
      • Compartimento: selezionare il compartimento in cui si desidera creare lo stack.

      • Forma: selezionare una forma in base ai requisiti del carico di lavoro dell'istanza dell'agente EXTPROC. La forma determina le risorse allocate all'istanza dell'agente EXTPROC.

      • Numero di OCPU: scegliere il numero di OCPU che si desidera allocare per l'istanza dell'agente EXTPROC.

      • Dimensione memoria (GB): scegliere la quantità di memoria in gigabyte (GB) da allocare all'istanza dell'agente EXTPROC.

      • Aggiungi chiavi SSH: caricare una chiave pubblica SSH o incollare la chiave pubblica. Selezionare una delle opzioni seguenti.
        • Scegliere il file di chiavi SSH: caricare la parte della chiave pubblica della coppia di chiavi. Individuare il file di chiavi che si desidera caricare o trascinare il file nella casella.

        • Incolla chiave SSH: incollare la parte della chiave pubblica della coppia di chiavi nella casella.

  4. Successivo.

    Viene quindi visualizzata la pagina Revisione.

  5. Nella pagina Revisione effettuare le operazioni riportate di seguito.
    1. Verificare le variabili di configurazione.
    2. Selezionare la casella di controllo Esegui applicazione nella sezione Esegui applicazione nello stack creato?
    3. Fare clic su Crea.
    Nota

    In quest'area non sono visualizzate le variabili con valori predefiniti o variabili non modificate.

    Resource Manager esegue il job di applicazione per creare di conseguenza le risorse dello stack. Viene visualizzata la pagina Dettagli job e lo stato del job è Accettato. Quando il job di applicazione viene avviato, lo stato viene aggiornato in In corso.

    Nota

    Le informazioni necessarie per connettersi all'istanza creata come parte dello stack sono disponibili nella scheda Informazioni sull'applicazione.

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

Un wallet con firma automatica viene creato nell'ambito della creazione dell'applicazione agente EXTPROC. Questo wallet consente di accedere all'istanza dell'agente Extrpoc.

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

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

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

Attenersi alla procedura riportata di seguito per caricare il wallet in Autonomous Database.

  1. Importare il wallet, cwallet.sso, contenente i certificati per l'istanza dell'agente EXTPROC dallo storage degli oggetti in Autonomous Database. 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. Memorizza i file wallet in una posizione sicura e condividili solo con 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. Vedere CREATE_CREDENTIAL Procedura per informazioni sui parametri del nome utente e della password per diversi servizi di storage degli oggetti.
    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 delle risorse per accedere alle risorse di Oracle Cloud Infrastructure.
  3. Creare una directory in Autonomous 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 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 Database.

Passi per richiamare una procedura esterna come funzione SQL

Mostra i passi per richiamare una procedura esterna come funzione SQL.

Dopo aver avviato l'applicazione dello stack EXTPROC di OCI Marketplace e averla configurata per eseguire procedure esterne, è possibile creare una libreria di funzioni wrapper SQL che fanno riferimento e richiamano le rispettive procedure esterne.

Come prerequisito, le librerie nella lista di inclusione devono essere copiate nella directory /u01/app/oracle/extproc_libs sulla VM EXTPROC.

Attenersi alla procedura riportata di seguito per creare una libreria in Autonomous Database e registrare le routine C come procedura esterna nella libreria.
  1. Creare una libreria.

    Una procedura esterna è una routine di lingua C memorizzata in una libreria. Per richiamare le procedure esterne con Autonomous Database, è necessario creare una libreria.

    Eseguire DBMS_CLOUD_FUNCTION.CREATE_CATALOG per creare una libreria. Ad esempio:

    BEGIN
        DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
            library_name               => 'demolib',
            library_listener_url       => 'remote_extproc_hostname:16000',
            library_wallet_dir_name    => 'wallet_dir',
            library_ssl_server_cert_dn => 'CN=VM Hostname',
            library_remote_path        => '/u01/app/oracle/extproc_libs/library name'
    );
    END;
    /
    

    Questa operazione crea la libreria demolib nell'Autonomous Database e registra la libreria di collegamenti dinamici nel database. L'istanza dell'agente EXTPROC è preconfigurata per ospitare le procedure esterne sulla porta 16000.

    Per ulteriori informazioni, vedere CREATE_CATALOG Procedura.

    Eseguire una query sulle viste DBA_CLOUD_FUNCTION_CATALOG View e USER_CLOUD_FUNCTION_CATALOG View per recuperare la lista di tutti i cataloghi e le librerie nel database.

    Eseguire una query sulla vista USER_CLOUD_FUNCTION_ERRORS View per elencare gli eventuali errori generati durante la convalida della connessione alla posizione della libreria remota.

  2. Creare la funzione.

    Ad esempio:

    CREATE OR REPLACE FUNCTION ftest(
          x VARCHAR2, 
          y VARCHAR2) 
    RETURN VARCHAR2 AS LANGUAGE C
          LIBRARY test
          NAME "demolib"
          PARAMETERS(
              x STRING, 
              y STRING)
          AGENT IN (x);
    /
  3. Per eliminare una libreria esistente è possibile utilizzare la procedura DROP_CATALOG. Ad esempio:
    BEGIN
        DBMS_CLOUD_FUNCTION.DROP_CATALOG (
          LIBRARY_NAME  => 'demolib'
      );
    END;
    /
    

    Viene eliminata la libreria DEMOLIB.

    Per ulteriori informazioni, vedere DROP_CATALOG Procedura.