Utilisation de la messagerie persistante avec les messages stockés dans la banque d'objets cloud

Messages persistants dans DBMS_PIPE :

• Permet d'envoyer et d'extraire des messages très volumineux.

• Prise en charge de l'envoi d'un grand nombre de messages de canal.

• Prise en charge de l'envoi et de la réception de messages au sein d'une seule base de données, dans plusieurs bases de données et entre différentes bases de données dans différentes régions.

• Prise en charge de plusieurs canaux à l'aide du même URI d'emplacement de banque d'objets cloud.

Les canaux de messagerie persistants peuvent être créés dans n'importe quel type DBMS_PIPE pris en charge :

• Tuyau implicite : créé automatiquement lorsqu'un message est envoyé avec un nom de tuyau inconnu à l'aide de la fonction DBMS_PIPE.SEND_MESSAGE.
• Tuyau explicite : créé à l'aide de la fonction DBMS_PIPE.CREATE_PIPE avec un nom de tuyau spécifié par l'utilisateur.
• Public Pipe : accessible par tout utilisateur disposant du droit d'accès EXECUTE sur le package DBMS_PIPE.
• Tuyau privé : accessible par les sessions avec le même utilisateur que le créateur de pipe.

L'exemple suivant présente le workflow général pour DBMS_PIPE avec messagerie persistante :

Les applications existantes utilisant DBMS_PIPE peuvent continuer à fonctionner avec un minimum de modifications. Vous pouvez configurer des applications existantes qui utilisent DBMS_PIPE avec un objet d'informations d'identification et un URI d'emplacement à l'aide d'un déclencheur de connexion ou d'une autre routine d'initialisation. Après avoir défini les informations d'identification et l'URI d'emplacement DBMS_PIPE, aucune autre modification n'est nécessaire pour utiliser la messagerie persistante. Toute utilisation ultérieure du canal stocke les messages dans la banque d'objets cloud au lieu de les stocker dans la mémoire de base de données. Vous pouvez ainsi modifier la méthode de stockage des messages du stockage en mémoire vers le stockage d'objets cloud persistant, avec un minimum de modifications.

Décrit les étapes de création d'un canal persistant avec un nom de canal spécifié (tuyau explicite).

1. Stockez les informations d'identification de la banque d'objets à l'aide de la procédure DBMS_CLOUD.CREATE_CREDENTIAL. Par exemple :

   BEGIN
     DBMS_CLOUD.CREATE_CREDENTIAL(
       credential_name => 'my_persistent_pipe_cred',
       username => 'adb_user@example.com',
       password => 'password'
     );
   END;
   /

   Cette opération stocke les informations d'identification dans la base de données dans un format crypté. Vous pouvez utiliser n'importe quel nom d'informations d'identification. Cette étape est requise une seule fois, sauf si les informations d'identification de banque d'objets changent. Après avoir stocké les informations d'identification, vous pouvez utiliser le même nom d'informations d'identification pour accéder à la banque d'objets cloud afin d'envoyer et de recevoir des messages avec DBMS_PIPE.

   Pour obtenir des informations détaillées sur les paramètres, reportez-vous à la procédure CREATE_CREDENTIAL. Pour Oracle Cloud Infrastructure Object Storage, il est obligatoire que les informations d'identification utilisent l'authentification Oracle Cloud Infrastructure native.

   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 à Utilisation du principal de ressource pour accéder à des ressources Oracle Cloud Infrastructure.

   Remarque
   
   Certains outils tels que SQL*Plus et SQL Developer utilisent le caractère esperluette (&) comme caractère spécial. Si votre mot de passe contient l'esperluette, utilisez la commande SET DEFINE OFF dans ces outils, comme indiqué dans l'exemple, pour désactiver le caractère spécial et obtenir les informations d'identification créées correctement.
