Appeler des procédures externes en tant que fonctions SQL

Les procédures externes sont des fonctions écrites dans un langage de troisième génération et pouvant être appelées à partir de code PL/SQL ou SQL comme s'il s'agissait d'une routine ou d'une fonction PL/SQL.

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.

Définissez la procédure C en utilisant l'un de ces prototypes.

Créez une bibliothèque d'objets partagés (fichier .so). La bibliothèque d'objets partagés contient la procédure C (procédure externe) qui a été définie à l'étape précédente.

gcc -I/u01/app/oracle/extproc_libs/ -shared -fPIC -o extproc.so UpdateSalary.c

Présente les étapes d'obtention de l'application de pile EXTPROC 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 Oracle Cloud Infrastructure, cliquez sur Marketplace, puis, sous Marketplace, cliquez sur Toutes les applications. Vous accédez ainsi au tableau de bord Toutes les applications Marketplace.
3. Entrez EXTPROC dans le champ de recherche et cliquez sur Rechercher.
4. Cliquez sur le widget EXTPROC de type : pile.
   
   

   
   Description de l'illustration adbs_extproc_application.png

   
   

Lancez l'application de pile EXTPROC à partir de la page Détails de l'application EXTPROC.

1. Sur la page Agent EXTPROC d'Oracle Autonomous Database, sous Type de pile, effectuez les opérations suivantes :

   • Dans la liste déroulante Version, sélectionnez la version de package de la pile. Par défaut, le menu affiche la dernière version.

   • Dans la liste déroulante Compartiment, sélectionnez le nom du compartiment dans lequel vous voulez lancer l'instance.

     Remarque
     
     Si vous ne disposez pas des droits nécessaires pour lancer l'instance dans le compartiment sélectionné, elle est lancée dans le compartiment racine.

   • Cochez la case J'ai pris connaissance des Conditions standard Oracle et des restrictions et je vous les accepte.

2. Cliquez sur Lancer la pile.
   
   

   
   Description de l'illustration adb_launch_stack.png

   
   

Présente les étapes de création de pile pour l'instance EXTPROC.

1. Sur la page Informations sur la pile, vérifiez et modifiez les informations suivantes si nécessaire :

   • Informations sur la pile

   • Fournisseurs personnalisés

   • Nom (facultatif) : vous pouvez modifier le nom de pile par défaut. Evitez de saisir des informations confidentielles.

   • Description (facultatif) : vous pouvez modifier la description de pile par défaut. Evitez de saisir des informations confidentielles.

   • Créer dans le compartiment

   • Version de Terraform

   • Balises : indiquez les éléments suivants pour affecter des balises à la pile.

     • Espace de noms de balise : pour ajouter une balise définie, sélectionnez un espace de noms existant. Pour ajouter une balise free-from, laissez la valeur vide.

     • Clé de balise : pour ajouter une balise définie, sélectionnez une clé de balise existante. Pour ajouter une balise à format libre, saisissez le nom de clé souhaité.

     • Valeur de balise : saisissez la valeur de balise souhaitée.

     Ajouter une balise : cliquez sur cette option pour ajouter une autre balise.

     Pour plus d'informations sur le balisage, reportez-vous à Balises de ressources.

   
   

   
   Description de l'illustration adbs_extproc_createstack_updated.png

   
   
2. Cliquez sur Suivant.
   Vous accédez ainsi à la page Configurer des variables, qui vous permet de configurer des variables pour les ressources d'infrastructure que la pile crée lorsque vous exécutez le travail d'application pour ce plan d'exécution.
