Package DBMS_CLOUD_FUNCTION

Il pacchetto DBMS_CLOUD_FUNCTION consente di richiamare le funzioni remote OCI e AWS Lambda nell'Autonomous AI Database come funzioni SQL.

Nota: il supporto per DBMS_CLOUD_FUNCTION è disponibile in Oracle Database 19c a partire dalla versione 19.29 e in Oracle AI Database 26ai a partire dalla versione 23.26.

Riepilogo dei sottoprogrammi DBMS_CLOUD_FUNCTION

La tabella riportata di seguito riassume i sottoprogrammi inclusi nel pacchetto DBMS_CLOUD_FUNCTION.

Tabella - sottoprogrammi DBMS_CLOUD_FUNCTION

Sottoprogramma	Desrizione
Procedura CREATE_CATALOG	Questa procedura crea un catalogo.
Procedura CREATE_FUNCTION	Questa procedura crea funzioni in un catalogo.
Procedura DROP_CATALOG	Questa procedura elimina un catalogo e le funzioni create utilizzando il catalogo.
Procedura DROP_FUNCTION	Questa procedura elimina le funzioni da un catalogo.
Procedura LIST_FUNCTIONS	Questa procedura elenca tutte le funzioni di un catalogo.
Procedura SYNC_FUNCTIONS	Questa procedura consente di aggiungere nuove funzioni al catalogo e di rimuovere le funzioni eliminate dal catalogo.

Procedura CREATE_CATALOG

La procedura DBMS_CLOUD_FUNCTION.CREATE_CATALOG crea un catalogo nel database. Un catalogo è un set di funzioni che crea l'infrastruttura necessaria per eseguire le sottoprogrammi. Questa procedura è sovraccaricata.

Variante sintassi 1

DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
    credential_name             IN VARCHAR2,
    catalog_name                IN VARCHAR2,
    service_provider            IN VARCHAR2,
    cloud_params                IN CLOB
);

Parametri per variante 1

Parametro	Descrizione
`credential_name`	Specifica il nome della credenziale per l'autenticazione. Questo parametro è obbligatorio.
`service_provider`	Specifica il tipo di provider di servizi. Questo parametro può avere `OCI` o `AWS` come valore di parametro. Questo parametro è obbligatorio.
`catalog_name`	Specifica il nome del catalogo. Questo parametro è obbligatorio.
`cloud_params`	Fornisce un parametro alla funzione. Ad esempio, OCID compartimento e aree. Questo parametro è obbligatorio.

Esempi per variante 1

BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
        credential_name  => 'OCI_CREDENTIAL',
        catalog_name     => 'OCI_DEMO_CATALOG',
        service_provider => 'OCI',
        cloud_params     => '{"region_id":"us-phoenix-1", "compartment_id":"compartment_id"}'
 );
END;
/

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

Per creare una libreria con le procedure esterne, è necessario utilizzare la procedura con sovraccarico. Questa procedura non richiede un oggetto credenziale. I parametri richiedono le specifiche della VM EXTPROC e della libreria condivisa che contiene le procedure esterne.

Variante sintassi 2

DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
    library_name                IN VARCHAR2,
    library_listener_url        IN VARCHAR2,
    library_wallet_dir_name     IN VARCHAR2,
    library_ssl_server_cert_dn  IN VARCHAR2,
    library_remote_path         IN VARCHAR2
);

Parametri per variante 2

Parametro	Descrizioni
`library_name`	Specifica il nome fornito al catalogo o alla libreria nel database. Questo parametro è obbligatorio.
`library_listener_url`	Specifica il nome FQDN (nome di dominio completamente qualificato) della VM EXTPROC che ospita la libreria condivisa che contiene le procedure esterne scritte in un linguaggio di terza generazione come C/C++ e il numero di porta in cui il listener SQL*Net in esecuzione nel contenitore VM EXTPROC accetta le richieste di connessione. Il parametro viene specificato come stringa nel formato `host_name:port_number`. Ad esempio: `'extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com:16000'` Questo parametro è obbligatorio.
`library_wallet_dir_name`	Specifica il nome della DIRECTORY nel database in cui è stato importato e memorizzato il wallet con firma automatica.
`library_ssl_server_cert_dn`	Specifica il nome distinto (DN) del certificato server ottenuto dal wallet. Ad esempio: `'CN=extproc-agent-170798'` Questo parametro è obbligatorio.
`library_remote_path`	Specifica il percorso completo della directory nella VM EXTPROC, in cui è memorizzata la libreria contenente le procedure esterne. Ad esempio: `'/u01/app/oracle/extproc_libs/helloCextproc.so'` Questo parametro è obbligatorio.

Esempi per variante 2

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

Errori

