Appeler des fonctions en nuage et des procédures externes

Dans Oracle Database sur place (Enterprise, Standard, Express, Personal Editions), vous pouvez écrire des fonctions définies par l'utilisateur dans PL/SQL, Java ou C pour fournir des fonctionnalités qui ne sont pas disponibles dans les fonctions SQL ou SQL intégrées. Vous pouvez appeler ces fonctions définies par l'utilisateur dans une instruction SQL partout où une expression peut se produire. Voir À propos des fonctions définies par l'utilisateur.

À partir d'Oracle Database 19c, vous pouvez créer, stocker et exécuter des scripts Python à l'aide de la fonction d'exécution Python intégrée dans SQL. Voir Exécution Python intégrée à l'aide d'OML4Py.

Oracle Autonomous AI Database sur une infrastructure Exadata dédiée étend les fonctions définies par l'utilisateur au nuage en vous permettant d'écrire des fonctions SQL qui appellent des services de calcul sans serveur dans le nuage, tels que OCI Functions et AWS Lambda Functions, ou procédures externes - qui incluent des routines C/C++, des scripts Shell ou Python - s'exécutant dans une machine virtuelle de calcul OCI externe à la base de données Autonomous AI Database.

À propos des fonctions en nuage et des procédures externes

Les fonctions définies par l'utilisateur vous permettent d'appeler des fonctions disponibles en externe à partir de code PL/SQL ou SQL dans votre base de données. Vous pouvez appeler les fonctions externes suivantes à l'aide des fonctions définies par l'utilisateur :

• Oracle Cloud Infrastructure Functions : Oracle Cloud Infrastructure Functions est une plate-forme de fonctions-service entièrement gérée, multilocataire, hautement évolutive et sur demande. Oracle Cloud Infrastructure Functions est fondée sur Oracle Cloud Infrastructure de niveau entreprise et est propulsée par le moteur à code source libre de Fn Project. Pour plus d'informations, voir Aperçu du service des fonctions pour OCI.

• Fonctions Lambda AWS : AWS Lambda est un service de calcul sans serveur basé sur les événements qui vous permet d'exécuter du code pour pratiquement toutes les applications ou tous les services dorsaux sans provisionner ni gérer les serveurs. Pour plus d'informations, voir AWS Lambda.

• Procédures externes : Les procédures externes sont des fonctions écrites dans un langage de troisième génération (C, par exemple), des scripts d'interpréteur de commandes du système d'exploitation ou des scripts Python pouvant être appelés en tant que fonctions SQL ou procédures ou fonctions PL/SQL. Pour plus d'informations, voir Qu'est-ce qu'une procédure externe.

Appeler les fonctions OCI Cloud en tant que fonctions SQL

Affiche les étapes pour appeler les fonctions en nuage OCI en tant que fonctions SQL dans votre base de données d'intelligence artificielle autonome sur une infrastructure Exadata dédiée.

Avant de procéder à ces étapes, il est supposé que vous avez créé et déployé le service des fonctions pour OCI dans une location et un compartiment OCI. Voir Service des fonctions pour OCI pour plus de détails.

Une fois que vous aurez utilisé les fonctions OCI, vous utiliserez les API PL/SQL DBMS_CLOUD et DBMS_CLOUD_FUNCTION pour créer un catalogue de fonctions d'encapsuleur SQL dans la base de données IA autonome qui référencent et appellent leur fonction en nuage respective au moyen de leurs points d'extrémité d'API. Vous utiliserez l'API DBMS_CLOUD_FUNCTION pour gérer les fonctions de votre application de base de données.

