Appeler des fonctions cloud et des procédures externes

Dans une base de données Oracle Database sur site (Enterprise, Standard, Express, Personal Editions), vous pouvez écrire des fonctions définies par l'utilisateur en 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 chaque fois qu'une expression peut se produire. Reportez-vous à A propos des fonctions définies par l'utilisateur.

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

Oracle Autonomous AI Database on Dedicated Exadata Infrastructure étend la fonctionnalité de fonctions définies par l'utilisateur au cloud en vous permettant d'écrire des fonctions SQL qui appellent des services de calcul sans serveur dans le cloud, tels qu'OCI Fonctions et fonctions AWS Lambda, 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.

Rubriques connexes

A propos des fonctions cloud et des procédures externes

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

  • Oracle Cloud Infrastructure Functions : Oracle Cloud Infrastructure Functions est une plate-forme Functions-as-a-Service entièrement gérée, colocative, hautement évolutive et à la demande. Oracle Cloud Infrastructure Functions s'appuie sur Oracle Cloud Infrastructure de niveau professionnel et est optimisé par le moteur open source du projet Fn. Pour plus d'informations, reportez-vous à Présentation des fonctions OCI.
  • Fonctions lambda AWS : AWS Lambda est un service de calcul sans serveur axé sur les événements qui vous permet d'exécuter du code pour pratiquement toutes les applications ou tous les services back-end sans provisionner ni gérer de serveurs. Pour plus d'informations, reportez-vous à 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 shell de système d'exploitation ou des scripts Python qui peuvent ê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 des fonctions OCI Cloud en tant que fonctions SQL

Présente les étapes permettant d'appeler des fonctions cloud OCI en tant que fonctions SQL dans votre base de données 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 OCI dans une location et un compartiment OCI. Pour plus de détails, reportez-vous à Fonctions OCI.

Une fois les fonctions OCI fonctionnelles, vous utiliserez les API PL/SQL DBMS_CLOUD et DBMS_CLOUD_FUNCTION pour créer un catalogue de fonctions de wrapper SQL dans la base de données d'IA autonome qui référencent et appellent leur fonction cloud respective via leurs adresses d'API. Vous allez utiliser l'API DBMS_CLOUD_FUNCTION pour gérer les fonctions à partir de votre application de base de données.

  1. Créez des informations d'identification en utilisant la procédure DBMS_CLOUD.CREATE_CREDENTIAL.

    Fournissez la clé privée d'API de l'utilisateur de 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 d'informations d'identification, empreinte de la clé, OCID de location et OCID utilisateur. Reportez-vous à 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;
/

    L'objet d'informations d'identification OCI_CRED est ainsi créé.

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

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

    Un catalogue est un ensemble de fonctions de wrapper qui référencent et appellent leurs fonctions cloud respectives via leurs adresses d'API. Indiquez l'objet d'informations d'identification, le nom du fournisseur de services cloud, dans ce cas OCI, l'ID de région OCI (PHX dans cet exemple) et l'ID de 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;
/

    L'objet de catalogue OCI_DEMO_CATALOG est ainsi créé.

    Pour plus d'informations, reportez-vous à 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 cloud de votre base de données.

  3. Vous pouvez répertorier toutes les fonctions cloud 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;
/

PL/SQL procedure successfully completed.

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, reportez-vous à Procédure LIST_FUNCTIONS.

  4. Créez la fonction de wrapper SQL. 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. SYNC_FUNCTIONS Procédure de génération de wrappers SQL à partir de l'objet de catalogue.
    • Vous pouvez créer manuellement des fonctions de wrapper individuelles à l'aide de DBMS_CLOUD_FUNCTION. CREATE_FUNCTION Procédure.
    1. SYNC_FUNCTIONS : SYNC_FUNCTIONS synchronise automatiquement (crée et/ou met à jour) 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éé.
      BEGIN
 DBMS_CLOUD_FUNCTION.SYNC_FUNCTIONS (
        catalog_name => 'OCI_DEMO_CATALOG'
 );
END;
/

      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.

      Vous pouvez vérifier les résultats de synchronisation à l'aide de la requête suivante, pour un utilisateur en cours 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, reportez-vous à Procédure SYNC_FUNCTIONS.

    2. CREATE_FUNCTION : vous pouvez créer manuellement une fonction SQL dans votre catalogue qui appelle sa fonction cloud 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;