Codice errore	Descrizione
`ORA-20000`	Questo errore viene generato nella seguente condizione: - valore `cloud_params` mancante o valori di parametro errati passati.
`ORA-20001`	Questo errore viene generato nella seguente condizione: - La credenziale a cui si fa riferimento nel file `credential_name` non esiste.
`ORA-20002`	Questo errore viene generato nella seguente condizione: - Questo errore viene generato quando il catalogo esiste già.
`ORA-20009`	Questo errore viene generato quando il provider di servizi non esiste.

Nota per l'uso

Per creare un catalogo, è necessario aver eseguito il login come utente ADMIN o disporre dei privilegi seguenti:
- DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE
- DBMS_CLOUD_OCI_FNC_FUNCTIONS_INVOKE_INVOKE_FUNCTION_RESPONSE_T
- DBMS_CLOUD
- Privilegio di lettura su USER_CLOUD_FUNCTION
- Privilegio di lettura su USER_CLOUD_FUNCTION_CATALOG

Procedura CREATE_FUNCTION

È possibile creare manualmente una funzione SQL che richiama la funzione cloud corrispondente nel catalogo. Mentre SYNC_FUNCTIONS recupera e crea automaticamente wrapper per tutte le funzioni cloud in un catalogo, CREATE_FUNCTION consente di creare funzioni con tipi di reso e handler di risposta personalizzati. La procedura CREATE_FUNCTION è applicabile solo per le funzioni cloud.

Sintassi

La procedura DBMS_CLOUD_FUNCTION.CREATE_FUNCTION è supportata solo per le funzioni cloud.

DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
    credential_name   IN VARCHAR2,
    catalog_name      IN VARCHAR2,
    function_name     IN VARCHAR2,
    function_id       IN VARCHAR2,
    input_args        IN CLOB      DEFAULT NULL,
    return_type       IN VARCHAR2  DEFAULT 'CLOB',
    response_handler  IN VARCHAR2  DEFAULT NULL
);

response_handler deve essere definito nel seguente formato:

<USER DEFINED TYPE> response_handler_name(function_response in CLOB)RETURNS CLOB;

Il valore restituito di response_handler è 'Tipo definito dall'utente' e response_json è un documento JSON con due campi, nel formato seguente:

'{
"status":"<response status>",
"response_body":"<response from the function>"
}'

Parametri

Parametro	Descrizione
`credential_name`	Specifica il nome della credenziale per l'autenticazione. Questo parametro è obbligatorio.
`catalog_name`	Specifica il nome del catalogo. Questo parametro è obbligatorio.
`function_name`	Specifica il nome della funzione PL/SQL. Questo parametro è obbligatorio.
`function_id`	Il valore del parametro `function_id` si riferisce alla funzione OCI o AWS Lambda. Questo parametro è obbligatorio.
`input_args`	Specifica la coppia JSON del valore della chiave che accetta gli argomenti di input e i relativi tipi.
`return_type`	Definisce il tipo restituito della funzione. Il tipo restituito è di tipo dati `CLOB`.
`response_handler`	Specifica il callback definito dall'utente per gestire la risposta.

Errori

Codice errore	Descrizione
`ORA-20001`	Questo errore viene generato quando la credenziale a cui si fa riferimento in `credential_name` non esiste.
`ORA-20003`	Questo errore viene generato quando il catalogo specificato non esiste.
`ORA-20004`	Questo errore viene generato quando la funzione specificata esiste già.
`ORA-20005`	Questo errore viene generato quando l'ID funzione o la funzione Amazon Resource Names (ARN) non esiste.
`ORA-20006`	Questo errore viene generato quando gli argomenti di input non sono validi.
`ORA-20007`	Questo errore viene generato quando il tipo restituito è mancante o non valido.
`ORA-20008`	Questo errore viene generato quando l'handler di risposte è mancante o non valido.

Esempio

Il caso semplice con solo parametri di input alla funzione:

VAR function_args CLOB;
EXEC :function_args := TO_CLOB('{"command": "VARCHAR2", "value": "VARCHAR2"}');
BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
	credential_name  => 'DEFAULT_CREDENTIAL',
       catalog_name     => 'OCI_DEMO_CATALOG',
       function_name    => 'demo_function',
       function_id      => 'ocid1.fnfunc.oc1.phx.aaaaaaaazkrbjv6ntowwxlbbp5ct4otsj4o2hdw4ayosyosv4sthmya2lyza',
       input_args       => :function_args);
 );
END;
/

Esempio con il tipo restituito e l'handler di risposte:

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

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

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.

Note sull'uso

Per richiamare le procedure esterne, è possibile utilizzare la stessa sintassi utilizzata per le funzioni definite dall'utente. Ad esempio, se nel database è stata creata una libreria denominata EXTPROC_LIBRARY utilizzando la procedura CREATE_CATALOG per le procedure esterne, è possibile definire una funzione SQL come mostrato in questo esempio e richiamarla da un'istruzione SQL.

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

