Documentazione di Oracle Cloud Infrastructure

Pacchetto DBMS_CLOUD_FUNCTION

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

Argomento padre: riferimento al package fornito da Autonomous Database

Riepilogo dei sottoprogrammi DBMS_CLOUD_FUNCTION

La tabella seguente contiene un riepilogo dei sottoprogrammi inclusi nel pacchetto DBMS_CLOUD_FUNCTION.

Programma secondario descrizione;

CREATE_CATALOG Procedura

Questa procedura crea un catalogo.

CREATE_FUNCTION Procedura

Questa procedura consente di creare funzioni in un catalogo.

DROP_CATALOG Procedura

Questa procedura elimina un catalogo e le funzioni create utilizzando il catalogo

DROP_FUNCTION Procedura

Questa procedura elimina le funzioni da un catalogo.

LIST_FUNCTIONS Procedura

Questa procedura elenca tutte le funzioni di un catalogo.

SYNC_FUNCTIONS Procedura

Questa procedura crea un wrapper PL/SQL per aggiungere nuove funzioni al catalogo e rimuovere i wrapper per le funzioni eliminate dal catalogo.
  • CREATE_CATALOG Procedura
    Questa procedura crea un catalogo nel database. La procedura DBMS_CLOUD_FUNCTION.CREATE_CATALOG crea un catalogo. Un catalogo è un set di funzioni che crea l'infrastruttura necessaria per eseguire le routine secondarie. Questa procedura è sovraccaricata.
  • CREATE_FUNCTION Procedura
    Questa procedura crea funzioni in un catalogo. Esistono due procedure DBMS_CLOUD_FUNCTION.CREATE_FUNCTION sovraccaricate.
  • DROP_CATALOG Procedura
    La procedura DBMS_CLOUD_FUNCTION.DROP_CATALOG elimina il catalogo e le funzioni create utilizzando il catalogo. Questa procedura è sovraccaricata.
  • DROP_FUNCTION Procedura
    La procedura DBMS_CLOUD_FUNCTION.DROP_FUNCTION elimina la funzione. Questa procedura è sovraccaricata.
  • LIST_FUNCTIONS Procedura
    Questa procedura elenca tutte le funzioni di un catalogo.
  • SYNC_FUNCTIONS Procedura
    Questa procedura crea un wrapper PL/SQL per l'aggiunta di nuove funzioni al catalogo e la rimozione dei wrapper per le funzioni eliminate dal catalogo.

Argomento padre: DBMS_CLOUD_FUNCTION Package

CREATE_CATALOG Procedura

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

Sintassi

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

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

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 il valore OCI, AWS, AZURE o GCP come 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, Aree e Azure subscription_id.

Questo parametro è obbligatorio.

library_name

Specifica il nome della libreria quando si crea una libreria remota.

Questo parametro è obbligatorio.

library_listener_url

Specifica la posizione remota della libreria.

Il parametro accetta un valore stringa in formato host_name:port_number.

Ad esempio: EHRPMZ_DBDOMAIN.adb-us-phoenix1.com:16000

Questo parametro è obbligatorio.

library_remote_path

Specifica il percorso remoto della libreria.

È necessario fornire il percorso assoluto completo della libreria remota.

Ad esempio:/u01/app/oracle/product/21.0.0.0/client_1/lib/libst_shape.so

Questo parametro è obbligatorio.

library_wallet_dir_name

Specifica la directory in cui è memorizzato il wallet con firma automatica.

Questo parametro è obbligatorio.

library_ssl_server_cert_dn

Specifica il nome distinto (DN) del certificato del server.

Questo parametro è obbligatorio.

Errori

Codice di errore descrizione;

ORA-20000

Questo errore viene generato in una delle seguenti condizioni:

  • Valore cloud_params mancante o valori di parametro errati passati.

  • Il valore library_name non è univoco quando si crea una libreria.

ORA-20001

Questo errore viene generato in una delle seguenti condizioni:

  • La credenziale a cui viene fatto riferimento nel file credential_name non esiste.

  • Il listener specificato in library_listener_url non è raggiungibile durante la creazione di una libreria.

ORA-20002

Questo errore viene generato in una delle seguenti condizioni:

  • Questo errore viene generato quando il catalogo esiste già.

  • La directory del certificato server specificata è vuota durante la creazione di una libreria.

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;
/
BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
        credential_name  => 'AZURE$PA', 
        catalog_name     => 'AZURE_DEMO_CATALOG', 
        service_provider => 'AZURE',
        cloud_params     => '{"subscription_id":"44495e6a-8ff1-4161-b387-0e14e675b878"}'
 );
END;
/

BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (   
    library_name               => 'EXT_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;
/

BEGIN
    DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
        credential_name  => 'GCP$PA', 
        catalog_name     => 'GCP_DEMO_CATALOG', 
        service_provider => 'GCP',
        cloud_params     => '{"project_id":"example_XXXXXX"}'
 );
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

CREATE_FUNCTION Procedura

Questa procedura consente di creare funzioni in un catalogo. Esistono due procedure DBMS_CLOUD_FUNCTION.CREATE_FUNCTION sovraccaricate.

Sintassi CREATE_FUNCTION

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 dell'handler risposte

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

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

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