1. Créez des données d'identification à l'aide de la procédure DBMS_CLOUD.CREATE_CREDENTIAL.

   Indiquez la clé privée d'API de l'utilisateur de la location OCI (contenu du fichier point-pem que vous avez téléchargé lors de la création de la clé d'API) en tant qu'objet de données d'identification, empreinte numérique de la clé, OCID de la location et OCID de l'utilisateur. Voir Clés et OCID requis.

    SET DEFINE OFF
    BEGIN
      DBMS_CLOUD.CREATE_CREDENTIAL (
           credential_name => 'OCI_CRED', -- provide a string as the name
           user_ocid       => 'user_ocid', -- provide the OCID string for the user, obtained from OCI Console User Profile
           tenancy_ocid    => 'tenancy_ocid', -- provide the OCID string for the tenancy, obtained from OCI Console User Profile
           private_key     => 'private_key', -- provide the content of the dot-pem file that you downloaded when you created the API Key
           fingerprint     => 'fingerprint' -- provide the fingerprint string for the API key
      );
    END;
    /
   

   Cela crée l'objet de données d'identification OCI_CRED.

   Pour plus d'informations, voir Procédure CREATE_CREDENTIAL.

2. Créez un objet Catalog à l'aide de la procédure DBMS_CLOUD_FUNCTION.CREATE_CATALOG.

   Un catalogue est une collection de fonctions d'encapsuleur qui référencent et appellent leurs fonctions en nuage respectives au moyen de leurs points d'extrémité d'API. Fournissez l'objet de données d'identification, le nom du fournisseur de services en nuage - dans ce cas OCI, et l'ID région OCI (PHX dans cet exemple) et l'ID compartiment OCI dans lequel se trouvent les fonctions OCI.

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

   Cela crée l'objet de catalogue OCI_DEMO_CATALOG.

   Pour plus d'informations, voir Procédure CREATE_CATALOG. Vous pouvez interroger la vue DBA_CLOUD_FUNCTION_CATALOG et la vue USER_CLOUD_FUNCTION_CATALOG pour extraire la liste de tous les catalogues de fonctions en nuage de votre base de données.

3. Vous pouvez lister toutes les fonctions en nuage du catalogue à l'aide de la procédure DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS.

    SET PAGESIZE 1000
   
    VAR function_list CLOB;
   
    BEGIN
        DBMS_CLOUD_FUNCTION.LIST_FUNCTIONS (
          credential_name  => 'OCI_CRED',
          catalog_name     => 'OCI_DEMO_CATALOG',
          function_list    => :function_list
     );
    END;
    /
   

    SELECT JSON_QUERY (:function_list, '$' RETURNING VARCHAR2(32676) pretty) AS search_results FROM dual;
   

    SEARCH_RESULTS
   
    ------------------------------------------------------------------------------------------------ [
      {
        "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"
        "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"
      },
      {
        "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",
        "invokeEndpoint" : "https://dw.us.func.oci.oraclecloud_example.com"
      }
    ]
   

   Pour plus d'informations, voir Procédure LIST_FUNCTIONS.

4. Créez la fonction SQL Wrapper. Vous pouvez utiliser l'une des deux méthodes suivantes pour créer les fonctions SQL wrapper à partir du catalogue, qui appellent leurs fonctions cloud respectives :

   • Vous pouvez utiliser DBMS_CLOUD_FUNCTION. Procédure SYNC_FUNCTIONS permettant de générer des wrappers SQL à partir de l'objet de catalogue.

   • Vous pouvez créer manuellement des fonctions d'encapsulation individuelles à l'aide de DBMS_CLOUD_FUNCTION. Procédure CREATE_FUNCTION.

   1. SYNC_FUNCTIONS : SYNC_FUNCTIONS synchronise automatiquement (crée et/ou met à jour) les fonctions d'encapsuleur dans le catalogue avec la liste complète des fonctions en nuage définies dans la région, le compartiment et la location avec lesquels le catalogue a été créé.

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

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

      Vous pouvez vérifier les résultats de la synchronisation à l'aide de l'interrogation suivante pour un utilisateur courant donné.

       SHOW user
      

       TEST_USER
      

       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
      

      Pour plus d'informations, voir Procédure SYNC_FUNCTIONS.

   2. CREATE_FUNCTION : Vous pouvez créer manuellement une fonction SQL dans votre catalogue qui appelle sa fonction en nuage respective à l'aide de DBMS_CLOUD.CREATE_FUNCTION.

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

      Cela crée la fonction FINTECH_FUN dans le catalogue OCI_DEMO_CATALOG, en tant que référence à la fonction en nuage respective dont le point d'extrémité est référencé par le paramètre FUNCTION_ID. L'appel de la fonction dans le catalogue avec ses arguments exécute la fonction en nuage correspondante dans OCI et fournit la sortie retournée par la fonction en nuage.

      Note : Le nom de la fonction OCI peut être complètement différent de FINTECH_FUNCTION. Seul l'OCID de la fonction OCI que vous fournissez en tant qu'entrée au paramètre function_id est pris en compte pour créer cette référence.

   3. CREATE_FUNCTION avec des types de retour et des programmes de traitement de réponse personnalisés : La création manuelle de fonctions vous permet de créer des types de retour et des programmes de traitement de réponse personnalisés, comme illustré dans l'exemple suivant.

      Créez d'abord un type de retour et le gestionnaire de réponses de la fonction.

       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.
      

      Ensuite, utilisez ce type et ce gestionnaire de réponses lors de la création manuelle de la fonction d'encapsuleur SQL.

       VAR input_param CLOB;
       VAR l_return_type VARCHAR2(100);
       VAR l_response_handler VARCHAR2(1000);
      
       -- Define function parameters
       exec :input_param       := TO_CLOB('{"command": "VARCHAR2", "value": "VARCHAR2"}');
      

       PL/SQL procedure successfully completed.
      

       exec :l_return_type     := 'fintech_rt';
      

       PL/SQL procedure successfully completed.
      

       exec :l_response_handler := 'fintech_response_handler';
      

       PL/SQL procedure successfully completed.
      

       BEGIN
           DBMS_CLOUD_FUNCTION.CREATE_FUNCTION (
               credential_name  => 'OCI_CRED',
               catalog_name     => 'OCI_DEMO_CATALOG',
               function_name    => 'FINTECH_FUNCTION',
               function_id      => 'ocid1.fnfunc.oc1.phx.aaabbbcccc_example',
               input_args       => :input_param,
               return_type      => :l_return_type,
               response_handler => :l_response_handler
        );
       END;
       /
      

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

      Pour plus d'informations, voir Procédure CREATE_FUNCTION.

      Une fois la fonction créée, vous pouvez la DÉCRIRE pour obtenir ses détails de retour.

       DESC fintech_fun
       COLUMN STATUS format a30
       COLUMN OUTPUT format a30
      

      Vous pouvez ensuite appeler la fonction, en fournissant les valeurs des paramètres d'entrée.

       SET SERVEROUTPUT ON
      
       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;
       /
      

      Cela appelle la fonction en nuage fintech_fun en appelant la référence de fonction oocid1.funfn.oci.phx.aaaaaa_example dans le catalogue OCI_DEMO_CATALOG.

5. Vous pouvez supprimer une fonction existante à l'aide de la procédure DROP_FUNCTION.

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

   Cette action supprime la fonction FINTECH_FUN du catalogue OCI_DEMO_CATALOG.

   Pour plus d'informations, voir Procédure DROP_FUNCTION.

6. Vous pouvez supprimer un catalogue existant à l'aide de la procédure DROP_CATALOG.

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

   Cette action supprime OCI_DEMO_CATALOG de la base de données.

   Pour plus d'informations, voir Procédure DROP_CATALOG.

Appeler les fonctions Lambda AWS en tant que fonctions SQL

Affiche les étapes d'appel des fonctions distantes AWS en tant que fonctions SQL dans votre base de données d'IA autonome sur une infrastructure Exadata dédiée.

Avant de procéder à ces étapes, il est supposé que vous avez créé et déployé des fonctions AWS Lambda dans une location AWS. Voir AWS Lambda pour plus de détails.

Pour accéder aux fonctions lambda d'AWS, vous devez configurer les politiques nécessaires dans Oracle Cloud Infrastructure. Pour plus d'informations, voir Création d'une politique IAM pour accéder aux ressources Lambda AWS et Utilisation de politiques basées sur des ressources pour Lambda.

Une fois que vous aurez activé les fonctions AWS Lambda, vous utiliserez les API PL/SQL DBMS_CLOUD et DBMS_CLOUD_FUNCTION pour créer un catalogue de fonctions d'encapsulation SQL dans la base de données Autonomous AI Database qui référencent et appellent leur fonction cloud respective au moyen de leurs points d'extrémité d'API. Vous utiliserez l'API DBMS_CLOUD_FUNCTION pour gérer les fonctions de votre application de base de données.

1. Créez des données d'identification à l'aide de la procédure DBMS_CLOUD.CREATE_CREDENTIAL en utilisant la clé secrète AWS comme objet de données d'identification.

    SET DEFINE OFF
   
    BEGIN
      DBMS_CLOUD.CREATE_CREDENTIAL (
        credential_name => 'AWS_CRED',
        username        => 'access_key_ID', -- ID of Secret Key
        password        => 'secret_access_key' -- Secret Key password
      );
    END;
    /
   

   Cela crée l'objet de données d'identification AWS_CRED.

   Pour plus d'informations, voir Procédure CREATE_CREDENTIAL.

2. Créez un objet Catalog à l'aide de la procédure DBMS_CLOUD_FUNCTION.CREATE_CATALOG.

   Un catalogue est une collection de fonctions d'encapsuleur qui référencent et appellent leurs fonctions en nuage respectives au moyen de leurs points d'extrémité d'API. Indiquez l'objet de données d'identification, le nom du fournisseur de services en nuage - dans ce cas AWS, et l'ID région AWS (ap-northeast-1 dans cet exemple) dans lequel se trouvent les fonctions AWS Lambda.

    BEGIN
        DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
            credential_name  => 'AWS_CRED',
            catalog_name     => 'AWS_DEMO_CATALOG',
            service_provider => 'AWS',
            cloud_params     => '{"region_id":"ap-northeast-1"}'
     );
    END;
    /
   

   Cela crée l'objet de catalogue AWS_DEMO_CATALOG.

   Pour plus d'informations, voir Procédure CREATE_CATALOG. Vous pouvez interroger la vue DBA_CLOUD_FUNCTION_CATALOG et la vue USER_CLOUD_FUNCTION_CATALOG pour extraire la liste de tous les catalogues de votre base de données.

   Les autres étapes/opérations - à savoir la procédure LIST_FUNCTIONS, la procédure SYNC_FUNCTIONS, la procédure CREATE_FUNCTION, la procédure DROP_FUNCTION et la procédure DROP_CATALOG - ont la même utilisation que celle décrite pour les fonctions en nuage OCI. Voir Appeler les fonctions en nuage OCI en tant que fonctions SQL.