/

      La fonction FINTECH_FUN est ainsi créée dans le catalogue OCI_DEMO_CATALOG, en tant que 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 dans OCI et fournit la sortie renvoyée par la fonction cloud.

      Remarques :

      Le nom de la fonction OCI peut être entièrement 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 gestionnaires de réponses personnalisés : la création manuelle de fonctions vous permet de créer des types de retour et des gestionnaires de réponses 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 de wrapper 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 la base de données.

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

      Une fois la fonction créée, vous pouvez la DESCRIBER 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;
/

      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.

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

    La fonction FINTECH_FUN est supprimée du catalogue OCI_DEMO_CATALOG.

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

  6. Vous pouvez supprimer un catalogue existant en utilisant la procédure DROP_CATALOG.

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

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

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

Appeler des fonctions AWS Lambda en tant que fonctions SQL

Présente les étapes permettant d'appeler des fonctions distantes AWS en tant que fonctions SQL dans votre base de données AI autonome sur une infrastructure Exadata dédiée.

Avant de procéder à ces étapes, il est supposé que vous avez créé et déployé AWS Lambda Functions dans une location AWS. Pour plus d'informations, reportez-vous à AWS Lambda.

Pour accéder aux fonctions AWS lambda, vous devez configurer les stratégies nécessaires dans Oracle Cloud Infrastructure. Pour plus d'informations, reportez-vous à Création d'une stratégie IAM pour accéder aux ressources AWS Lambda et à Utilisation de stratégies basées sur les ressources pour Lambda.

Une fois que vous aurez travaillé sur les fonctions Lambda AWS, vous utiliserez les API PL/SQL DBMS_CLOUD et DBMS_CLOUD_FUNCTION pour créer un catalogue de fonctions de wrapper SQL dans la base de données AI autonome qui référencent et appellent leur fonction cloud respective via leurs adresses d'API. Vous allez utiliser l'API DBMS_CLOUD_FUNCTION pour gérer les fonctions à partir de votre application de base de données.

  1. Créez des informations d'identification à l'aide de la procédure DBMS_CLOUD.CREATE_CREDENTIAL en utilisant la clé secrète AWS comme objet d'informations 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;
/

    L'objet d'informations d'identification AWS_CRED est ainsi créé.

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

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

    Un catalogue est un ensemble de fonctions de wrapper qui référencent et appellent leurs fonctions cloud respectives via leurs adresses d'API. Indiquez l'objet d'informations d'identification, le nom du fournisseur de services cloud, dans ce cas AWS, et l'ID de 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;
/

    L'objet de catalogue AWS_DEMO_CATALOG est ainsi créé.

    Pour plus d'informations, reportez-vous à Procédure CREATE_CATALOG. Vous pouvez interroger les vues DBA_CLOUD_FUNCTION_CATALOG et USER_CLOUD_FUNCTION_CATALOG pour extraire la liste de tous les catalogues de la 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 cloud OCI. Reportez-vous à Appel de fonctions cloud OCI en tant que fonctions SQL.

Présentation des procédures externes