2. Créez un canal explicite pour envoyer et extraire des messages. Par exemple, créez un canal nommé ORDER_PIPE.

   DECLARE
     r_status INTEGER;
   BEGIN
       r_status := DBMS_PIPE.CREATE_PIPE(pipename => 'ORDER_PIPE');
   END;
   /

   Pour plus d'informations, reportez-vous à Fonction CREATE_PIPE.

3. Vérifiez que le pipe est créé.

   SELECT ownerid, name, type FROM v$db_pipes 
          WHERE name = 'ORDER_PIPE';

   OWNERID NAME       TYPE    
   ------- ---------- ------- 
        80 ORDER_PIPE PRIVATE 

4. Utilisez les procédures DBMS_PIPE pour définir les informations d'identification d'accès et l'URI d'emplacement par défaut afin de stocker les messages persistants dans la banque d'objets cloud.

   BEGIN
       DBMS_PIPE.SET_CREDENTIAL_NAME('my_persistent_pipe_cred');
       DBMS_PIPE.SET_LOCATION_URI('https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/'); 
   END;
   /

   Ces procédures définissent le nom des informations d'identification par défaut et l'URI d'emplacement par défaut à utiliser avec les procédures DBMS_PIPE.

   Si vous utilisez Oracle Cloud Infrastructure Object Storage pour stocker des messages, vous pouvez utiliser des URI natifs Oracle Cloud Infrastructure ou des URI Swift. Cependant, l'URI d'emplacement et les informations d'identification doivent correspondre au type suivant :

   • Si vous utilisez un format d'URI natif pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser l'authentification des clés de signature Oracle Cloud Infrastructure natives dans l'objet d'informations d'identification.

   • Si vous utilisez le format d'URI Swift pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser une authentification par jeton d'authentification dans l'objet d'informations d'identification.

   Pour plus d'informations, reportez-vous à Procédure SET_CREDENTIAL_NAME et à Procédure SET_LOCATION_URI.

5. Emballer et envoyer un message sur le canal.

   DECLARE
     l_result INTEGER;
     l_date   DATE;
   BEGIN
       l_date := sysdate;
       DBMS_PIPE.PACK_MESSAGE(l_date);         -- date of order
       DBMS_PIPE.PACK_MESSAGE('C123');         -- order number
       DBMS_PIPE.PACK_MESSAGE(5);              -- number of items in order
       DBMS_PIPE.PACK_MESSAGE('Printers');     -- type of item in order
   
    
       l_result := DBMS_PIPE.SEND_MESSAGE(
                       pipename => 'ORDER_PIPE',
                       credential_name => DBMS_PIPE.GET_CREDENTIAL_NAME,
                       location_uri => DBMS_PIPE.GET_LOCATION_URI);
        
       IF l_result = 0 THEN
           DBMS_OUTPUT.put_line('DBMS_PIPE sent order successfully');
       END IF;
    
   END;
   /

   Pour plus d'informations, reportez-vous aux sections PACK_MESSAGE Procedures et SEND_MESSAGE Function.

Décrit les étapes permettant d'extraire un message persistant à partir d'un canal explicite sur la même instance Autonomous Database (instance où le message a été envoyé).

1. Vérifiez que le pipe est créé.

   SELECT ownerid, name, type FROM v$db_pipes 
          WHERE name = 'ORDER_PIPE';
   

   OWNERID NAME       TYPE    
   ------- ---------- ------- 
        80 ORDER_PIPE PRIVATE 

   Lorsque vous êtes sur la même instance Autonomous Database et que le canal existe, vous n'avez pas besoin d'exécuter DBMS_PIPE.CREATE_PIPE avant de recevoir un message. Cela s'applique lorsque le canal a été créé sur la même instance, comme indiqué dans Création d'un canal persistant explicite et envoi d'un message.