Aperçu des procédures externes

Présente un aperçu des procédures externes et de leur utilisation dans les applications de base de données autonome avec intelligence artificielle sur une infrastructure dédiée.

Les procédures externes sont des fonctions écrites dans un langage de troisième génération et appelées en tant que fonctions SQL ou procédures ou fonctions PL/SQL. Les instructions SQL et PL/SQL sont les mieux adaptées au traitement rapide et efficace des données et des transactions dans la base de données. Les procédures externes peuvent compléter SQL et PL/SQL en exécutant des tâches de calcul et gourmandes en mémoire dans une machine virtuelle externe dédiée et en fournissant les résultats à la base de données. Des exemples typiques de telles tâches sont des problèmes scientifiques et d'ingénierie dont les bibliothèques informatiques existent dans le système d'exploitation Linux (et ne sont pas facilement portables sur une plate-forme de données), l'analyse de données hors ligne, le contrôle des périphériques et des processus en temps réel, etc.

Vous pouvez appeler et utiliser des procédures externes dans votre base de données d'IA autonome avec des fonctions définies par l'utilisateur. Plutôt que d'exécuter ces procédures dans la base de données, vous placerez le code exécutable dans une machine virtuelle OCI Linux dédiée et personnalisée qui est provisionnée avec un conteneur et une exécution pour exécuter des programmes C, des scripts Shell et des scripts Python, ainsi que des bibliothèques Oracle SQL\*Net pour permettre l'exécution SQL à distance à partir de la base de données.

Note : L'hôte distant pour les procédures externes doit être une machine virtuelle EXTPROC OCI Linux provisionnée à partir du marché des applications OCI et configurée dans un réseau en nuage virtuel OCI (VCN) approprié.

L'exécution à distance sur la machine virtuelle OCI Linux EXTPROC n'est prise en charge que par la base de données autonome d'IA sur l'infrastructure Exadata dédiée sur Oracle Public Cloud à partir de la version 19.30 et dans Oracle Database 26ai à partir de la version 23.26.1. Cette fonction n'est pas encore prise en charge par Autonomous AI Database sur une base de données d'infrastructure Exadata dédiée sur Exadata Cloud@Customer (ExaCC).