Fournit un aperçu des procédures externes et de leur utilisation dans la base de données Autonomous AI sur les applications d'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. Le langage SQL et le langage PL/SQL sont les mieux adaptés pour un traitement rapide et efficace des données et des transactions dans la base. Les procédures externes peuvent compléter SQL et PL/SQL en exécutant des tâches gourmandes en calcul et en mémoire dans une machine virtuelle externe dédiée, et en renvoyant 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 de calcul existent dans le système d'exploitation Linux (et ne sont pas facilement portables vers 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 AI autonome avec des fonctions définies par l'utilisateur. Au lieu d'exécuter ces procédures dans la base de données, vous placerez le code exécutable dans une machine virtuelle OCI Linux personnalisée dédiée 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.

Remarques :

L'hôte distant pour les procédures externes doit être une machine virtuelle OCI Linux EXTPROC provisionnée à partir d'OCI Marketplace et configurée dans un réseau cloud virtuel OCI (VCN) approprié. Pour plus d'informations, reportez-vous à Configuration système dans OCI pour les procédures et scripts externes.

L'exécution à distance sur la machine virtuelle OCI Linux EXTPROC est prise en charge uniquement par Autonomous AI Database on Dedicated Exadata Infrastructure sur Oracle Public Cloud à partir de la version 19.30, et dans Oracle Database 26ai, à partir de la version 23.26.1. Cette fonctionnalité n'est pas encore prise en charge par la base de données Autonomous AI Database on Dedicated Exadata Infrastructure sur Exadata Cloud@Customer (ExaCC).

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

Affiche les étapes de provisionnement de la machine virtuelle EXTPROC, ainsi que 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 cloud virtuel OCI provisionné dans un compartiment OCI de la location OCI.
  • Base de données Autonomous AI, créée en tant qu'instance sous une base de données Conteneur Autonomous provisionnée à partir d'un cluster de machines virtuelles Exadata Autonomous créé sur l'infrastructure Exadata sur Oracle Public Cloud.
  • Machine virtuelle EXTPROC provisionnée dans le cadre d'une pile EXTPROC à partir d'OCI Marketplace.

Il est recommandé de placer le cluster AVM dans un sous-réseau privé dans 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'IA 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é. Le VCN peut éventuellement être configuré avec une passerelle NAT si les applications Autonomous AI Database et les autres ressources du sous-réseau privé ont besoin d'un accès sortant à Internet.

Suivez ces étapes minimales de configuration OCI Networking lorsque vous introduisez la machine virtuelle ExtProc dans cette topologie.

  • Vous devez pouvoir vous connecter à votre machine virtuelle ExtProc pour créer la bibliothèque partagée (dot-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.
  • La pratique habituelle 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).

    Remarques :

    La machine virtuelle EXTPROC ne doit PAS se trouver dans un sous-réseau dont la plage de 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 Autonomous AI.

  • Vous devez définir une règle entrante dans la liste de sécurité du VCN pour autoriser l'accès par connexion SSH à la machine virtuelle via le port 22. Vous devez également définir une règle sortante dans la liste de sécurité du VCN pour permettre à ADBD d'accéder au port de destination 16000 pour être spécifique, ou à tous les ports de destination, en général. Reportez-vous à Accès et sécurité à OCI Networking.
  • Dans le cadre du provisionnement de la pile de machines virtuelles EXTPROC, vous fournirez toutes les adresses IP client d'AVMC. Vous obtiendrez ces adresses IP client IPv4 à partir du tableau de bord OCI pour le cluster AVM.
  • Par la suite, l'outil de provisionnement créera automatiquement un groupe de sécurité réseau nommé nsg_acl. Ce groupe de sécurité réseau dispose d'une règle entrante autorisant les adresses IP client dédiées Autonomous Database en tant que seules sources pouvant accéder à la destination du port 16000.

Rubriques avancées

  • Si les sous-réseaux hébergeant la machine virtuelle ExtProc et la base de données Autonomous AI se trouvent dans le même VCN, vous n'avez pas besoin d'indiquer 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 ADBD se trouvent dans des réseaux cloud virtuels différents, vous devez implémenter l'appairage VCN. Reportez-vous à Appairage VCN.
  • Si vous choisissez de configurer la machine virtuelle ExtProc pour qu'elle se trouve dans un sous-réseau privé, vous devez pouvoir vous connecter à la machine virtuelle via un bastion/serveur de vidage et activer l'entrée uniquement dans la machine virtuelle ExtProc, ainsi que sécuriser l'accès aux autres ressources du sous-réseau privé, telles que la base de données AI autonome. Pour plus de détails, reportez-vous aux guides de mise en réseau OCI.

Implémenter des fonctions définies par l'utilisateur avec des procédures externes

  1. Provisionner et configurer la machine virtuelle EXTPROC à partir d'OCI MarketPlace

    1. Connectez-vous à la console OCI à l'adresse http://cloud.oracle.com. Reportez-vous à Connexion à la console Oracle Cloud Infrastructure pour plus d'informations.
    2. Dans le menu de navigation de gauche d'Oracle Cloud Infrastructure, sélectionnez Marketplace, puis, sous Marketplace, cliquez sur Toutes les applications.
    3. Entrez "EXTPROC" dans la barre de recherche, puis cliquez sur Rechercher. Vous verrez deux widgets : un libellé Pile et un autre libellé Image.
    4. Choisissez le widget nommé Stack (important). Vous accédez à la page de détails de l'agent Oracle Autonomous Database EXTPROC, avec la version de pile, la date de publication et les notes de version relatives à la pile. Sur cette page, cliquez sur le bouton Lancer la pile. Vous accédez alors à la page Launch Stack suivante.

    5. Dans la page Launch Stack :

      • Dans la liste déroulante Version, choisissez la version de package de la pile.
      • Dans la liste déroulante Compartiment, sélectionnez le nom du compartiment dans lequel provisionner la machine virtuelle EXTPROC. A moins que vous n'ayez des raisons spécifiques de ne pas le faire, choisissez le même compartiment que celui du moniteur ADBD (il est recommandé d'éviter le compartiment racine d'une ressource). Reportez-vous à la section Configuration système pour les procédures et scripts externes pour choisir le compartiment approprié.
      • Acceptez les conditions générales, puis cliquez sur Lancer la pile.

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

    6. Sur cette page, indiquez un nom, une description, un nom de compartiment, la version de Terraform et toute information de balise. Le nom du compartiment est obligatoire et, surtout, il est nécessaire d'entrer dans l'assistant sur cette page. Cliquez ensuite sur Suivant.
    7. 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 Bibliothèques externes, fournissez la liste des bibliothèques, séparées par une virgule (,), que vous voulez autoriser à appeler à partir de votre base de données Autonomous AI 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 VM elle-même (pour correspondre à l'architecture et à l'environnement).

        Remarques :

        Etant donné que vous êtes toujours en train de créer 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++, vous devez vous rappeler 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 de portefeuille, indiquez le mot de passe du 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 Autonomous AI sur une infrastructure dédiée et la machine virtuelle d'agent EXTPROC.
    8. La deuxième partie de la page des variables de configuration implique la configuration réseau pour la machine virtuelle EXTPROC.
      • Pour Compartiment, choisissez 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 si elles se trouvent dans des sous-réseaux différents (privés et publics).
      • Pour Stratégie réseau, choisissez "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 un VCN, AVMC et une base de données d'IA autonome.

        Remarques :

        L'autre choix consiste à créer un VCN et un sous-réseau avec sa propre stratégie de configuration pour l'agent de machine virtuelle EXTPROC. Comme indiqué dans la configuration système pour les procédures et scripts externes, si vous choisissez de placer la machine virtuelle EXTPROC dans un VCN différent de celui de la base de données Autonomous AI, vous devez homologue les réseaux cloud virtuels.
      • Ignorez l'entrée suivante pour le type d'accès d'agent EXTPROC. Ce champ n'est pas applicable à la base de données AI autonome sur une infrastructure Exadata dédiée.
    9. Ensuite, dans le champ intitulé "Adresses IP d'adresse privée", entrez TOUTES les adresses IP client de l'AVMC sur lequel la base de données est configurée. Vous pouvez obtenir ces adresses IP client à partir du tableau de bord de la console OCI pour AVMC.
    10. Fournissez ensuite les détails du VCN et du sous-réseau.

      Remarques :

      La machine virtuelle EXTPROC ne doit PAS se trouver dans un sous-réseau dont la plage de 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 Autonomous AI.
    11. La dernière partie de la page de configuration implique la configuration du calcul pour l'agent de machine virtuelle EXTPROC.
      • Pour Compartiment, choisissez le nom du compartiment dans le menu déroulant. Il est recommandé de colocaliser la machine virtuelle dans le même compartiment que celui de la base de données Autonomous AI sur une infrastructure dédiée, le VCN et le sous-réseau afin de 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 globale de vos procédures externes.
      • Pour Ajouter des clés SSH, générez les fichiers de clés publique et privée 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 cryptage RSA) :
        ssh-keygen -t ed25519 -C "your_email@example.com" (OR)
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

        Cela générera un fichier de clés privées ssh-key-<date-time-id>.key et un fichier de clés publiques ssh-key-<date-time-id>.key.pub. Copiez-collez le contenu de la clé publique SSH dans la fenêtre ou faites glisser le fichier .pub dans la fenêtre.

      • Cliquez sur Suivant.

    12. Vous accédez alors à la page Review. Vérifiez toutes les entrées, 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 le travail ORM terminé, la machine virtuelle EXTPROC est créée et exécutée.

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

    Vous devez fournir des informations sur le système de machine virtuelle EXTPROC en tant qu'entrées aux API DBMS_CLOUD_FUNCTION dans la base de données Autonomous AI pour permettre l'appel de procédures externes à partir de la base de données.

    1. Dans le menu de navigation de gauche d'Oracle Cloud Infrastructure, sélectionnez Compute, choisissez le compartiment indiqué pour le provisionnement de machine virtuelle EXTPROC et consultez le tableau de bord répertoriant toutes les machines virtuelles du compartiment. Le travail ORM aura créé la machine virtuelle EXTPROC avec un nom canonique EXTPROC-agent ou EXTPROC-agent-<setofnumbers>. Il s'agit du nom d'hôte de votre instance de machine virtuelle EXTPROC. Si vous cliquez sur cette entrée, vous accédez à la page qui affiche les détails du système : les adresses publiques et privées IPV4 (IPv4 et IPv6), le sous-réseau et les détails de l'image.
    2. 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 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 processus d'écoute Oracle SQL*Net. Dans le conteneur, un environnement client Oracle avec les fichiers de configuration nécessaires tels que sqlnet.ora et listener.ora sera disponible, ainsi qu'un fichier de portefeuille pour une communication sécurisée avec la base de données AI autonome.

    3. 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 distantes de l'application SQL et PL/SQL sur Autonomous AI Database, et il est le moteur d'exécution d'exécution de la procédure externe.
      • A partir du système d'exploitation Linux, nom de domaine qualifié complet (FQDN) de l'hôte de machine virtuelle EXTPROC.
      • A partir du conteneur Podman, à partir du statut du processus d'écoute, du port sur la machine virtuelle EXTPROC sur laquelle la base de données se connecte à la machine virtuelle.
      • A partir du conteneur Podman, à partir de la spécification sqlnet.ora, l'emplacement du fichier de portefeuille.
      • A partir d'une inspection du fichier de portefeuille à l'aide de l'outil orapki, la valeur du paramètre Nom distinctif (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 qualifié complet + 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 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 (DN) du certificat sera l'entrée du paramètre library_ssl_server_cert_dn : 'CN=extproc-agent-170798'.
  3. Construire la bibliothèque C et la placer à 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 indiqué dans le système de fichiers de la machine virtuelle d'agent ExtProc.

    Le nom de la bibliothèque doit correspondre exactement aux noms que vous avez fournis lors de la création de la pile ExtProc. Au cas où vous l'auriez égaré, vous pouvez le trouver dans l'entrée EXTPROC_DLLS du fichier initextproccontainer.ora de conteneur ExtProc comme indiqué ci-dessous, ou dans la section "Variables" du travail 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 sur la machine virtuelle d'agent EXTPROC.
    • Le chemin d'accès complet au 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 dont nous avons besoin pour créer l'objet Catalogue/Bibliothèque dans l'application de base de données sont alors terminées.

  4. Téléchargement du fichier de portefeuille de la machine virtuelle ExtProc vers OCI Object Storage

    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 AI autonome et l'agent EXTPROC se connectent à l'aide de Mutual Transport Layer Security (mTLS). Lorsque le protocole mTLS (Mutual Transport Layer Security) est utilisé, les clients se connectent via une connexion de base de données TCP (Secure TCP) à l'aide du Protocole TLS 1.2 standard avec un certificat d'autorité de certificat client sécurisé.

    Remarques :

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

    Vous devez au préalable exporter le portefeuille du répertoire /u01/app/oracle/extproc_wallet sur la machine virtuelle où EXTPROC s'exécute vers OCI Object Storage.

    Remarques :

    • 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 Object Storage 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

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

    Importez ensuite le portefeuille, cwallet.sso, contenant les certificats de l'instance d'agent EXTPROC à partir d'Object Storage dans un répertoire de votre base de données Autonomous AI.

    Créez des informations d'identification pour accéder à Object Storage où vous avez stocké le fichier de portefeuille cwallet.sso. Pour plus d'informations sur les paramètres de nom utilisateur et de mot de passe des différents services Object Storage, reportez-vous à Procédure CREATE_CREDENTIAL.

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

    SQL> SET DEFINE OFF

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

SQL> CREATE DIRECTORY extprocwalletdir AS 'extprocwalletdir';

Directory created.

SQL> 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

SQL> 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 de bibliothèque 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.

    SQL> 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.

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

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

    Créez la fonction SQL mise en correspondance avec la fonction ExtProc C. Voir le nom de la fonction C du programme écrit ci-dessus.

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

Function created.

SQL>

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

    SQL> SELECT HELLOCEXTPROC() FROM dual;

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