Documentazione dell'infrastruttura Oracle Cloud

Passi per richiamare le funzioni cloud OCI come funzioni SQL

Mostra i passi per richiamare le funzioni remote OCI come funzioni SQL nel database.

Per richiamare le funzioni cloud in OCI come funzioni SQL, creeremo un catalogo di funzioni wrapper SQL che fanno riferimento e chiamano la rispettiva funzione cloud tramite gli endpoint API. Prima di creare questo catalogo, si presume che siano state create le funzioni cloud necessarie a cui questo catalogo fa riferimento.

Vedere Creazione e distribuzione di funzioni per ulteriori informazioni sulla creazione e la distribuzione di Oracle Cloud Infrastructure Functions e Application (ovvero un gruppo di funzioni OCI).

  1. Creare le credenziali utilizzando la procedura DBMS_CLOUD.CREATE_CREDENTIAL. L'oggetto credenziale che si sta creando deve essere di tipo chiave privata.
    SET DEFINE OFF
BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL (
       credential_name => 'OCI_CRED',
       user_ocid       => 'user_ocid',
       tenancy_ocid    => 'tenancy_ocid',
       private_key     => 'private_key',
       fingerprint     => 'fingerprint'
  );
END;
/

PL/SQL procedure successfully completed.

    Viene creata la credenziale OCI_CRED.

    Per ulteriori informazioni, vedere CREATE_CREDENTIAL Procedure.

    Nota

    Se si utilizza un principal risorsa per l'autenticazione, è necessario configurare i criteri necessari per l'accesso alle funzioni OCI. Per ulteriori informazioni, vedere Dettagli per le funzioni.
  2. Crea catalogo.

    Un catalogo è una raccolta di funzioni wrapper che fanno riferimento e richiamano le rispettive funzioni cloud tramite gli endpoint API.

    Esempio per creare un catalogo per Oracle Cloud Infrastructure Functions. 

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

PL/SQL procedure successfully completed.

    In questo modo viene creato il catalogo OCI_DEMO_CATALOG.

    Per ulteriori informazioni, vedere CREATE_CATALOG Procedure. È possibile eseguire una query sulle viste DBA_CLOUD_FUNCTION_CATALOG View e USER_CLOUD_FUNCTION_CATALOG View per recuperare la lista di tutti i cataloghi del database.

  3. È possibile elencare le funzioni in un catalogo.

    Di seguito è riportato l'esempio per elencare Oracle Cloud Infrastructure Functions: 

    VAR function_list CLOB;

BEGIN
    DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS (
      credential_name  => 'OCI_CRED', 
      catalog_name     => 'OCI_DEMO_CATALOG',
      function_list    => :function_list
 );
END;
/

PL/SQL procedure successfully completed.

SELECT JSON_QUERY (:function_list, '$' RETURNING VARCHAR2(32676) pretty) AS search_results FROM dual;
SEARCH_RESULTS                        --This is a sample output
------------------------------------------------------------------------------------------------
[
  {
    "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"
SEARCH_RESULTS
------------------------------------------------------------------------------------------------
4ayosyosv4sthmya2lyza",
    "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"
  },
SEARCH_RESULTS
------------------------------------------------------------------------------------------------
  {
    "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",

SEARCH_RESULTS
------------------------------------------------------------------------------------------------
    "invokeEndpoint" : "https://dw.us.func.oci.oraclecloud_example.com"
  }
]

    Per ulteriori informazioni, vedere LIST_FUNCTIONS Procedure.

  4. Eseguire DBMS_CLOUD_FUNCTION.SYNC_FUNCTIONS per creare funzioni SQL wrapper. È possibile utilizzare uno dei metodi seguenti per creare le funzioni SQL wrapper nel catalogo, che richiamano le rispettive funzioni cloud:

    • SYNC_FUNCTIONS: SYNC_FUNCTIONS è il metodo più rapido e semplice, che sincronizza automaticamente le funzioni wrapper (crea o elimina) nel catalogo con la lista completa delle funzioni cloud definite nell'area, nel compartimento e nella tenancy con cui è stato creato il catalogo. Ad esempio: 

    