Configuration du système pour les procédures et les scripts externes

Affiche les étapes de provisionnement de la machine virtuelle EXTPROC et les étapes de configuration du réseau et du calcul OCI pour l'exécution de procédures externes.

Au minimum, l'architecture se compose des ressources suivantes :

• Réseau en nuage virtuel OCI provisionné dans un compartiment OCI dans l'emplacement OCI.

• Une base de données IA autonome, créée en tant qu'instance sous une base de données conteneur autonome, qui est provisionnée à partir d'une grappe de machines virtuelles Exadata autonome (AVMC), créée sur l'infrastructure Exadata sur Oracle Public Cloud.

• Une machine virtuelle EXTPROC fournie dans le cadre d'une pile EXTPROC à partir du marché des applications d'OCI.

À titre de meilleure pratique, la grappe AVM sera placée dans un sous-réseau privé d'un VCN. La table de routage par défaut et les listes de sécurité du VCN seront configurées conformément aux exigences de la base de données d'intelligence artificielle autonome dans la location OCI. Le VCN peut avoir une table de routage par défaut et une liste de sécurité par défaut, où vous pouvez définir toutes les règles de routage et de sécurité. Facultativement, le VCN peut être configuré avec une passerelle NAT si les applications de base de données de l'IA autonome et les autres ressources du sous-réseau privé ont besoin d'un accès sortant à Internet.

Suivez ces étapes minimales de configuration du service de réseau pour OCI lorsque vous introduisez la machine virtuelle ExtProc dans cette topologie.

• Vous devez être en mesure de vous connecter à votre machine virtuelle ExtProc pour créer la bibliothèque partagée (point-so) avec les procédures externes implémentées en C/C++, inspecter et configurer la machine virtuelle et le conteneur, et effectuer d'autres opérations de ce type.

• L'exercice type consiste à configurer la machine virtuelle EXTPROC pour qu'elle se trouve dans un sous-réseau public du VCN. Dans ce cas, vous devez créer une passerelle Internet dans le VCN (si elle n'est pas déjà configurée par l'administrateur).

Note : La machine virtuelle EXTPROC ne doit PAS se trouver dans un sous-réseau dont l'intervalle CIDR est 10.x.x.x. Si l'adresse IP de la machine virtuelle EXPROC est 10.x.x.x, elle ne pourra pas communiquer avec la base de données IA autonome.

• Vous devez définir une règle de trafic entrant dans la liste de sécurité du VCN pour permettre l'accès par connexion SSH à la machine virtuelle au moyen du port 22. Vous devez également définir une règle de trafic sortant dans la liste de sécurité du VCN pour permettre à ADBD d'accéder au port de destination 16000 pour qu'il soit spécifique, ou à tous les ports de destination, en général. Voir Accès au réseau OCI et sécurité.

• Dans le cadre du provisionnement de la pile de machines virtuelles EXTPROC, vous fournirez toutes les adresses IP de client de la machine virtuelle autonome. Vous obtiendrez ces adresses IP de client IPv4 à partir du tableau de bord OCI pour la grappe AVM.

• Par la suite, l'outil de provisionnement créera automatiquement un groupe de sécurité de réseau (NSG) nommé nsg_acl. Ce groupe de sécurité de réseau aura une règle de trafic entrant autorisant les adresses IP de client dédié Autonomous Database comme seules sources pouvant accéder à la destination du port 16000.

Sujets avancés

• Si les sous-réseaux hébergeant la machine virtuelle ExtProc et la base de données d'intelligence artificielle autonome se trouvent dans le même VCN, vous n'avez pas besoin de spécifier de règles de routage spéciales dans la table de routage du VCN. Si les sous-réseaux hébergeant la machine virtuelle ExtProc et le domaine ADBD se trouvent dans des réseaux en nuage virtuels différents, vous devez mettre en oeuvre l'appairage de VCN. Voir Appairage de réseau VCN.

• Si vous choisissez de configurer la machine virtuelle ExtProc dans un sous-réseau privé, vous devez pouvoir vous connecter à la machine virtuelle au moyen d'un serveur bastion/sortant et activer le trafic entrant uniquement dans la machine virtuelle ExtProc, et sécuriser l'accès aux autres ressources du sous-réseau privé, telles que la base de données IA autonome. Voir les guides du service de réseau pour OCI pour plus de détails.

Mettre en oeuvre des fonctions définies par l'utilisateur avec des procédures externes