3. Sur la page Configurer les variables, entrez les informations dans les zones Configurer l'agent EXTPROC, Configuration réseau et Configuration de calcul.
   1. Fournissez des informations dans la zone Configurer l'agent EXTPROC.

      • Bibliothèques externes : indiquez 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. Par exemple, extproc.so, extproc1.so.

        Une fois la pile créée, vous devez copier les bibliothèques dans le répertoire /u01/app/oracle/extproc_libs sur la machine virtuelle d'agent EXTPROC.

      • Mot de passe de portefeuille : indiquez le mot de passe de portefeuille.

        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 et la machine virtuelle d'agent EXTPROC. Le portefeuille est créé dans le répertoire /u01/app/oracle/extproc_wallet.

        Remarque
        
        Une fois le portefeuille créé, le mot de passe du portefeuille ne peut pas être modifié.

      
      

      
      Description de l'illustration adbs_configure_var_extproc_agent.png

      
      
   2. Fournissez des informations dans la zone Configuration réseau.

      • Compartiment : dans la liste déroulante, choisissez le compartiment dans lequel placer la configuration.

      • Stratégie réseau : choisissez l'une des options de la liste déroulante, Créer un VCN et un sous-réseau ou Utiliser un VCN et un sous-réseau existants.

        • Créer un VCN et un sous-réseau : choisissez cette option si aucune adresse privée n'est configurée pour votre base de données Autonomous AI. Cela crée un VCN avec un sous-réseau public et privé préconfiguré avec des règles de sécurité.

          Si vous sélectionnez cette option, la page affiche également la liste déroulante Configuration Strategy :

          Choisissez Utiliser la configuration recommandée dans la liste déroulante Stratégie de configuration.

          
          

          
          Description de l'illustration adb_extproc_network_config.png

          
          

        • Utiliser le VCN et le sous-réseau existants : sélectionnez cette option pour créer l'agent EXTPROC à l'aide d'un VCN existant. L'instance d'agent EXTPROC est ainsi créée dans le sous-réseau fourni.

          Lorsque vous sélectionnez cette option, fournissez les informations suivantes pour le VCN et le sous-réseau existants :

          • Sous Réseau cloud virtuel, procédez comme suit :

            Dans la liste déroulante VCN existant, choisissez un VCN existant. Si le VCN spécifié n'existe pas, un nouveau VCN est créé.

          • Sous Sous-réseau EXTPROC :

            Dans la liste déroulante Sous-réseau existant, choisissez un sous-réseau existant.

            Lorsque vous choisissez d'utiliser un VCN et un sous-réseau existants, ajoutez une règle entrante pour le port 16000 de l'instance d'agent EXTPROC. Vous ajoutez également une règle sortante sur le sous-réseau public.

            Pour plus d'informations, reportez-vous à Configuration de l'accès réseau avec des adresses privées.

          
          

          
          Description de l'illustration adbs_extproc_network_configuration_existing_vcn.png

          
          

      • Type d'accès à l'agent EXTPROC : choisissez l'une des options suivantes dans la liste déroulante.

        • Accès sécurisé à partir de bases de données d'adresse privée ADB-S spécifiques dans votre VCN : choisissez cette option pour autoriser uniquement les adresses IP d'adresse privée spécifiées dans votre réseau cloud virtuel (VCN) à se connecter à votre agent EXTPROC.

          Lorsque cette option est sélectionnée, vous indiquez la liste des adresses IP d'adresse privée autorisées à l'étape suivante.

        • Accès sécurisé à partir de toutes les bases de données d'adresse privée ADB-S dans votre VCN : choisissez cette option pour autoriser toute adresse privée dans votre réseau cloud virtuel (VCN) à se connecter à votre agent EXTPROC.

      • Adresses IP d'adresse privée

        Fournissez la liste des adresses IP d'adresse privée séparées par une virgule (,) pour la variable Adresses IP d'adresse privée. Par exemple, 10.0.0.0, 10.0.0.1.

        Remarque
        
        Ce champ s'affiche uniquement lorsque vous sélectionnez Accès sécurisé à partir de bases de données d'adresse privée ADB-S spécifiques dans votre VCN pour le type d'accès d'agent EXTPROC.
   3. Fournissez les informations de configuration Compute.

      • Compartiment : sélectionnez le compartiment de création de la pile.

      • Forme : sélectionnez une forme en fonction des exigences de charge globale de l'instance d'agent EXTPROC. La forme détermine les ressources allouées à l'instance d'agent EXTPROC.

      • Nombre d'OCPU : choisissez le nombre d'OCPU à allouer à l'instance d'agent EXTPROC.

      • Taille de mémoire (Go) : choisissez la quantité de mémoire en gigaoctets (Go) à allouer à l'instance d'agent EXTPROC.

      • Ajouter des clés SSH : téléchargez une clé publique SSH ou collez-la. Sélectionnez l'une des options suivantes :

        • Choisir un fichier de clés SSH : téléchargez la partie de clé publique de votre paire. Accédez au fichier de clés à télécharger ou glissez-déplacez-le dans la zone.

        • Coller la clé SSH : collez la partie de la clé publique de la paire dans la zone.

      
      

      
      Description de l'illustration adbs_extproc_compute_config.png

      
      
4. Cliquez sur Suivant.

   Vous accédez alors à la page Vérifier.