Function created.

SQL> SELECT HELLOCEXTPROC() FROM dual;

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

Procedura DROP_CATALOG

La procedura DBMS_CLOUD_FUNCTION.DROP_CATALOG elimina il catalogo e le funzioni create utilizzando il catalogo.

Sintassi

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    catalog_name      IN VARCHAR2
 );

Parametri

Parametro Descrizione

Parametro	Descrizione
`catalog_name`	Specifica il nome del catalogo. Questo parametro è obbligatorio.

catalog_name

Specifica il nome del catalogo.

Questo parametro è obbligatorio.

Errori

Codice errore	Descrizione
`ORA-20003`	Questo errore viene generato quando il catalogo specificato non esiste.

Esempio:

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

Procedura DROP_FUNCTION

La procedura DBMS_CLOUD_FUNCTION.DROP_FUNCTION elimina la funzione.

Sintassi

La procedura DBMS_CLOUD_FUNCTION.DROP_FUNCTION è supportata solo per le funzioni cloud.

DBMS_CLOUD_FUNCTION.DROP_FUNCTION (
    catalog_name      IN VARCHAR2,
    function_name     IN VARCHAR2
);

Parametri

Parametro Descrizione

Parametro	Descrizione
`catalog_name`	Specifica il nome del catalogo. Questo parametro è obbligatorio.
`function_name`	Specifica il nome della funzione da eliminare. Questo parametro è obbligatorio.

catalog_name

Specifica il nome del catalogo.

Questo parametro è obbligatorio.

function_name

Specifica il nome della funzione da eliminare.

Questo parametro è obbligatorio.

Errori

Codice errore	Descrizione
`ORA-20003`	Questo errore viene generato quando la funzione specificata non esiste.

Esempi

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

Procedura LIST_FUNCTIONS

Questa procedura elenca tutte le funzioni di un catalogo.

Nota: la procedura LIST_FUNCTIONS è applicabile solo per le funzioni cloud.

Sintassi

DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS (
    credential_name   IN VARCHAR2,
    catalog_name      IN VARCHAR2,
    function_list     OUT VARCHAR2
);

Parametri

Parametro Descrizione

credential_name

Specifica il nome della credenziale per l'autenticazione.

Questo parametro è obbligatorio.

function_list

Restituisce la lista di funzioni in formato JSON.

Questo parametro è obbligatorio.

catalog_name

Specifica il nome del catalogo.

Questo parametro è obbligatorio.

Errori

Codice errore	Descrizione
`ORA-20000`	Questo errore viene generato quando vengono passati valori di parametro errati.
`ORA-20001`	Questo errore viene generato quando la credenziale a cui si fa riferimento in `credential_name` non esiste.
`ORA-20003`	Questo errore viene generato quando il catalogo specificato non esiste.

Esempio:

VAR function_list CLOB;
BEGIN
    DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS (
	credential_name  => 'DEFAULT_CREDENTIAL',
	catalog_name     => 'OCI_DEMO_CATALOG',
	function_list    => :function_list);
 );
END;
/
SELECT JSON_QUERY(:function_list, '$' RETURNING VARCHAR2(32676) pretty) AS search_results FROM dual;

Procedura SYNC_FUNCTIONS

Questa procedura consente di aggiungere nuove funzioni al catalogo e di rimuovere le funzioni eliminate dal catalogo.

Nota: la procedura SYNC_FUNCTIONS è applicabile solo alle funzioni cloud.

Sintassi

DBMS_CLOUD_FUNCTION.SYNC_FUNCTIONS (
    catalog_name      IN VARCHAR2,
    refresh_rate     IN VARCHAR2 DEFAULT 'DAILY'
);

Parametri

Parametro Descrizione

Parametro	Descrizione
`catalog_name`	Specifica il nome del catalogo. Questo parametro è obbligatorio.
`refresh_rate`	Specifica la frequenza di aggiornamento della funzione. `refresh_rate` può accettare i seguenti valori: `HOURLY` `DAILY` `WEEKLY` `MONTHLY` Il valore predefinito per questo parametro è `DAILY`.

catalog_name

Specifica il nome del catalogo.

Questo parametro è obbligatorio.

refresh_rate

Specifica la frequenza di aggiornamento della funzione.

refresh_rate può accettare i seguenti valori:

HOURLY
DAILY
WEEKLY
MONTHLY

Il valore predefinito per questo parametro è DAILY.

Errori

Codice errore	Descrizione
`ORA-20003`	Questo errore viene generato quando il catalogo specificato non esiste.
`ORA-20004`	Questo errore viene generato quando viene passato un valore non valido per il parametro `refresh_rate`.

Esempio:

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