1. Provisionner et configurer la machine virtuelle EXTPROC à partir du marché des applications pour OCI

   a. Connectez-vous à la console OCI à l'adresse http://cloud.oracle.com. Pour plus d'informations, voir Se connecter à la console Oracle Cloud Infrastructure.

   b. Dans le menu de navigation de gauche d'Oracle Cloud Infrastructure, accédez au site Marketplace, puis, sous Marketplace, cliquez sur Toutes les applications.

   c. Entrez "EXTPROC" dans la barre de recherche, puis cliquez sur Rechercher. Vous verrez deux widgets - un étiqueté Stack, et un autre étiqueté Image.

   j. Sélectionnez le widget nommé Pile (ceci est important). This will take you to Oracle Autonomous Database EXTPROC Agentdetails page, providing the stack version, release date, and release notes about the Stack. Dans cette page, cliquez sur le bouton Lancer la pile. Vous accédez alors à la page Launch Stack suivante.

   e. Dans la page Launch Stack :

   • Dans la liste déroulante Version, sélectionnez la version d'ensemble de la pile.

   • Dans la liste déroulante Compartiment, sélectionnez le nom du compartiment dans lequel vous voulez provisionner la machine virtuelle EXTPROC. Sauf si vous avez des raisons spécifiques de ne pas le faire, sélectionnez le même compartiment que celui de la base de données autonome (il est recommandé d'éviter le compartiment racine pour toute ressource).

   • Acceptez les conditions générales et cliquez sur Lancer la pile.

   Vous accédez alors à la page suivante : l'assistant Create Stack.

   f. Dans cette page, fournissez un nom, une description, un nom de compartiment, la version de Terraform et toutes les informations de marqueur. Le nom du compartiment est obligatoire et le plus important, entrée dans l'assistant dans cette page. Cliquez sur Suivant.

   v. Vous accédez ainsi à la page des variables de configuration de la machine virtuelle EXTPROC (également appelée agent EXTPROC). La première partie de cette page rassemble les informations sur les bibliothèques EXTPROC et un mot de passe de portefeuille.

   • Pour les bibliothèques externes, fournissez une liste de bibliothèques, séparées par une virgule (,), que vous voulez autoriser à appeler à partir de votre base de données d'intelligence artificielle autonome sur une infrastructure dédiée. Ces bibliothèques partagées contiendront les procédures externes écrites en C/C++, qui sont idéalement compilées et intégrées dans la machine virtuelle elle-même (pour correspondre à l'architecture et à l'environnement).

     Note : Étant donné que vous êtes toujours en cours de création de la machine virtuelle EXTPROC, notez les noms des bibliothèques partagées que vous fournissez ici. Lorsque la machine virtuelle est disponible et que vous développez vos procédures externes en C/C++, n'oubliez pas de compiler et de construire la bibliothèque/les bibliothèques avec le(s) nom(s) exact(s) fourni(s) ci-dessus.

   • Pour Mot de passe du portefeuille, indiquez un mot de passe pour le fichier de portefeuille qui sera créé dans la machine virtuelle ExtProc. Le portefeuille et un certificat auto-signé sont générés pour l'authentification TLS mutuelle entre la base de données d'IA autonome sur une infrastructure dédiée et la machine virtuelle de l'agent EXTPROC.

   h. La deuxième partie de la page des variables de configuration implique la configuration réseau de la machine virtuelle EXTPROC.

   • Pour Compartiment, sélectionnez le nom du compartiment pour le VCN dans le menu déroulant. Dans l'exemple ci-dessus, il est représenté par adbd. Idéalement, la base de données d'IA autonome et la machine virtuelle EXTPROC seront colocalisées dans le même VCN, même dans des sous-réseaux (privés et publics) différents.

   • Pour Stratégie de réseau, sélectionnez "Utiliser le VCN et le sous-réseau existants". Comme indiqué dans une section précédente, à ce stade de votre effort de développement ExtProc, vous pouvez avoir l'architecture système en place avec une base de données VCN, AVMC et Autonomous AI Database.

     Note : L'autre choix consiste à créer un nouveau VCN et un sous-réseau avec sa propre stratégie de configuration pour l'agent de machine virtuelle EXTPROC. Si vous choisissez de placer la machine virtuelle EXTPROC dans un VCN différent de celui de la base de données IA autonome, vous devez appairer les réseaux en nuage virtuels.

   • Ignorez l'entrée suivante pour le type d'accès de l'agent EXTPROC. Ce champ ne s'applique pas à une base de données autonome avec intelligence artificielle sur une infrastructure Exadata dédiée.

   i. Ensuite, dans le champ étiqueté "Adresses IP de point d'extrémité privé", entrez TOUTES les adresses IP client de la machine virtuelle autonome sur laquelle la base de données est configurée. Vous pouvez obtenir ces adresses IP de client à partir du tableau de bord de la console OCI pour la machine virtuelle autonome.

   • Pour le réseau en nuage virtuel, indiquez le nom du VCN dans lequel vous voulez créer l'agent de machine virtuelle EXTPROC.

   • Pour Sous-réseau EXTPROC, indiquez le nom du sous-réseau dans lequel vous voulez créer l'agent de machine virtuelle EXTPROC.

   j. Fournissez ensuite les détails du VCN et du sous-réseau.

   Note : La machine virtuelle EXTPROC ne doit PAS se trouver dans un sous-réseau dont l'intervalle CIDR est 10.x.x.x. Si l'adresse IP de la machine virtuelle EXPROC est 10.x.x.x, elle ne pourra pas communiquer avec la base de données IA autonome.

   k. La dernière partie de la page de configuration concerne la configuration de calcul de l'agent de machine virtuelle EXTPROC.

   • Pour Compartiment, sélectionnez le nom du compartiment dans le menu déroulant. Il est recommandé de colocaliser la machine virtuelle dans le même compartiment que celle de la base de données d'IA autonome sur une infrastructure dédiée, du VCN et du sous-réseau pour minimiser le dépannage.

   • Pour Forme, Nombre d'OCPU et Taille de mémoire (Go), entrez des valeurs en fonction des caractéristiques de charge de travail de vos procédures externes.

   • Pour Ajouter des clés SSH, générez les fichiers de clés publiques et privées SSH dans votre système d'exploitation Linux, MacOS ou Windows. Ouvrez une fenêtre de terminal et exécutez l'une des commandes suivantes (ED25519 est l'algorithme moderne et plus sûr; les anciens systèmes prennent en charge l'algorithme de chiffrement RSA) :

     ssh-keygen -t ed25519 -C "[e-mail]" (OR)
     ssh-keygen -t rsa -b 4096 -C "[e-mail]"
     

     Cela générera un fichier de clé privée ssh-key-<date-time-id>.key et un fichier de clé publique ssh-key-<date-time-id>.key.pub. Copiez-collez le contenu de la clé publique SSH dans la fenêtre ou glissez-déposez le fichier .pub dans la fenêtre.

   • Cliquez sur Suivant.

   l (HeartBeatInterval). Vous accédez alors à la page Review. Vérifiez toutes les entrées, puis cochez la case Exécuter l'application, puis cliquez sur Créer.

   Le gestionnaire de ressources OCI sera lancé pour créer la pile de machines virtuelles EXTPROC. Une fois la tâche ORM terminée, la machine virtuelle EXTPROC sera créée et en cours d'exécution.

2. Collecter les informations sur le système de MV EXTPROC pour l'entrée d'API DBMS_CLOUD_FUNCTION

   Vous devez fournir les informations sur le système de MV EXTPROC en tant qu'entrées aux API DBMS_CLOUD_FUNCTION dans la base de données IA autonome pour permettre l'appel de procédures externes à partir de la base de données.

   a. Dans le menu de navigation de gauche d'Oracle Cloud Infrastructure, accédez au menu déroulant Calcul, sélectionnez le compartiment que vous avez spécifié pour le provisionnement de machines virtuelles EXTPROC et consultez le tableau de bord listant toutes les machines virtuelles du compartiment. La tâche ORM aura créé la machine virtuelle EXTPROC sous le nom canonique EXTPROC-agent ou EXTPROC-agent-<setofnumbers>. Il s'agit du nom d'hôte de votre instance de machine virtuelle EXTPROC. En cliquant sur cette entrée, vous accédez à la page qui affiche les détails du système - les adresses IPV4 publiques et privées (IPv4 et IPv6), le sous-réseau et les détails de l'image.

   b. Connectez-vous à la machine virtuelle ExtProc à l'aide de la clé SSH que vous avez fournie lors de la création de la pile ExtProc et de l'adresse IP. L'utilisateur par défaut sur la machine virtuelle est opc. sudo pour devenir l'utilisateur oracle.

    ~ ssh -i ssh-key-<date-time-id>.key opc@<Public-IP-Address>
   

    Wed Nov 19 10:46:25 GMT 2025: EXTPROC Agent intialization completed.
   
    Activate the web console with: systemctl enable --now cockpit.socket
       
    Last login: Thu Nov 20 20:10:54 2025 from  <client-IP-address>
   

    [opc@extproc-agent-170798 ~]$ whoami
   

    opc
   
    [opc@extproc-agent-170798 ~]$ sudo su - oracle
    Last login: Wed Nov 19 19:07:24 GMT 2025 on pts/0
   

   La machine virtuelle EXTPROC aura un conteneur Podman en cours d'exécution avec un module d'écoute Oracle SQL*Net. Dans le conteneur, un environnement client Oracle avec les fichiers de configuration nécessaires tels que sqlnet.ora, listener.ora sera disponible, ainsi qu'un fichier de portefeuille pour une communication sécurisée avec la base de données IA autonome.

   c. Collectez les informations système requises pour les API PL/SQL au niveau du système d'exploitation, puis à partir du conteneur Podman configuré dans la machine virtuelle. Le conteneur exécute Oracle Listener pour recevoir les demandes d'exécution à distance de l'application SQL et PL/SQL sur Autonomous AI Database et est le moteur d'exécution de la procédure externe.

   • À partir du système d'exploitation Linux, le nom de domaine complet de l'hôte de machine virtuelle EXTPROC.

   • À partir du conteneur Podman, à partir du statut du module d'écoute, le port de la machine virtuelle EXTPROC sur laquelle la base de données se connecte à la machine virtuelle.

   • Dans le conteneur Podman, à partir de la spécification sqlnet.ora, l'emplacement du fichier de portefeuille.

   • À partir d'une inspection du fichier de portefeuille à l'aide de l'outil orapki, la valeur du paramètre Distinguished Name (DN) pour le certificat de portefeuille.

    [oracle@extproc-agent-170798 ~]$ hostname -f
    extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com
   
    [oracle@extproc-agent-170798 ~]$ podman ps
    CONTAINER ID  IMAGE                              COMMAND     CREATED       STATUS                 PORTS       NAMES
    86d81c4df6ff  ghcr.io/oracle/adb-extproc:latest              23 hours ago  Up 23 hours (healthy)              adb-extproc
   
    [oracle@extproc-agent-170798 ~]$ podman exec -it 86d81c4df6ff bash
   
    (base) [oracle@extproc-agent-170798 admin]$ lsnrctl status
   
    LSNRCTL for Linux: Version 23.26.0.0.0 - for Oracle Cloud and Engineered Systems on 20-NOV-2025 09:25:54
   
    Copyright (c) 1991, 2025, Oracle.  All rights reserved.
   
    Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=IPC)(KEY=EXTPROC1)))
    STATUS of the LISTENER
   
    ------------------------
    Alias                     LISTENER
    Version                   TNSLSNR for Linux: Version 23.26.0.0.0 - for Oracle Cloud and Engineered Systems
    Start Date                19-NOV-2025 17:19:58
    Uptime                    0 days 16 hr. 5 min. 55 sec
    Trace Level               off
    Security                  ON: Local OS Authentication
    SNMP                      OFF
    Listener Parameter File   /u01/app/oracle/product/23.0.0.0/client_1/network/admin/listener.ora
    Listener Log File         /u01/app/oracle/diag/tnslsnr/extproc-agent-170798/listener/alert/log.xml
    Listening Endpoints Summary...
      (DESCRIPTION=(ADDRESS=(PROTOCOL=ipc)(KEY=EXTPROC1)))
      (DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=0.0.0.0)(PORT=16000)))
    Services Summary...
    Service "extproccontainer.com" has 1 instance(s).
      Instance "extproccontainer", status UNKNOWN, has 1 handler(s) for this service...
     The command completed successfully
   
    (base) [oracle@extproc-agent-170798 /]$ cd $ORACLE_HOME/network/admin
   
    (base) [oracle@extproc-agent-170798 admin]$ cat sqlnet.ora
   
    NAMES.DIRECTORY_PATH= (TNSNAMES, EZCONNECT)
    WALLET_LOCATION =(SOURCE = (METHOD = FILE)(METHOD_DATA = (DIRECTORY = /u01/app/oracle/wallets/extproc_wallet)))
    tcp.invited_nodes=(20.63.19.141,20.63.19.141,20.63.19.143,20.63.19.144)
    tcp.validnode_checking=yes
   
    (base) [oracle@extproc-agent-170798 admin]$ orapki wallet display -wallet /u01/app/oracle/wallets/extproc_wallet/cwallet.sso
    Oracle PKI Tool Release 23.0.0.0.0 - Production
    Version 23.0.0.0.0
    Copyright (c) 2004, 2025, Oracle and/or its affiliates. All rights reserved.
   
    Requested Certificates:
    User Certificates:
    Subject:        CN=extproc-agent-170798
    Trusted Certificates:
    Subject:        CN=extproc-agent-170798
    (base) [oracle@extproc-agent-170798 admin]$ exit
    exit
   

   Dans l'exemple ci-dessus, nous avons collecté les entrées suivantes pour l'API DBMS_CLOUD_FUNCTION.CREATE_CATALOG.

   • La chaîne formée par le nom de domaine complet + le numéro de port sera l'entrée du paramètre library_listener_url. Dans cet exemple, il s'agit de 'extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com :16000'.

   • sqlnet.ora contient l'emplacement du fichier de portefeuille dans la machine virtuelle : /u01/app/oracle/wallets/extproc_wallet/cwallet.sso. Notez la liste d'adresses IP pour tcp.invited_nodes. Il doit contenir la liste des adresses IP de client que vous avez fournies en entrée pour la configuration réseau lors de la création de la pile de machines virtuelles EXTPROC.

   • Le nom distinctif du certificat (DN) sera l'entrée du paramètre library_ssl_server_cert_dn : 'CN=extproc-agent-170798'.