BEGIN
 DBMS_CLOUD_FUNCTION.SYNC_FUNCTIONS (
        catalog_name => 'OCI_DEMO_CATALOG'
 );
END;
/
PL/SQL procedure successfully completed.

    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.

    Eseguire la seguente query per verificare la sincronizzazione.

    
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
    Nota

    Per eseguire questo comando, tenere presente l'utente corrente.

    Per ulteriori informazioni, vedere SYNC_FUNCTIONS Procedure.

    • È possibile creare manualmente una funzione SQL nel catalogo che richiama la rispettiva funzione cloud utilizzando DBMS_CLOUD.CREATE_FUNCTION. Ad esempio:

    Esempio di creazione di una funzione nel catalogo OCI_DEMO_CATALOG. 

    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_fun',
        function_id      => 'ocid1.fnfunc.oc1.phx.aaabbbcccc_example',
        input_args       => :function_args
 );
END;
/

PL/SQL procedure successfully completed.

    In questo modo viene creata la funzione FINTECH_FUN nel catalogo OCI_DEMO_CATALOG.

    La funzione FINTECH_FUN nel catalogo è un 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 e fornisce l'output restituito dalla funzione cloud.

    La creazione manuale di una funzione nel catalogo consente inoltre di creare tipi di reso e handler di risposte personalizzati. Ad esempio:

    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.

VAR input_param clob;
VAR  l_return_type varchar2(100);
VAR  l_response_handler varchar2(1000);

exec :input_param       := TO_CLOB('{"command": "VARCHAR2", "value": "VARCHAR2"}');
exec :l_return_type     := 'fintech_rt';
exec :l_response_handler := 'fintech_response_handler';

PL/SQL procedure successfully completed.

PL/SQL procedure successfully completed.

PL/SQL procedure successfully completed.

EXEC DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (CREDENTIAL_NAME => 'OCI_CRED', FUNCTION_NAME => 'fintech_fun', CATALOG_NAME => 'OCI_DEMO_CATALOG', FUNCTION_ID => 'ocid1.funfn.oci.phx.aaaaaa_example', INPUT_ARGS => :input_param, RETURN_TYPE => :l_return_type ,RESPONSE_HANDLER =>:l_response_handler);

PL/SQL procedure successfully completed.

    È possibile eseguire una query sulle viste DBA_CLOUD_FUNCTION View e USER_CLOUD_FUNCTION View per recuperare la lista di tutte le funzioni del database.

    Per ulteriori informazioni, vedere CREATE_FUNCTION Procedure.

  5. Dopo aver creato la funzione, è possibile DESCRIBE e richiamarla.
    DESC fintech_fun
COLUMN STATUS format a30
COLUMN OUTPUT format a30
    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;
/

PL/SQL procedure successfully completed.

    Viene richiamata la funzione cloud fintech_fun richiamando il riferimento funzione oocid1.funfn.oci.phx.aaaaaa_example nel catalogo OCI_DEMO_CATALOG.

  6. È possibile eliminare una funzione esistente utilizzando la procedura DROP_FUNCTION. Ad esempio:
    EXEC DBMS_CLOUD_FUNCTION.DROP_FUNCTION (CATALOG_NAME => 'OCI_DEMO_CATALOG', FUNCTION_NAME => 'fintech_fun');

PL/SQL procedure successfully completed.

    Questa operazione elimina la funzione FINTECH_FUN dal catalogo OCI_DEMO_CATALOG.

    Per ulteriori informazioni, vedere DROP_FUNCTION Procedure.

  7. È possibile eliminare un catalogo esistente utilizzando la procedura DROP_CATALOG. Ad esempio:
    BEGIN
    DBMS_CLOUD_FUNCTION.DROP_CATALOG (
      catalog_name     => 'OCI_DEMO_CATALOG'
  );
END;
/

PL/SQL procedure successfully completed.

    In questo modo OCI_DEMO_CATALOG viene eliminato dal database.

    Per ulteriori informazioni, vedere DROP_CATALOG Procedure.