2. Recevez un message du pipe.

   DECLARE
       message1  DATE;
       message2  VARCHAR2(100);
       message3  INTEGER;
       message4  VARCHAR2(100);
       l_result  INTEGER;
   
   BEGIN
   
       DBMS_PIPE.SET_CREDENTIAL_NAME('my_persistent_pipe_cred');
       DBMS_PIPE.SET_LOCATION_URI('https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/'); 
       l_result := DBMS_PIPE.RECEIVE_MESSAGE (
                     pipename => 'ORDER_PIPE',
                     timeout  => DBMS_PIPE.MAXWAIT,
                     credential_name => DBMS_PIPE.GET_CREDENTIAL_NAME,
                     location_uri => DBMS_PIPE.GET_LOCATION_URI);
    
       IF l_result = 0 THEN
           DBMS_PIPE.unpack_message(message1);
           DBMS_PIPE.unpack_message(message2);
           DBMS_PIPE.unpack_message(message3);
           DBMS_PIPE.unpack_message(message4);
    
           DBMS_OUTPUT.put_line('Order Received Successfully On: ' || TO_CHAR(sysdate, 'dd-mm-yyyy hh24:mi:ss'));
           DBMS_OUTPUT.put_line('Date of Order: ' || message1);
           DBMS_OUTPUT.put_line('Order Number: ' || message2);
           DBMS_OUTPUT.put_line('Number of Items In Order: ' || message3);
           DBMS_OUTPUT.put_line('Item Type in Order: ' || message4);
       END IF;
    
   END;
   /

   Lorsque vous utilisez la même instance Autonomous Database, les informations d'identification existent déjà et vous n'avez pas besoin d'exécuter DBMS_CLOUD.CREATE_CREDENTIAL pour recevoir un message. Cela s'applique lorsque le canal a été créé sur la même instance, comme indiqué dans Création d'un canal persistant explicite et envoi d'un message.

Décrit les étapes permettant d'extraire un message persistant stocké dans la banque d'objets cloud avec un canal explicite sur une instance Autonomous Database différente de l'instance qui a envoyé le message.

1. Stockez les informations d'identification de la banque d'objets à l'aide de la procédure DBMS_CLOUD.CREATE_CREDENTIAL. Par exemple :

   BEGIN
     DBMS_CLOUD.CREATE_CREDENTIAL(
       credential_name => 'my_persistent_pipe_cred',
       username => 'adb_user@example.com',
       password => 'password'
     );
   END;
   /

   Cette opération stocke les informations d'identification dans la base de données dans un format crypté. Vous pouvez utiliser n'importe quel nom d'informations d'identification. Cette étape est requise une seule fois, sauf si les informations d'identification de banque d'objets changent. Une fois les informations d'identification stockées, vous pouvez utiliser le même nom d'informations d'identification pour accéder à la banque d'objets cloud afin d'envoyer et de recevoir des messages avec DBMS_PIPE.

   Pour obtenir des informations détaillées sur les paramètres, reportez-vous à la 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 à Utilisation du principal de ressource pour accéder à des ressources Oracle Cloud Infrastructure.

   Remarque
   
   Certains outils tels que SQL*Plus et SQL Developer utilisent le caractère esperluette (&) comme caractère spécial. Si votre mot de passe contient l'esperluette, utilisez la commande SET DEFINE OFF dans ces outils, comme indiqué dans l'exemple, pour désactiver le caractère spécial et obtenir les informations d'identification créées correctement.
2. Créez un canal explicite portant le même nom que le canal qui a envoyé le message. Par exemple, créez un canal nommé ORDER_PIPE.

   DECLARE
     r_status INTEGER;
   BEGIN
       r_status := DBMS_PIPE.CREATE_PIPE(pipename => 'ORDER_PIPE');
   END;
   /

   Reportez-vous à Fonction CREATE_PIPE.

3. Vérifiez que le pipe est créé.

   SELECT ownerid, name, type FROM v$db_pipes 
          WHERE name = 'ORDER_PIPE';
   

   OWNERID NAME       TYPE    
   ------- ---------- ------- 
        80 ORDER_PIPE PRIVATE 