3. Créez la bibliothèque C et placez-la à l'emplacement spécifié dans le système de fichiers de machine virtuelle EXTPROC

   Codez les fonctions C, créez-les et placez la bibliothèque dans le répertoire désigné dans le système de fichiers de la machine virtuelle de l'agent ExtProc.

   Le nom de la bibliothèque doit correspondre exactement au(x) nom(s) que vous avez fourni(s) lors de la création de la pile ExtProc. Si vous l'avez égaré, vous pouvez le trouver dans l'entrée EXTPROC_DLLS du fichier initextproccontainer.ora du conteneur ExtProc, comme illustré ci-dessous, ou dans la section "Variables" de la tâche ORM (Oracle Resource Manager) qui a créé la pile ExtProc. Vous devez copier les bibliothèques dans le répertoire /u01/app/oracle/extproc_libs de la machine virtuelle de l'agent EXTPROC.

   • Le chemin complet du fichier (dans cet exemple "/u01/app/oracle/extproc_libs/helloCextproc.so") sera l'entrée du paramètre library_remote_path de DBMS_CLOUD_FUNCTION.CREATE_CATALOG().

    (base) [oracle@extproc-agent-170798 client_1]$ cat $ORACLE_HOME/hs/admin/initextproccontainer.ora
    SET TRACE_LEVEL=ON
    SET _EXTPROC_REMOTE=TRUE
    SET WHOAMI=FROMDOCKER
    SET LD_LIBRARY_PATH=/u01/app/oracle/product/23.0.0.0/client_1/lib:/u01/app/oracle/extproc_libs:/opt/conda/lib
    SET EXTPROC_DLLS=ONLY:/u01/app/oracle/product/extprocutils.so:/u01/app/oracle/product/23.0.0.0/client_1/lib/libgsfextproc.so:/u01/app/oracle/extproc_libs/helloCextproc.so
    SET PYTHONHOME=/opt/conda
    SET SCRIPTS_FOLDER_LOC_ENV=/u01/app/oracle/extproc_scripts
    SET TRACE_FILE_LOC_ENV=/u01/app/oracle/extproc_logs
    SET PYTHONPATH=/tmp:/u01/app/oracle/extproc_scripts
    (base) [oracle@extproc-agent-170798 client_1]$ exit
   
    [oracle@extproc-agent-170798 ~]$ cat > helloCextproc.c
    #include <stdio.h>
    const char* helloCextproc() {
            return ("\nHello C Extproc from FQDN: extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com\n");
    }
    ^D
   
    [oracle@extproc-agent-170798 ~]$ gcc -shared -fPIC -o /u01/app/oracle/extproc_libs/helloCextproc.so helloCextproc.c
   
    [oracle@extproc-agent-170798 ~]$ ls -al /u01/app/oracle/extproc_libs/
    total 8
    drwxr-xr-x. 2 oracle oinstall   30 Nov 19 11:14 .
    drwxr-xr-x. 6 root   root       91 Nov 14 02:19 ..
   
    -rwxr-xr-x. 1 oracle oinstall 8184 Nov 19 11:14 helloCextproc.so
    [oracle@extproc-agent-170798 ~]$
   

   Toutes les entrées de paramètre nécessaires à la création de l'objet Catalogue/Bibliothèque dans l'application de base de données seront terminées.

