Etapes d'appel de fonctions OCI Cloud en tant que fonctions SQL

Affiche les étapes permettant d'appeler des fonctions distantes OCI en tant que fonctions SQL dans la base de données.

Pour appeler des fonctions cloud dans OCI en tant que fonctions SQL, nous allons créer un catalogue de fonctions wrapper SQL qui référencent et appellent leur fonction cloud respective via leurs adresses d'API. Avant de créer ce catalogue, il est supposé que vous avez créé les fonctions cloud nécessaires à référencer par ce catalogue.

Pour plus d'informations sur la création et le déploiement d'Oracle Cloud Infrastructure Functions et d'une application (groupe de fonctions OCI), reportez-vous à Création et déploiement de fonctions.

  1. Créez des informations d'identification en utilisant la procédure DBMS_CLOUD.CREATE_CREDENTIAL. L'objet d'informations d'identification que vous créez doit être de type clé privée.
    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.
    

    Les informations d'identification OCI_CRED sont ainsi créées.

    Pour plus d'informations, reportez-vous à Procédure CREATE_CREDENTIAL.

    Remarque

    Si vous utilisez un principal de ressource pour l'authentification, les stratégies requises pour l'accès à la fonction OCI doivent être configurées. Pour plus d'informations, reportez-vous à la section Détails des fonctions.
  2. Création d'un catalogue

    Un catalogue est un ensemble de fonctions de wrapper qui référencent et appellent leurs fonctions cloud respectives via leurs adresses d'API.

    Exemple permettant de créer un catalogue pour 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.
    

    Le catalogue OCI_DEMO_CATALOG est ainsi créé.

    Pour plus d'informations, reportez-vous à Procédure CREATE_CATALOG. Vous pouvez interroger les vues DBA_CLOUD_FUNCTION_CATALOG View et USER_CLOUD_FUNCTION_CATALOG View pour extraire la liste de tous les catalogues de la base de données.

  3. Vous pouvez répertorier les fonctions dans un catalogue.

    Voici l'exemple pour répertorier 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"
      }
    ]

    Pour plus d'informations, reportez-vous à Procédure LIST_FUNCTIONS.

  4. Exécutez DBMS_CLOUD_FUNCTION.SYNC_FUNCTIONS pour créer des fonctions SQL de wrapper. Vous pouvez utiliser l'une des méthodes suivantes pour créer les fonctions SQL wrapper dans le catalogue, qui appellent leurs fonctions cloud respectives :
    • SYNC_FUNCTIONS : SYNC_FUNCTIONS est la méthode la plus rapide et la plus simple qui synchronise automatiquement (crée ou supprime) les fonctions de wrapper dans le catalogue avec la liste complète des fonctions cloud définies dans la région, le compartiment et la location avec lesquels le catalogue a été créé. Par exemple :

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

    Cela crée un wrapper PL/SQL pour ajouter de nouvelles fonctions au catalogue et enlever des wrappers pour les fonctions qui ont été supprimées du catalogue.

    Exécutez la requête suivante pour vérifier la synchronisation.

    
    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
    
    Remarque

    Notez l'utilisateur en cours pour exécuter cette commande.

    Pour plus d'informations, reportez-vous à Procédure SYNC_FUNCTIONS.

    • Vous pouvez créer manuellement une fonction SQL dans votre catalogue qui appelle sa fonction cloud respective à l'aide de DBMS_CLOUD.CREATE_FUNCTION. Par exemple :

    Exemple permettant de créer une fonction dans le catalogue 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.

    La fonction FINTECH_FUN est ainsi créée dans le catalogue OCI_DEMO_CATALOG.

    La fonction FINTECH_FUN dans le catalogue est une référence à la fonction cloud respective dont l'adresse est référencée par le paramètre FUNCTION_ID. L'appel de la fonction dans le catalogue avec ses arguments exécute la fonction cloud correspondante et fournit la sortie renvoyée par la fonction cloud.

    La création manuelle d'une fonction dans le catalogue vous permet également de créer des types de retour et des gestionnaires de réponses personnalisés. Par exemple :

    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.
    

    Vous pouvez interroger les vues DBA_CLOUD_FUNCTION View et USER_CLOUD_FUNCTION View pour extraire la liste de toutes les fonctions de la base de données.

    Pour plus d'informations, reportez-vous à Procédure CREATE_FUNCTION.

  5. Une fois la fonction créée, vous pouvez DESCRIBE et l'appeler.
    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.

    La fonction cloud fintech_fun est appelée en appelant la référence de fonction oocid1.funfn.oci.phx.aaaaaa_example dans le catalogue OCI_DEMO_CATALOG.

  6. Vous pouvez supprimer une fonction existante en utilisant la procédure DROP_FUNCTION. Par exemple :
    EXEC DBMS_CLOUD_FUNCTION.DROP_FUNCTION (CATALOG_NAME => 'OCI_DEMO_CATALOG', FUNCTION_NAME => 'fintech_fun');
    
    PL/SQL procedure successfully completed.
    

    La fonction FINTECH_FUN est supprimée du catalogue OCI_DEMO_CATALOG.

    Pour plus d'informations, reportez-vous à Procédure DROP_FUNCTION.

  7. Vous pouvez supprimer un catalogue existant en utilisant la procédure DROP_CATALOG. Par exemple :
    BEGIN
        DBMS_CLOUD_FUNCTION.DROP_CATALOG (
          catalog_name     => 'OCI_DEMO_CATALOG'
      );
    END;
    /
    
    PL/SQL procedure successfully completed.

    Cette opération supprime OCI_DEMO_CATALOG de la base de données.

    Pour plus d'informations, reportez-vous à Procédure DROP_CATALOG.