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 d'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 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.

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 Autonomous AI 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 que vous avez des fonctions OCI fonctionnelles, vous utiliserez les API PL/SQL DBMS_CLOUD et DBMS_CLOUD_FUNCTION pour créer un catalogue de fonctions wrapper SQL dans la base de données Autonomous AI 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.

Créez des informations d'identification à l'aide de 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.

Créez un objet Catalogue à 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 les vues DBA_CLOUD_FUNCTION_CATALOG et USER_CLOUD_FUNCTION_CATALOG pour extraire la liste de tous les catalogues de fonctions cloud de votre base de données.

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

 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 à la section LIST_FUNCTIONS Procedure.

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 permettant de générer des wrappers SQL à partir de l'objet de catalogue.
Vous pouvez créer manuellement des fonctions de wrapper individuelles à l'aide de DBMS_CLOUD_FUNCTION. Procédure CREATE_FUNCTION.

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

Remarque : 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 entrée du paramètre function_id est pris en compte pour créer cette référence.

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

Vous pouvez supprimer une fonction existante en utilisant 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.
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

Affiche les étapes permettant d'appeler des fonctions distantes AWS en tant que fonctions SQL dans votre base de données Autonomous AI 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 wrapper SQL dans la base de données Autonomous AI 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.

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.
Créez un objet Catalogue à 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 votre base de données.

Les autres étapes/opérations (procédure LIST_FUNCTIONS, procédure SYNC_FUNCTIONS, procédure CREATE_FUNCTION, procédure DROP_FUNCTION et 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 Autonomous AI 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.

Remarque : 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é.

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 d'IA autonome, 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 de base de données Autonomous AI et les autres ressources du sous-réseau privé ont besoin d'un accès sortant à Internet.

Suivez ces étapes minimales de configuration de la mise en réseau OCI 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).

Remarque : la machine virtuelle EXTPROC ne doit PAS se trouver dans un sous-réseau dont la plage 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 fournissez 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ée automatiquement un groupe de sécurité réseau (NSG) 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 de sorte qu'elle se trouve dans un sous-réseau privé, vous devez pouvoir vous connecter à la machine virtuelle via un bastion/serveur de vidage, activer l'entrée 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 Autonomous AI. 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

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

a. Connectez-vous à la console OCI à l'adresse http://cloud.oracle.com. Reportez-vous à Connexion à la console Oracle Cloud Infrastructure pour plus d'informations.

b. Dans le menu de navigation de gauche d'Oracle Cloud Infrastructure, sélectionnez 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 libellé Pile et un autre libellé Image.

d. Choisissez le widget nommé Stack (important). Vous accédez à la page de détails de l'agent Oracle Autonomous Database EXTPROC, qui fournit 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.

e. 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).
- Acceptez les conditions générales et cliquez sur Lancer la pile.
Vous accédez alors à la page suivante : l'assistant Create Stack.

f. 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. Fournissez les informations relatives au jeu de transport, puis cliquez sur Suivant.

g. 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).
  
  Remarque : étant 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 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 Autonomous AI sur une infrastructure dédiée et la machine virtuelle d'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, 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 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 une base de données VCN, AVMC et Autonomous AI.
  
  Remarque : 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. 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 pour la base de données Autonomous AI sur une infrastructure Exadata dédiée.
i. 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.
- Pour Réseau cloud virtuel, indiquez le nom du VCN dans lequel créer l'agent de machine virtuelle EXTPROC.
- Pour Sous-réseau EXTPROC, indiquez le nom du sous-réseau dans lequel créer l'agent de machine virtuelle EXTPROC.
j. Fournissez ensuite les détails du VCN et du sous-réseau.

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

k. 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 systèmes plus anciens prennent en charge l'algorithme de chiffrement RSA) :
```
ssh-keygen -t ed25519 -C "your_email@example.com" (OR)
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
```
  Ceci 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.
- Fournissez les informations relatives au jeu de transport, puis cliquez sur Suivant.
l. 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.

Cette opération lance OCI Resource Manager 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.
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.

a. 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. 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 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, listener.ora sera disponible, ainsi qu'un fichier de portefeuille pour une communication sécurisée avec la base de données Autonomous AI.

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 distantes de l'application SQL et PL/SQL sur la base de données Autonomous AI. Il est également le moteur 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'.

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 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 mal placé, vous pouvez le trouver dans l'entrée EXTPROC_DLLS du fichier initextproccontainer.ora du 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 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 dont nous avons besoin pour créer l'objet Catalogue/Bibliothèque dans l'application de base de données sont alors terminées.

Télécharger le 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 Autonomous AI 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é.

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

Vous devez au préalable exporter le portefeuille à partir du répertoire /u01/app/oracle/extproc_wallet sur la machine virtuelle où EXTPROC est exécuté vers OCI Object Storage.
Remarque :
- 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.

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 nécessaires 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 de stockage d'objets, reportez-vous à Procédure CREATE_CREDENTIAL.

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

Créez ensuite 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.

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

Package DBMS_CLOUD_FUNCTION