4. Charger le fichier de portefeuille de la machine virtuelle ExtProc dans le stockage d'objets OCI

   Un portefeuille auto-signé est créé dans le cadre de la création de l'application d'agent EXTPROC. Ce portefeuille vous permet d'accéder à l'instance d'agent Extproc.

   Pour exécuter des procédures distantes sur l'instance d'agent EXTPROC, la base de données IA autonome et l'agent EXTPROC se connectent à l'aide de la sécurité de la couche de transport mutuel (mTLS). Lors de l'utilisation de la sécurité de la couche de transport mutuel (mTLS), les clients se connectent au moyen d'une connexion TCPS (TCP sécurisé) à la base de données à l'aide de la norme TLS 1.2 avec un certificat de client approuvé d'une autorité de certification (CA).

   Note : Vous pouvez également obtenir et utiliser un certificat public émis par une autorité de certification.

   Comme préalable, vous devez exporter le portefeuille du répertoire /u01/app/oracle/extproc_wallet sur la machine virtuelle où EXTPROC s'exécute vers le service de stockage d'objets pour OCI.

   Note :

   • Sécurisez le fichier de portefeuille. Le fichier de portefeuille, ainsi que l'ID utilisateur et le mot de passe de la base de données, permettent d'accéder à l'instance d'agent EXTPROC. Stockez les fichiers de portefeuille dans un emplacement sécurisé et partagez-les uniquement avec les utilisateurs autorisés.
   • Ne renommez pas le fichier de portefeuille. Le fichier de portefeuille dans le stockage d'objets doit être nommé cwallet.sso.