Parametri CREATE_FUNCTION

CREATE_FUNCTION Eccezioni

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, alla funzione AWS Lambda o Azure.

Questo parametro è obbligatorio.

input_args

Specifica la coppia di valori chiave JSON che accetta gli argomenti di input e i relativi tipi.

return_type

Definisce il tipo restituito della funzione.

Il tipo restituito è CLOB data type.

response_handler

Specifica il callback definito dall'utente per gestire la risposta.
Codice di errore descrizione;

ORA-20001

Questo errore viene generato quando la credenziale a cui viene fatto riferimento nel file 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.

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

Sintassi CREATE_FUNCTION 

DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
  library_name         IN VARCHAR2,
  function_name        IN VARCHAR2,
  function_id          IN VARCHAR2 DEFAULT NULL,
  plsql_params         IN CLOB DEFAULT NULL,
  external_params      IN CLOB DEFAULT NULL,
  api_type             IN VARCHAR2 DEFAULT 'FUNCTION',
  with_context         IN BOOLEAN DEFAULT FALSE,
  return_type          IN VARCHAR2 DEFAULT NULL
);

Parametri CREATE_FUNCTION

Parametro descrizione;

library_name

Specifica il nome della libreria remota.

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 alle procedure esterne (extproc).

Se non viene fornito il valore per function_id, viene utilizzato il valore nel valore function_name.

plsql_params

Specifica la coppia di valori chiave JSON che accetta i parametri per il wrapper PL/SQL.

I valori devono essere forniti nel formato "var_name":"modetype, datatype".

  • var_name : è il nome della variabile. Questo parametro è obbligatorio.

  • modetype: specifica la modalità variabile. La modalità variabile può essere una di quelle seguenti:

    • IN

    • OUT

    • IN OUT

  • datatype: specifica il tipo di dati della variabile. Questo parametro è obbligatorio.

Il valore predefinito per plsql_params è NULL.

external_params

Specifica i parametri che devono essere forniti alla funzione C esterna.

Se il valore non viene fornito per external_params, vengono utilizzati i parametri PL/SQL.

api_type

Specifica il tipo di API (funzione o procedura).

Il valore predefinito per api_type è function.

with_context

Specifica che un puntatore di contesto viene passato alla procedura esterna. Questo contesto viene utilizzato dalla libreria C esterna per la connessione al database.

Il valore predefinito per with_context è FALSE.

return_type

Specifica il tipo di restituzione della funzione creata.

CREATE_FUNCTION Esempio 

DECLARE
    plsql_params clob    := TO_CLOB('{"sal": "IN, FLOAT", "comm" :"IN, FLOAT"}');
    external_params clob := TO_CLOB('sal FLOAT, sal INDICATOR SHORT, comm FLOAT, comm INDICATOR SHORT,
    RETURN INDICATOR SHORT, RETURN FLOAT');
BEGIN
DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
    LIBRARY_NAME    => 'demolib',
    FUNCTION_NAME   => '"PercentComm"',
    PLSQL_PARAMS    => plsql_params,
    EXTERNAL_PARAMS => external_params,
    API_TYPE        => 'FUNCTION',
    WITH_CONTEXT    => FALSE,
    RETURN_TYPE     => 'FLOAT'
);
END;
/

DROP_CATALOG Procedura

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

Sintassi

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    catalog_name      IN VARCHAR2
 );

DBMS_CLOUD_FUNCTION.DROP_CATALOG (
    library_name      IN VARCHAR2
 );

Parametri

Parametro descrizione;

catalog_name

Specifica il nome del catalogo.

Questo parametro è obbligatorio.
library_name

Specifica il nome della libreria.

Questo parametro è obbligatorio.

Errori

Codice di errore descrizione;

ORA-20003

Questo errore viene generato quando il catalogo specificato non esiste.

Ad esempio: 

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

Ad esempio: 

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

DROP_FUNCTION Procedura

La procedura DBMS_CLOUD_FUNCTION.DROP_FUNCTION elimina la funzione. Questa procedura è sovraccaricata.

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

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

Parametri

Parametro descrizione;

catalog_name

Specifica il nome del catalogo.

Questo parametro è obbligatorio.

function_name

Specifica il nome della funzione da eliminare.

Questo parametro è obbligatorio.

library_name

Specifica il nome della libreria.

Questo parametro è obbligatorio.

Esempi

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

BEGIN
    DBMS_CLOUD_FUNCTION.DROP_FUNCTION (
       library_name     => 'EXTPROC_DEMO_LIBRARY',
       function_name    => 'demo_function');
END;
/

LIST_FUNCTIONS Procedura

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 di errore descrizione;

ORA-20000

Questo errore viene generato quando manca il valore cloud_params o vengono passati valori di parametro errati.

ORA-20001

Questo errore viene generato quando la credenziale a cui viene fatto riferimento nel file credential_name non esiste.

ORA-20003

Questo errore viene generato quando il catalogo specificato non esiste.

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

SYNC_FUNCTIONS Procedura

Questa procedura crea un wrapper PL/SQL per aggiungere nuove funzioni al catalogo e rimuovere i wrapper per le funzioni eliminate dal catalogo.

Sintassi

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

Parametri

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.

Errori

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