4. Utilisez les procédures DBMS_PIPE pour définir les informations d'identification d'accès et l'URI d'emplacement par défaut pour la banque d'objets afin que DBMS_PIPE puisse accéder au message persistant.

   BEGIN
       DBMS_PIPE.SET_CREDENTIAL_NAME('my_persistent_pipe_cred');
       DBMS_PIPE.SET_LOCATION_URI('https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/'); 
   END;
   /

   Ces procédures définissent le nom des informations d'identification par défaut et l'URI d'emplacement par défaut à utiliser avec les procédures DBMS_PIPE.

   Si vous utilisez Oracle Cloud Infrastructure Object Storage pour stocker des messages, vous pouvez utiliser des URI natifs Oracle Cloud Infrastructure ou des URI Swift. Cependant, l'URI d'emplacement et les informations d'identification doivent correspondre au type suivant :

   • Si vous utilisez un format d'URI natif pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser l'authentification des clés de signature Oracle Cloud Infrastructure natives dans l'objet d'informations d'identification.

   • Si vous utilisez le format d'URI Swift pour accéder à Oracle Cloud Infrastructure Object Storage, vous devez utiliser une authentification par jeton d'authentification dans l'objet d'informations d'identification.

   Pour plus d'informations, reportez-vous à Procédure SET_CREDENTIAL_NAME et à Procédure SET_LOCATION_URI.

5. Recevez un message du canal persistant.

   DECLARE
       message1  DATE;
       message2  VARCHAR2(100);
       message3  INTEGER;
       message4  VARCHAR2(100);
       l_result  INTEGER;
   
   BEGIN
   
       DBMS_PIPE.SET_CREDENTIAL_NAME('my_persistent_pipe_cred');
       DBMS_PIPE.SET_LOCATION_URI('https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/'); 
       l_result := DBMS_PIPE.RECEIVE_MESSAGE (
                     pipename => 'ORDER_PIPE',
                     timeout  => DBMS_PIPE.MAXWAIT,
                     credential_name => DBMS_PIPE.GET_CREDENTIAL_NAME,
                     location_uri => DBMS_PIPE.GET_LOCATION_URI);
    
       IF l_result = 0 THEN
           DBMS_PIPE.unpack_message(message1);
           DBMS_PIPE.unpack_message(message2);
           DBMS_PIPE.unpack_message(message3);
           DBMS_PIPE.unpack_message(message4);
    
           DBMS_OUTPUT.put_line('Order Received Successfully On: ' || TO_CHAR(sysdate, 'dd-mm-yyyy hh24:mi:ss'));
           DBMS_OUTPUT.put_line('Date of Order: ' || message1);
           DBMS_OUTPUT.put_line('Order Number: ' || message2);
           DBMS_OUTPUT.put_line('Number of Items In Order: ' || message3);
           DBMS_OUTPUT.put_line('Item Type in Order: ' || message4);
       END IF;
    
   END;
   /

   Pour plus d'informations, reportez-vous à Fonction RECEIVE_MESSAGE.

Décrit les étapes de suppression d'un canal persistant.

1. Appelez la fonction DBMS_PIPE.REMOVE_PIPE pour enlever un canal.

   DECLARE
      l_result  INTEGER;
   BEGIN
        l_result := DBMS_PIPE.REMOVE_PIPE('ORDER_PIPE');
   END;
   /

   La fonction REMOVE_PIPE enlève le canal de l'instance Autonomous Database où elle s'exécute. Toutefois, REMOVE_PIPE n'affecte pas les autres instances Autonomous Database avec un canal portant le même nom qui utilise le même URI d'emplacement.

2. Sur l'instance Autonomous Database, lorsque vous exécutez DBMS_PIPE.REMOVE_PIPE, vérifiez que le pipeline est enlevé.

   SELECT ownerid, name, type FROM v$db_pipes 
          WHERE name = 'ORDER_PIPE';
   

   No rows selected