Pacchetto DBMS_CLOUD

Pacchetto DBMS_CLOUD_FUNCTION

Il pacchetto DBMS_CLOUD_FUNCTION ti consente di richiamare le funzioni remote OCI e AWS Lambda nel tuo database AI autonomo 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.

Sintassi

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

Parametri

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.

Errori

Codice errore	Descrizione
`ORA-20000`	Questo errore viene generato nella seguente condizione: Valore `cloud_params` mancante o valori di parametro non corretti passati.
`ORA-20001`	Questo errore viene generato nella seguente condizione: La credenziale a cui viene fatto riferimento in `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.

Esempi

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

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

Questa procedura crea funzioni in un catalogo.

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

Firma gestore risposte

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

Il tipo restituito è definito dall'utente o PL/SQL. function_response è di tipo JSON con campi.

'{  
"STATUS":"<RESPONCE STATUS>",  
"RESPONSE_BODY":"<FUNCTION RESPONSE>"
}'

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 di restituzione 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

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

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.

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.

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

Titolo e informazioni sul copyright

Oracle e/o relative consociate.