5. Sur la page Vérifier, procédez comme suit :
   1. Vérifiez les variables de configuration.
   2. Cochez la case Exécuter l'application sous Exécuter l'application sur la pile créée ?
   3. Cliquez sur Créer.
   Remarque
   
   Cette zone n'affiche pas les variables qui ont des valeurs ou des variables par défaut que vous n'avez pas modifiées.

   
   

   
   Description de l'illustration adbs_extproc_review.png

   
   

   Resource Manager exécute le travail d'application pour créer les ressources d'empilement en conséquence. Vous accédez à la page Détails du travail et l'état du travail est Accepté. Lorsque le travail d'application des modifications démarre, le statut passe à En cours.

   
   

   
   Description de l'illustration adbs_extproc_job_details.png

   
   

   Remarque
   
   Les informations nécessaires pour vous connecter à l'instance créée dans le cadre de la pile sont disponibles dans l'onglet Informations sur l'application.

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

1. Importez le portefeuille, cwallet.sso, contenant les certificats de l'instance d'agent EXTPROC à partir d'Object Storage dans votre base de données Autonomous AI. Pour le fichier de portefeuille, tenez compte des points suivants :

   • Le fichier de portefeuille, ainsi que l'ID utilisateur et le mot de passe de 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.

2. Créez des informations d'identification pour accéder à Object Storage dans lequel stocker 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.
   La création d'informations d'identification pour accéder à la banque d'objets Oracle Cloud Infrastructure n'est pas requise si vous activez les informations d'identification de principal de ressource. Pour plus d'informations, reportez-vous à A propos de l'utilisation du principal de ressource pour accéder à des ressources Oracle Cloud Infrastructure.
3. Créez un répertoire sur Autonomous Database pour le fichier de portefeuille cwallet.sso.

   CREATE DIRECTORY wallet_dir AS 'directory_location';

   Pour plus d'informations sur la création de répertoires, reportez-vous à Créer un répertoire dans la base de données Autonomous AI.

4. Utilisez DBMS_CLOUD.GET_OBJECT pour télécharger vers le serveur le portefeuille. Par exemple :

   BEGIN
     DBMS_CLOUD.GET_OBJECT (
       credential_name     => 'DEF_CRED_NAME',
       object_uri          => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/cwallet.sso',
       directory_name      => 'WALLET_DIR'
   );
   END;
   /

   Dans cet exemple, namespace-string est l'espace de noms d'objet Oracle Cloud Infrastructure Object Storage et bucketname est le nom du bucket. Pour plus d'informations, reportez-vous à Espaces de nom Object Storage.

   Le portefeuille est copié dans le répertoire créé à l'étape précédente, WALLET_DIR. Le portefeuille qui vous permet de vous connecter à l'instance d'agent EXTPROC est désormais disponible sur votre instance Autonomous Database.

Affiche les étapes permettant d'appeler une procédure externe en tant que fonction SQL.

1. Créez une bibliothèque.

   Une procédure externe est une routine de langage C stockée dans une bibliothèque. Pour appeler des procédures externes avec Autonomous AI Database, vous créez une bibliothèque.

   Exécutez DBMS_CLOUD_FUNCTION.CREATE_CATALOG pour créer une bibliothèque. Par exemple :

   BEGIN
       DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
           library_name               => 'demolib',
           library_listener_url       => 'remote_extproc_hostname:16000',
           library_wallet_dir_name    => 'wallet_dir',
           library_ssl_server_cert_dn => 'CN=VM Hostname',
           library_remote_path        => '/u01/app/oracle/extproc_libs/library name'
   );
   END;
   /
   

   Cette opération crée la bibliothèque demolib dans votre base de données Autonomous AI et inscrit la bibliothèque de liens dynamiques dans votre base de données. L'instance d'agent EXTPROC est préconfigurée pour héberger les procédures externes sur le port 16000.

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

   Interrogez les vues DBA_CLOUD_FUNCTION_CATALOG View et USER_CLOUD_FUNCTION_CATALOG View pour extraire la liste de tous les catalogues et bibliothèques de votre base de données.

   Interrogez la vue USER_CLOUD_FUNCTION_ERRORS View pour répertorier les erreurs générées lors de la validation de la connexion à l'emplacement de la bibliothèque distante.

2. Créez la fonction.

   Par exemple :

   CREATE OR REPLACE FUNCTION ftest(
         x VARCHAR2, 
         y VARCHAR2) 
   RETURN VARCHAR2 AS LANGUAGE C
         LIBRARY test
         NAME "demolib"
         PARAMETERS(
             x STRING, 
             y STRING);
   /

3. Vous pouvez supprimer une bibliothèque existante en utilisant la procédure DROP_CATALOG. Par exemple :

   BEGIN
       DBMS_CLOUD_FUNCTION.DROP_CATALOG (
         LIBRARY_NAME  => 'demolib'
     );
   END;
   /
   

   Cette opération supprime la bibliothèque DEMOLIB.

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