5. Créer le catalogue, définir des fonctions SQL et appeler des procédures externes en tant que fonctions SQL

   Dans les étapes précédentes, nous disposons de toutes les entrées dont nous avons besoin pour que les API DBMS_CLOUD_FUNCTION puissent exécuter des procédures distantes à partir d'applications de base de données SQL ou PL/SQL.

   Ensuite, importez le portefeuille, cwallet.sso, contenant les certificats de l'instance d'agent EXTPROC du stockage d'objets dans un répertoire de votre base de données d'intelligence artificielle autonome.

   Créez des données d'identification pour accéder au stockage d'objets où vous avez stocké le fichier de portefeuille cwallet.sso. Voir Procédure CREATE_CREDENTIAL pour plus d'informations sur les paramètres de nom d'utilisateur et de mot de passe pour différents services de stockage d'objets.

   Créez un objet DIRECTORY dans la base de données et téléchargez le portefeuille dans le répertoire à l'aide de l'API DBMS_CLOUD.GET_OBJECT.

     SET DEFINE OFF
   
     BEGIN
      DBMS_CLOUD.CREATE_CREDENTIAL (
        credential_name => 'OCI_CREDENTIAL',
        user_ocid       => '<oci_user_ocid>',
        tenancy_ocid    => '<oci_tenancy_ocid>',
        private_key     => '<API-key-dot-pem-file-contents>',
        fingerprint     => '<fingerprint-created-with-API-key>');
    END;
    /
   
    CREATE DIRECTORY extprocwalletdir AS 'extprocwalletdir';
   

    Directory created.
   

    SELECT directory_name, directory_path FROM dba_directories WHERE directory_name LIKE '%EXTPROC%';
   

    DIRECTORY_NAME    DIRECTORY_PATH
   
    ----------------  -------------------------------------------------------------------------
    EXTPROCWALLETDIR  /u02/data/dbfs/<adbd-name>/42E945D608E16DF9E0630301000AF88D/extprocwalletdir
   

     BEGIN
      DBMS_CLOUD.GET_OBJECT (
      credential_name     => 'OCI_CREDENTIAL',
      object_uri          => 'https://objectstorage.us-ashburn-1.oraclecloud.com/p/aN.../n/zr.../b/bucket-name-20260129/o/cwallet.sso',
      directory_name      => 'EXTPROCWALLETDIR'
      );
    END;
    /
   

   Ensuite, créez l'objet Library dans la base de données qui représente la bibliothèque C dans ExtProc, avec les paramètres d'entrée que vous avez collectés à l'étape précédente.

    BEGIN
      DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
         library_name               => 'EXTPROC_LIBRARY',
         library_listener_url       => 'extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com:16000',
         library_wallet_dir_name    => 'EXTPROCWALLETDIR',
         library_ssl_server_cert_dn => 'CN=extproc-agent-170798',
         library_remote_path        => '/u01/app/oracle/extproc_libs/helloCextproc.so'
      );
    END;
    /
   

    PL/SQL procedure successfully completed.
   

     SELECT catalog_name from DBA_CLOUD_FUNCTION_CATALOG WHERE catalog_name LIKE '%EXTPROC%';
   

    CATALOG_NAME
   
    ---------------
    EXTPROC_LIBRARY
   

   Créez la fonction SQL mappée à la fonction ExtProc C. Voir le nom de la fonction C du programme écrit ci-dessus.

     CREATE OR REPLACE FUNCTION HELLOCEXTPROC RETURN VARCHAR2 AS
        LANGUAGE C
        LIBRARY EXTPROC_LIBRARY
        NAME "helloCextproc";
    /
   

    Function created.
   

   Appelez la fonction SQL. Il s'agit d'une exécution réussie (voir le corps de la fonction C de la routine C ci-dessus).

     SELECT HELLOCEXTPROC() FROM dual;
   

    HELLOCEXTPROC()
   
    ----------------------------------------------------------------------------------
    Hello C Extproc from FQDN: extproc-agent-170798.subnet-name.vcn-name.oraclevcn.com
   

Rubriques connexes

Ensemble DBMS_CLOUD_FUNCTION