Documentazione di Oracle Cloud Infrastructure

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 richiamano 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 delle funzioni per ulteriori informazioni sulla creazione e la distribuzione di Oracle Cloud Infrastructure Functions and Application (ovvero un gruppo di OCI Functions).

  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.

    In questo modo viene creata la credenziale OCI_CRED.

    Per ulteriori informazioni, vedere CREATE_CREDENTIAL Procedura.

    Nota

    Se si utilizza un principal risorsa per l'autenticazione, è necessario configurare i criteri necessari per l'accesso alla funzione OCI. Per ulteriori informazioni, vedere Dettagli per le funzioni.
  2. Creare un 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 Procedura.

  4. Eseguire DBMS_CLOUD_FUNCTION.SYNC_FUNCTIONS per creare funzioni SQL wrapper. È possibile utilizzare uno dei seguenti metodi 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 (crea o elimina) le funzioni wrapper 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 dei 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, conservare una nota dell'utente corrente.

    Per ulteriori informazioni, vedere SYNC_FUNCTIONS Procedura.

    • È possibile creare manualmente nel catalogo una funzione SQL 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 al cui endpoint fa riferimento il parametro FUNCTION_ID. Richiamando la funzione nel catalogo insieme ai relativi argomenti, viene eseguita la funzione cloud corrispondente e viene fornito l'output restituito dalla funzione cloud.

    La creazione manuale di una funzione nel catalogo consente inoltre di creare tipi di restituzione e gestori delle 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 Procedura.

  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.

    La funzione FINTECH_FUN viene eliminata dal catalogo OCI_DEMO_CATALOG.

    Per ulteriori informazioni, vedere DROP_FUNCTION Procedura.

  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.

    Viene eliminato OCI_DEMO_CATALOG dal database.

    Per ulteriori informazioni, vedere DROP_CATALOG Procedura.