Ensemble DBMS_PIPE (Pipes de messagerie persistantes)
L'ensemble DBMS_PIPE permet à deux sessions ou plus dans la même instance de communiquer.
Oracle Autonomous AI Database sur une infrastructure Exadata dédiée prend en charge la fonctionnalité DBMS_PIPE de base disponible dans Oracle Database 19c, plus les extensions.
Voir DBMS_PIPE dans Informations de référence sur les ensembles et les types PL/SQL pour Oracle Database 19c ou Informations de référence sur les ensembles et les types PL/SQL pour Oracle Database 26ai pour plus de détails sur la fonctionnalité DBMS_PIPE de base fournie dans Oracle Database.
Aperçu DBMS_PIPE pour les pipelines de messagerie persistants
La fonctionnalité de canal comporte plusieurs applications potentielles : interface de service externe, débogage, transactions indépendantes et alertes.
Sur Autonomous AI Database, l'ensemble DBMS_PIPE offre des fonctionnalités étendues pour la prise en charge des canaux de messagerie persistants. Pour plus d'informations, voir DBMS_PIPE dans Informations de référence sur les ensembles et les types PL/SQL pour Oracle Database 19c ou Informations de référence sur les ensembles et les types PL/SQL pour Oracle Database 26ai.
Messages persistants dans DBMS_PIPE :
-
Prise en charge de la possibilité d'envoyer et de récupérer des messages très volumineux.
-
Prise en charge d'un grand nombre de messages de canal.
-
Prenez en charge le partage de messages au sein d'une seule base de données, entre plusieurs bases de données et entre des bases de données de différentes régions.
-
Prendre en charge plusieurs canaux à l'aide du même URI d'emplacement du magasin d'objets en nuage.
La fonctionnalité de messagerie persistante permet à deux sessions de base de données ou plus de communiquer avec les messages stockés dans le magasin d'objets en nuage. À l'aide de cette fonctionnalité, les messages d'un canal peuvent être mis à la disposition uniquement de la base de données courante ou être mis à la disposition de plusieurs bases de données dans la même région ou dans différentes régions.
Un canal de messagerie persistant peut être l'un des types
DBMS_PIPEpris en charge :-
Canal implicite : Créé automatiquement lorsqu'un message est envoyé avec un nom de canal inconnu à l'aide de la fonction
DBMS_PIPE.SEND_MESSAGE. -
Canal explicite : Créé à l'aide de la fonction
DBMS_PIPE.CREATE_PIPEavec un nom de canal spécifié par l'utilisateur. -
Public Pipe : Accessible par tout utilisateur disposant de l'autorisation
EXECUTEsur l'ensembleDBMS_PIPE. -
Canal privé : Accessible par des sessions avec le même utilisateur que le créateur du canal. Note : Lorsque vous envoyez et recevez des messages dans différentes bases de données à l'aide de messages persistants, Oracle vous recommande d'appeler
DBMS_PIPE.CREATE_PIPEavant d'envoyer ou de recevoir des messages. La création d'un canal explicite avecDBMS_PIPE.CREATE_PIPEgarantit qu'un canal est créé avec les autorisations d'accès voulues, publiques ou privées (en réglant le paramètrePRIVATEàFALSEou en utilisant la valeur par défautTRUE).
-
Limite DBMS_PIPE
L'ensemble DBMS_PIPE ne prend pas en charge l'envoi de messages entre des bases de données qui utilisent des jeux de caractères différents. Par exemple, si vous avez une instance de base de données d'IA autonome qui utilise AL32UTF8 et une autre qui utilise WE8MSWIN1252, vous ne pouvez pas envoyer de messages avec DBMS_PIPE entre ces deux bases de données. Dans ce cas, le système générera l'erreur ORA-12704 si vous tentez d'envoyer des messages avec DBMS_PIPE entre ces deux bases de données.
Sommaire des sous-programmes DBMS_PIPE pour la messagerie persistante
Ce tableau répertorie les sous-programmes DBMS_PIPE et les décrit brièvement.
| Sous-programme | Description |
|---|---|
| Fonction CREATE_PIPE | Crée un tuyau (nécessaire pour les tuyaux privés). |
| Fonction GET_CREDENTIAL_NAME | Retourne la valeur de variable credential_name globale. |
| Fonction GET_LOCATION_URI | Retourne la valeur de la variable location_uri globale utilisée comme URI d'emplacement par défaut lorsqu'un message est stocké dans le magasin d'objets en nuage. |
| Fonction NEXT_ITEM_TYPE |
Retourne le type de données de l'élément suivant dans la mémoire tampon. |
| Procédures PACK_MESSAGE |
Crée le message dans la mémoire tampon locale. |
| Fonction RECEIVE_MESSAGE | Copie le message du canal nommé dans la mémoire tampon locale. |
| Procédure RESET_BUFFER |
Épure le contenu de la mémoire tampon locale. |
| Fonction REMOVE_PIPE |
Supprime le tuyau nommé. |
| Fonction SEND_MESSAGE | Envoie un message sur un tuyau nommé : Cela crée implicitement un tuyau public si le tuyau nommé n'existe pas. |
| Procédure SET_CREDENTIAL_NAME | Définit la variable credential_name utilisée comme données d'identification par défaut pour les messages stockés dans le magasin d'objets en nuage. |
| Procédure SET_LOCATION_URI | Définit la variable location_uri globale utilisée comme URI d'emplacement par défaut pour les messages stockés dans le magasin d'objets en nuage. |
| Fonction UNIQUE_SESSION_NAME |
Retourne un nom de session unique. |
| Procédures UNPACK_MESSAGE |
Permet d'accéder à l'élément suivant dans la mémoire tampon. |
Fonction CREATE_PIPE
Cette fonction crée explicitement un canal public ou privé. Si l'indicateur private est TRUE, le créateur de la canalisation est affecté en tant que responsable de la canalisation privée.
Les canaux créés explicitement ne peuvent être supprimés qu'en appelant REMOVE_PIPE ou en arrêtant l'instance.
Syntaxe
DBMS_PIPE.CREATE_PIPE (
pipename IN VARCHAR2,
maxpipesize IN INTEGER DEFAULT 66536,
private IN BOOLEAN DEFAULT TRUE)
RETURN INTEGER;
Paramètres
| Paramètre | Description |
|---|---|
pipename |
Nom du canal que vous créez. Vous devez utiliser ce nom lorsque vous appelez **Attention :** N'utilisez pas de noms de canal commençant par |
maxpipesize |
Taille maximale autorisée pour le tuyau, en octets. La taille totale de tous les messages de la barre verticale ne peut pas dépasser ce montant. Le message est bloqué s'il dépasse ce maximum. La valeur par défaut de Le La valeur par défaut |
private |
Utilise la valeur par défaut, Les canaux publics peuvent être créés implicitement lorsque vous appelez |
Valeurs retournées
| Retour | Description |
|---|---|
0 |
Réussite. Si le canal existe déjà et que l'utilisateur qui tente de le créer est autorisé à l'utiliser, Oracle retourne 0, indiquant la réussite, et toutes les données déjà présentes dans le canal restent. |
ORA-23322 |
Échec dû à un conflit d'attribution de nom. Si un canal portant le même nom existe et a été créé par un autre utilisateur, Oracle signale l'erreur |
Exceptions
| Exception | Description |
|---|---|
Null pipe name |
Erreur d'autorisation : Un canal portant le même nom existe déjà et vous n'êtes pas autorisé à l'utiliser. |
Exemple
Créer un privé explicite nommé MY_PIPE1
DECLARE
l_status INTEGER;
BEGIN
l_status := DBMS_PIPE.create_pipe(
pipename => 'MY_PIPE1',
private => TRUE);
END;
/
Fonction GET_CREDENTIAL_NAME
Cette fonction retourne la valeur de variable credential_name globale à utiliser lorsque les messages sont stockés dans le magasin d'objets en nuage.
Syntaxe
DBMS_PIPE.GET_CREDENTIAL_NAME
RETURN VARCHAR2;
Valeurs retournées
| Valeur de retour | Description |
|---|---|
credential_name |
Nom des données d'identification permettant d'accéder au service de stockage d'objets en nuage. |
Exemple
DECLARE
credential_name VARCHAR2(400)
BEGIN
credential_name := DBMS_PIPE.GET_CREDENTIAL_NAME;
END;
/
Fonction GET_LOCATION_URI
Cette fonction retourne la valeur de variable location_uri globale qui peut être utilisée comme URI d'emplacement par défaut lorsque des messages de canal sont stockés dans le magasin d'objets en nuage.
Syntaxe
DBMS_PIPE.GET_LOCATION_URI
RETURN VARCHAR2;
Valeur de retour
| Valeur de retour | Description |
|---|---|
location_uri |
URI de l'objet. |
Exemple
DECLARE
location_uri VARCHAR2(400)
BEGIN
location_uri := DBMS_PIPE.GET_LOCATION_URI;
END;
/
Fonction RECEIVE_MESSAGE
Cette fonction copie le message dans le tampon de messages local.
Syntaxe
DBMS_PIPE.RECEIVE_MESSAGE (
pipename IN VARCHAR2,
timeout IN INTEGER DEFAULT maxwait,
credential_name IN VARCHAR2 DEFAULT null,
location_uri IN VARCHAR2)
RETURN INTEGER;
Paramètres
Table - Paramètres de fonction RECEIVE_MESSAGE
| Paramètre | Description |
|---|---|
pipename |
Nom de la barre verticale sur laquelle vous souhaitez recevoir un message. Les noms commençant par |
timeout |
Temps d'attente d'un message, en secondes. Une temporisation de 0 vous permet de lire sans blocage. La temporisation n'inclut pas le temps passé à exécuter la fonction de mémoire cache spécifiée avec le paramètre Valeur par défaut : est la constante |
credential_name |
Nom des données d'identification du magasin en nuage utilisé pour stocker les messages.
Vous pouvez définir cette valeur avant d'appeler L'objet de données d'identification doit disposer des privilèges |
location_uri |
URI d'emplacement du magasin en nuage utilisé pour stocker les messages.
Vous pouvez définir cette valeur avant d'appeler |
Valeurs retournées
Table - Valeurs de retour de fonction RECEIVE_MESSAGE
| Retour | Description |
|---|---|
0 |
Réussite |
1 |
Temporisé. Si le tuyau a été créé implicitement et est vide, il est supprimé. |
2 |
L'enregistrement dans le tuyau est trop volumineux pour le tampon. |
3 |
Une interruption s'est produite. |
ORA-23322 |
L'utilisateur ne dispose pas de privilèges suffisants pour lire à partir du canal. |
Notes d'utilisation
-
Pour recevoir un message d'un canal, appelez d'abord
RECEIVE_MESSAGE. Lorsque vous recevez un message, il est supprimé du tuyau. Par conséquent, un message ne peut être reçu qu'une seule fois. Pour les tuyaux créés implicitement, le tuyau est retiré après la suppression du dernier enregistrement du tuyau. -
Si le canal que vous spécifiez lorsque vous appelez
RECEIVE_MESSAGEn'existe pas déjà, Oracle crée implicitement le canal et attend de recevoir le message. Si le message n'arrive pas dans un intervalle de temporisation désigné, l'appel retourne et le tuyau est supprimé. -
Après avoir reçu le message, vous devez effectuer un ou plusieurs appels à
UNPACK_MESSAGEpour accéder aux éléments individuels du message. La procédureUNPACK_MESSAGEest surchargée pour déballer les éléments de typeDATE,NUMBER,VARCHAR2et il existe deux procédures supplémentaires pour déballer les élémentsRAWetROWID. Si vous ne connaissez pas le type de données que vous tentez de déballer, appelezNEXT_ITEM_TYPEpour déterminer le type de l'élément suivant dans la mémoire tampon. -
Les messages persistants sont garantis d'être écrits ou lus par un seul processus. Cela évite les incohérences dans le contenu des messages en raison d'écritures et de lectures simultanées. À l'aide d'un canal de messagerie persistant,
DBMS_PIPEautorise une seule opération, l'envoi d'un message ou d'un message de réception à être actif à un moment donné. Toutefois, si une opération n'est pas possible en raison d'une opération en cours, le processus tente de nouveau périodiquement jusqu'à ce que la valeurtimeoutsoit atteinte. -
Si vous utilisez Oracle Cloud Infrastructure Object Storage pour stocker des messages, vous pouvez utiliser des URI natifs d'Oracle Cloud Infrastructure ou des URI Swift. Toutefois, l'URI d'emplacement et les données 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 native des clés de signature Oracle Cloud Infrastructure dans l'objet de données 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 de données d'identification.
-
Exceptions
Table - Exceptions de fonction RECEIVE_MESSAGE
| Exception | Description |
|---|---|
Null pipe name |
Erreur d'autorisation. Privilège insuffisant pour supprimer l'enregistrement de la barre verticale. La pipe appartient à quelqu'un d'autre. |
Fonction SEND_MESSAGE
Cette fonction envoie un message sur le canal nommé.
Le message est contenu dans la mémoire tampon du message local, qui a été remplie d'appels à PACK_MESSAGE. Vous pouvez créer un canal explicitement à l'aide de CREATE_PIPE, sinon il est créé implicitement.
Syntaxe
DBMS_PIPE.SEND_MESSAGE (
pipename IN VARCHAR2,
timeout IN INTEGER DEFAULT MAXWAIT,
credential_name IN VARCHAR2 DEFAULT null,
location_uri IN VARCHAR2 )
RETURN INTEGER;
Paramètres
Table - Paramètres de fonction SEND_MESSAGE
| Paramètre | Description |
|---|---|
credential_name |
Nom des données d'identification du magasin en nuage utilisé pour stocker les messages.
Vous pouvez définir cette valeur avant d'appeler L'objet de données d'identification doit disposer des privilèges |
location_uri |
URI d'emplacement du magasin en nuage utilisé pour stocker les messages.
Vous pouvez définir cette valeur avant d'appeler |
maxpipesize |
Taille maximale autorisée pour le tuyau, en octets. La taille totale de tous les messages de la barre verticale ne peut pas dépasser ce montant. Le message est bloqué s'il dépasse ce maximum. La valeur par défaut est 65536 octets. Le La spécification de La valeur par défaut |
pipename |
Nom de la barre verticale sur laquelle vous voulez placer le message. Si vous utilisez une barre verticale explicite, il s'agit du nom que vous avez spécifié lorsque vous avez appelé **Attention :** N'utilisez pas de noms de barre verticale commençant par ' |
timeout |
Temps d'attente en tentant de placer un message sur une barre verticale, en secondes. La valeur par défaut est la constante |
Valeurs retournées
Table - Valeurs de retour de fonction SEND_MESSAGE
| Retour | Description |
|---|---|
0 |
Succès. Si le canal existe déjà et que l'utilisateur qui tente de le créer est autorisé à l'utiliser, Oracle retourne 0, indiquant la réussite, et toutes les données déjà présentes dans le canal restent. Si un utilisateur connecté en tant que |
1 |
Temporisé. Cette procédure peut expirer soit parce qu'elle ne peut pas obtenir un verrou sur le tuyau, soit parce que le tuyau reste trop plein pour être utilisé. Si le tuyau a été créé implicitement et est vide, il est supprimé. |
3 |
Une interruption s'est produite. Si le tuyau a été créé implicitement et est vide, il est supprimé. |
ORA-23322 |
Privilèges insuffisants. Si un canal portant le même nom existe et a été créé par un autre utilisateur, Oracle signale l'erreur |
Notes d'utilisation
-
Les messages persistants sont garantis d'être écrits ou lus par un seul processus. Cela évite les incohérences dans le contenu des messages en raison d'écritures et de lectures simultanées. À l'aide d'un canal de messagerie persistant,
DBMS_PIPEautorise une seule opération, l'envoi d'un message ou d'un message de réception à être actif à un moment donné. Toutefois, si une opération n'est pas possible en raison d'une opération en cours, le processus tente de nouveau périodiquement jusqu'à ce que la valeurtimeoutsoit atteinte. -
Si vous utilisez Oracle Cloud Infrastructure Object Storage pour stocker des messages, vous pouvez utiliser des URI natifs d'Oracle Cloud Infrastructure ou des URI Swift. Toutefois, l'URI d'emplacement et les données 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 native des clés de signature Oracle Cloud Infrastructure dans l'objet de données 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 de données d'identification.
-
Exceptions
Table - Exception de fonction SEND_MESSAGE
| Exception | Description |
|---|---|
Null pipe name |
Erreur d'autorisation. Privilège insuffisant pour écrire dans le canal. Le tuyau est privé et appartient à quelqu'un d'autre. |
Procédure SET_CREDENTIAL_NAME
Cette procédure définit la variable credential_name qui est utilisée comme données d'identification par défaut lorsque des messages de canal sont stockés dans le magasin d'objets en nuage.
Syntaxe
DBMS_PIPE.SET_CREDENTIAL_NAME (
credential_name IN VARCHAR2 );
Paramètres
| Paramètre | Description |
|---|---|
credential_name |
Nom des données d'identification permettant d'accéder au service de stockage d'objets en nuage. |
Note d'utilisation
Si vous utilisez Oracle Cloud Infrastructure Object Storage pour stocker des messages, vous pouvez utiliser des URI natifs d'Oracle Cloud Infrastructure ou des URI Swift. Toutefois, l'URI d'emplacement et les données 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 native des clés de signature Oracle Cloud Infrastructure dans l'objet de données 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 de données d'identification.
Exemple
BEGIN
DBMS_PIPE.SET_CREDENTIAL_NAME(
credential_name => 'my_cred1');
END;
/
Procédure SET_LOCATION_URI
Cette procédure définit la variable location_uri globale.
Syntaxe
DBMS_PIPE.SET_LOCATION_URI (
location_uri IN VARCHAR2 );
Paramètre
| Paramètre | Description |
|---|---|
location_uri |
URI d'objet ou de fichier. Le format de l'URI dépend du service de stockage d'objets en nuage que vous utilisez. Pour plus de détails, voir Formats d'URI du service de stockage d'objets en nuage. |
Note d'utilisation
Si vous utilisez Oracle Cloud Infrastructure Object Storage pour stocker des messages, vous pouvez utiliser des URI natifs d'Oracle Cloud Infrastructure ou des URI Swift. Toutefois, l'URI d'emplacement et les données 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 native des clés de signature Oracle Cloud Infrastructure dans l'objet de données 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 de données d'identification.
Exemple
BEGIN
DBMS_PIPE.GET_LOCATION_URI(
location_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/');
END;
/