DBMS_PIPE-Package (Persistente Messaging-Pipes)
DBMS_PIPE
können zwei oder mehr Sessions in derselben Instanz kommunizieren.
Oracle Autonomous Database on Dedicated Exadata Infrastructure unterstützt die in Oracle Database 19c verfügbare Corefunktionalität von DBMS_PIPE
sowie Erweiterungen.
Weitere Informationen über die in Oracle Database bereitgestellte DBMS_PIPE
-Kernfunktionalität finden Sie unter DBMS_PIPE in Oracle Database 19c PL/SQL-Pakete und Typenreferenz oder Oracle Database 23ai PL/SQL-Pakete und -Typenreferenz.
DBMS_PIPE Überblick über persistente Messaging-Pipes
Die Pipe-Funktionalität hat mehrere potenzielle Anwendungen: externe Serviceschnittstelle, Debugging, unabhängige Transaktionen und Warnungen.
In Autonomous Database verfügt das Package DBMS_PIPE über erweiterte Funktionen zur Unterstützung persistenter Messaging-Pipes. Weitere Informationen finden Sie unter DBMS_PIPE in Oracle Database 19c PL/SQL-Packages und Typenreferenz oder Oracle Database 23ai PL/SQL-Packages und Typenreferenz.
Persistente Nachrichten in DBMS_PIPE
:
-
Unterstützen Sie die Möglichkeit, sehr große Nachrichten zu senden und abzurufen.
-
Unterstützt eine große Anzahl von Pipe-Nachrichten.
-
Unterstützen Sie die gemeinsame Nutzung von Nachrichten innerhalb einer einzelnen Datenbank, über mehrere Datenbanken hinweg und über Datenbanken in verschiedenen Regionen hinweg.
-
Unterstützen Sie mehrere Pipes mit derselben Speicherort-URI des Cloud-Objektspeichers.
Mit der persistenten Messaging-Funktion können zwei oder mehr Datenbanksessions mit Nachrichten kommunizieren, die im Cloud-Objektspeicher gespeichert sind. Mit dieser Funktionalität können Meldungen in einer Pipe nur der aktuellen Datenbank oder mehreren Datenbanken in derselben Region oder über verschiedene Regionen hinweg zur Verfügung gestellt werden.
Eine persistente Messaging Pipe kann einer der unterstützten
DBMS_PIPE
-Typen sein:- Implizite Pipe: Wird automatisch erstellt, wenn eine Nachricht mit einem unbekannten Pipe-Namen mit der Funktion
DBMS_PIPE.SEND_MESSAGE
gesendet wird. - Explizite Pipe: Wird mit der Funktion
DBMS_PIPE.CREATE_PIPE
mit einem benutzerdefinierten Pipe-Namen erstellt. - Öffentliche Pipe: Zugriff für alle Benutzer mit der Berechtigung
EXECUTE
für das PackageDBMS_PIPE
. - Private Pipe: Zugriff durch Sessions mit demselben Benutzer wie der Pipe-Ersteller.
- Implizite Pipe: Wird automatisch erstellt, wenn eine Nachricht mit einem unbekannten Pipe-Namen mit der Funktion
Hinweis:
Wenn Sie Nachrichten über verschiedene Datenbanken hinweg mit persistenten Nachrichten senden und empfangen, empfiehlt Oracle, dass SieDBMS_PIPE.CREATE_PIPE
aufrufen, bevor Sie Nachrichten senden oder empfangen. Durch das Erstellen einer expliziten Pipe mit DBMS_PIPE.CREATE_PIPE
wird sichergestellt, dass eine Pipe mit den gewünschten Zugriffsberechtigungen erstellt wird, entweder öffentlich oder privat (indem Sie den Parameter PRIVATE
auf FALSE
setzen oder den Standardwert TRUE
verwenden).
DBMS_PIPE Einschränkung
Das Package DBMS_PIPE
unterstützt nicht das Senden von Nachrichten zwischen Datenbanken, die unterschiedliche Zeichensätze verwenden. Beispiel: Wenn Sie eine Autonomous Database-Instanz verwenden, die AL32UTF8 verwendet, und eine andere Instanz, die WE8MSWIN1252 verwendet, können Sie keine Nachrichten mit DBMS_PIPE
zwischen diesen beiden Datenbanken senden. In diesem Fall löst das System den Fehler ORA-12704
aus, wenn Sie versuchen, Nachrichten mit DBMS_PIPE
zwischen diesen beiden Datenbanken zu senden.
Zusammenfassung der DBMS_PIPE-Unterprogramme für persistentes Messaging
In dieser Tabelle werden die DBMS_PIPE
-Unterprogramme aufgeführt und kurz beschrieben.
Tabelle - DBMS_PIPE-Packageunterprogramme
Unterprogramm | Beschreibung |
---|---|
Erstellt eine Pipe (für private Rohre erforderlich). |
|
Gibt den globalen Variablenwert |
|
Gibt den globalen Variablenwert |
|
Gibt den Datentyp des nächsten Elements im Puffer zurück. |
|
Erstellt Meldung im lokalen Puffer. |
|
Kopiert Nachricht von benannter Pipe in lokalen Puffer. |
|
Löscht den Inhalt des lokalen Puffers. |
|
Entfernt die benannte Pipe. |
|
Sendet eine Nachricht an eine benannte Pipe: Dadurch wird implizit eine öffentliche Pipe erstellt, wenn die benannte Pipe nicht vorhanden ist. |
|
Legt die Variable |
|
Legt die globale Variable |
|
Funktion UNIQUE_SESSION_NAME
|
Gibt einen eindeutigen Sessionnamen zurück. |
Greift auf das nächste Element im Puffer zu. |
Funktion CREATE_PIPE
Diese Funktion erstellt explizit eine öffentliche oder private Pipe. Wenn das Flag private
TRUE
lautet, wird der Pipe-Ersteller als Eigentümer der privaten Pipe zugewiesen.
Explizit erstellte Pipes können nur durch Aufruf von REMOVE_PIPE
oder durch Herunterfahren der Instanz entfernt werden.
Syntax
DBMS_PIPE.CREATE_PIPE ( pipename IN VARCHAR2, maxpipesize IN INTEGER DEFAULT 66536, private IN BOOLEAN DEFAULT TRUE) RETURN INTEGER;
Parameter
Tabelle - CREATE_PIPE-Funktionsparameter
Parameter | Beschreibung |
---|---|
|
Name der Pipe, die Sie erstellen. Sie müssen diesen Namen verwenden, wenn Sie Achtung: Verwenden Sie keine Pipe-Namen, die mit |
|
Die maximal zulässige Größe für die Pipe in Byte. Die Gesamtgröße aller Nachrichten in der Pipe darf diesen Betrag nicht überschreiten. Die Nachricht wird blockiert, wenn sie diesen Höchstwert überschreitet. Der Standard Die Die Standardeinstellung |
|
Verwendet den Standardwert Öffentliche Pipes können implizit erstellt werden, wenn Sie |
Rückgabewerte
Tabelle - Rückgabewerte der Funktion CREATE_PIPE
Return | Beschreibung |
---|---|
|
Erfolgreich. Wenn die Pipe bereits vorhanden ist und der Benutzer, der versucht, sie zu erstellen, autorisiert ist, sie zu verwenden, gibt Oracle 0 zurück und gibt den Erfolg an. Alle bereits in der Pipe enthaltenen Daten bleiben erhalten. |
|
Fehler aufgrund eines Namenskonflikts. Wenn eine Pipe mit demselben Namen vorhanden ist und von einem anderen Benutzer erstellt wurde, gibt Oracle den Fehler |
Exceptions
Tabelle - Funktionsausnahme CREATE_PIPE
Ausnahme | Beschreibung |
---|---|
|
Berechtigungsfehler: Pipe mit demselben Namen ist bereits vorhanden und darf nicht verwendet werden. |
Beispiel
Erstellen Sie einen expliziten privaten Namen namens MY_PIPE1
.
DECLARE
l_status INTEGER;
BEGIN
l_status := DBMS_PIPE.create_pipe(
pipename => 'MY_PIPE1',
private => TRUE);
END;
/
Funktion GET_CREDENTIAL_NAME
Diese Funktion gibt den globalen Variablenwert credential_name
zurück, der verwendet werden soll, wenn Nachrichten im Cloud-Objektspeicher gespeichert werden.
Syntax
DBMS_PIPE.GET_CREDENTIAL_NAME RETURN VARCHAR2;
Rückgabewerte
Rückgabewert | Beschreibung |
---|---|
|
Der Name der Zugangsdaten für den Zugriff auf den Cloud-Objektspeicher. |
Beispiel
DECLARE
credential_name VARCHAR2(400)
BEGIN
credential_name := DBMS_PIPE.GET_CREDENTIAL_NAME;
END;
/
Funktion GET_LOCATION_URI
Diese Funktion gibt den globalen Variablenwert location_uri
zurück, der als Standardverzeichnis-URI verwendet werden kann, wenn Pipe-Nachrichten im Cloud-Objektspeicher gespeichert werden.
Syntax
DBMS_PIPE.GET_LOCATION_URI RETURN VARCHAR2;
Rückgabewert
Rückgabewert | Beschreibung |
---|---|
location_uri |
Die Objekt-URI. |
Beispiel
DECLARE
location_uri VARCHAR2(400)
BEGIN
location_uri := DBMS_PIPE.GET_LOCATION_URI;
END;
/
Funktion RECEIVE_MESSAGE
Diese Funktion kopiert die Nachricht in den lokalen Nachrichtenpuffer.
Syntax
DBMS_PIPE.RECEIVE_MESSAGE ( pipename IN VARCHAR2, timeout IN INTEGER DEFAULT maxwait, credential_name IN VARCHAR2 DEFAULT null, location_uri IN VARCHAR2) RETURN INTEGER;
Parameter
Tabelle - RECEIVE_MESSAGE-Funktionsparameter
Parameter | Beschreibung |
---|---|
|
Name der Pipe, an der Sie eine Nachricht erhalten möchten. Namen, die mit |
|
Wartezeit auf eine Nachricht in Sekunden. Mit einem Timeout von 0 können Sie lesen, ohne zu blockieren. Der Timeout umfasst nicht die Zeit, die für die Ausführung der Cachefunktion aufgewendet wurde, die mit dem Parameter Standardwert: ist die Konstante |
|
Der Zugangsdatenname für den Cloud-Speicher, in dem Nachrichten gespeichert werden.
Sie können diesen Wert festlegen, bevor Sie Das Zugangsdatenobjekt muss über die Berechtigungen |
|
Die Standort-URI für den Cloud-Speicher, in dem Nachrichten gespeichert werden.
Sie können diesen Wert festlegen, bevor Sie |
Rückgabewerte
Tabelle - Rückgabewerte der Funktion RECEIVE_MESSAGE
Return | Beschreibung |
---|---|
|
Erfolgreich |
|
Wegen Timeout abgebrochen. Wenn die Pipe implizit erstellt wurde und leer ist, wird sie entfernt. |
|
Datensatz in der Pipe ist zu groß für den Puffer. |
|
Interrupt aufgetreten. |
|
Der Benutzer hat keine ausreichenden Berechtigungen zum Lesen aus der Pipe. |
Verwendungshinweise
-
Um eine Nachricht von einer Pipe zu empfangen, rufen Sie zunächst
RECEIVE_MESSAGE
auf. Wenn Sie eine Nachricht erhalten, wird sie aus der Pipe entfernt. Daher kann eine Nachricht nur einmal empfangen werden. Bei implizit erstellten Rohren wird die Pipe entfernt, nachdem der letzte Datensatz aus der Pipe entfernt wurde. -
Wenn die Pipe, die Sie beim Aufruf von
RECEIVE_MESSAGE
angeben, noch nicht vorhanden ist, erstellt Oracle implizit die Pipe und wartet auf den Empfang der Nachricht. Wenn die Nachricht nicht innerhalb eines festgelegten Timeoutintervalls ankommt, wird der Aufruf zurückgegeben und die Pipe entfernt. -
Nachdem Sie die Nachricht erhalten haben, müssen Sie mindestens einen Aufruf an
UNPACK_MESSAGE
ausführen, um auf die einzelnen Elemente in der Nachricht zuzugreifen. Die ProzedurUNPACK_MESSAGE
wird überladen, um Elemente des TypsDATE
,NUMBER
,VARCHAR2
zu entpacken. Außerdem gibt es zwei zusätzliche Prozeduren zum Entpacken vonRAW
- undROWID
-Elementen. Wenn Sie den Datentyp nicht kennen, den Sie entpacken möchten, rufen SieNEXT_ITEM_TYPE
auf, um den Typ des nächsten Elements im Puffer zu bestimmen. -
Persistente Nachrichten werden garantiert entweder von genau einem Prozess geschrieben oder gelesen. Dadurch wird eine Inkonsistenz des Nachrichteninhalts durch gleichzeitige Schreib- und Lesevorgänge verhindert. Mit einer persistenten Messaging-Pipe lässt
DBMS_PIPE
nur einen Vorgang zu, bei dem eine Nachricht oder eine empfangende Nachricht zu einem bestimmten Zeitpunkt aktiv sein kann. Wenn ein Vorgang jedoch aufgrund eines laufenden Vorgangs nicht möglich ist, wiederholt sich der Prozess in regelmäßigen Abständen, bis der Werttimeout
erreicht ist. -
Wenn Sie Nachrichten mit Oracle Cloud Infrastructure Object Storage speichern, können Sie Oracle Cloud Infrastructure-native URIs oder Swift-URIs verwenden. Der Speicherort-URI und die Zugangsdaten müssen jedoch wie folgt mit dem Typ übereinstimmen:
-
Wenn Sie ein natives URI-Format für den Zugriff auf Oracle Cloud Infrastructure Object Storage verwenden, müssen Sie die native Authentifizierung für Oracle Cloud Infrastructure-Signaturschlüssel im Zugangsdatenobjekt verwenden.
-
Wenn Sie mit dem Swift-URI-Format auf Oracle Cloud Infrastructure Object Storage zugreifen, müssen Sie eine Authentifizierung mit Authentifizierungstoken im Zugangsdatenobjekt verwenden.
-
Exceptions
Tabelle - RECEIVE_MESSAGE-Funktionsausnahmen
Ausnahme | Beschreibung |
---|---|
|
Berechtigungsfehler. Unzureichende Berechtigung zum Entfernen des Datensatzes aus der Pipe. Die Pipe ist im Besitz einer anderen Person. |
Funktion SEND_MESSAGE
Diese Funktion sendet eine Nachricht an die benannte Pipe.
Die Nachricht ist im lokalen Nachrichtenpuffer enthalten, der mit Aufrufen an PACK_MESSAGE
gefüllt wurde. Sie können eine Pipe explizit mit CREATE_PIPE
erstellen. Andernfalls wird sie implizit erstellt.
Syntax
DBMS_PIPE.SEND_MESSAGE ( pipename IN VARCHAR2, timeout IN INTEGER DEFAULT MAXWAIT, credential_name IN VARCHAR2 DEFAULT null, location_uri IN VARCHAR2 ) RETURN INTEGER;
Parameter
Tabelle - SEND_MESSAGE-Funktionsparameter
Parameter | Beschreibung |
---|---|
credential_name |
Der Zugangsdatenname für den Cloud-Speicher, in dem Nachrichten gespeichert werden.
Sie können diesen Wert festlegen, bevor Sie Das Zugangsdatenobjekt muss über die Berechtigungen |
location_uri |
Die Standort-URI für den Cloud-Speicher, in dem Nachrichten gespeichert werden.
Sie können diesen Wert festlegen, bevor Sie |
|
Maximal zulässige Größe für die Pipe, in Byte. Die Gesamtgröße aller Nachrichten in der Pipe darf diesen Betrag nicht überschreiten. Die Nachricht wird blockiert, wenn sie diesen Höchstwert überschreitet. Der Standardwert beträgt 65536 Byte. Die Wenn Sie Die Standardeinstellung |
|
Name der Pipe, auf der Sie die Nachricht platzieren möchten. Wenn Sie eine explizite Pipe verwenden, ist dies der Name, den Sie beim Aufruf von Achtung: Verwenden Sie keine Pipe-Namen, die mit " |
|
Wartezeit beim Versuch, eine Nachricht in einer Pipe zu platzieren, in Sekunden. Der Standardwert ist die Konstante |
Rückgabewerte
Tabelle - Rückgabewerte der Funktion SEND_MESSAGE
Return | Beschreibung |
---|---|
|
Erfolgreich. Wenn die Pipe bereits vorhanden ist und der Benutzer, der versucht, sie zu erstellen, autorisiert ist, sie zu verwenden, gibt Oracle 0 zurück und gibt den Erfolg an. Alle bereits in der Pipe enthaltenen Daten bleiben erhalten. Wenn ein Benutzer, der mit |
|
Wegen Timeout abgebrochen. Dieser Vorgang kann wegen Timeout abgebrochen werden, weil er keine Sperre für die Pipe erhalten kann oder weil die Pipe für die Verwendung zu voll bleibt. Wenn die Pipe implizit erstellt wurde und leer ist, wird sie entfernt. |
|
Interrupt aufgetreten. Wenn die Pipe implizit erstellt wurde und leer ist, wird sie entfernt. |
|
Berechtigungen reichen nicht aus. Wenn eine Pipe mit demselben Namen vorhanden ist und von einem anderen Benutzer erstellt wurde, gibt Oracle den Fehler |
Verwendungshinweise
-
Persistente Nachrichten werden garantiert entweder von genau einem Prozess geschrieben oder gelesen. Dadurch wird eine Inkonsistenz des Nachrichteninhalts durch gleichzeitige Schreib- und Lesevorgänge verhindert. Mit einer persistenten Messaging-Pipe lässt
DBMS_PIPE
nur einen Vorgang zu, bei dem eine Nachricht oder eine empfangende Nachricht zu einem bestimmten Zeitpunkt aktiv sein kann. Wenn ein Vorgang jedoch aufgrund eines laufenden Vorgangs nicht möglich ist, wiederholt sich der Prozess in regelmäßigen Abständen, bis der Werttimeout
erreicht ist. -
Wenn Sie Oracle Cloud Infrastructure Object Storage zum Speichern von Nachrichten verwenden, können Sie Oracle Cloud Infrastructure-native URIs oder Swift-URIs verwenden. Der Speicherort-URI und die Zugangsdaten müssen jedoch wie folgt mit dem Typ übereinstimmen:
-
Wenn Sie ein natives URI-Format für den Zugriff auf Oracle Cloud Infrastructure Object Storage verwenden, müssen Sie die native Authentifizierung für Oracle Cloud Infrastructure-Signaturschlüssel im Zugangsdatenobjekt verwenden.
-
Wenn Sie mit dem Swift-URI-Format auf Oracle Cloud Infrastructure Object Storage zugreifen, müssen Sie eine Authentifizierung mit Authentifizierungstoken im Zugangsdatenobjekt verwenden.
-
Exceptions
Tabelle - Funktionsausnahme SEND_MESSAGE
Ausnahme | Beschreibung |
---|---|
|
Berechtigungsfehler. Unzureichende Berechtigung zum Schreiben in die Pipe. Die Pipe ist privat und gehört einer anderen Person. |
Prozedur SET_CREDENTIAL_NAME
Diese Prozedur legt die Variable credential_name
fest, die als Standardzugangsdaten verwendet wird, wenn Pipe-Nachrichten im Cloud-Objektspeicher gespeichert werden.
Syntax
DBMS_PIPE.SET_CREDENTIAL_NAME ( credential_name IN VARCHAR2 );
Parameter
Parameter | Beschreibung |
---|---|
|
Der Name der Zugangsdaten für den Zugriff auf den Cloud-Objektspeicher. |
Hinweis zur Verwendung
Wenn Sie Oracle Cloud Infrastructure Object Storage zum Speichern von Nachrichten verwenden, können Sie Oracle Cloud Infrastructure-native URIs oder Swift-URIs verwenden. Der Speicherort-URI und die Zugangsdaten müssen jedoch wie folgt mit dem Typ übereinstimmen:
-
Wenn Sie ein natives URI-Format für den Zugriff auf Oracle Cloud Infrastructure Object Storage verwenden, müssen Sie die native Authentifizierung für Oracle Cloud Infrastructure-Signaturschlüssel im Zugangsdatenobjekt verwenden.
-
Wenn Sie mit dem Swift-URI-Format auf Oracle Cloud Infrastructure Object Storage zugreifen, müssen Sie eine Authentifizierung mit Authentifizierungstoken im Zugangsdatenobjekt verwenden.
Beispiel
BEGIN
DBMS_PIPE.SET_CREDENTIAL_NAME(
credential_name => 'my_cred1');
END;
/
Prozedur SET_LOCATION_URI
Diese Prozedur legt die globale Variable location_uri
fest.
Syntax
DBMS_PIPE.SET_LOCATION_URI ( location_uri IN VARCHAR2 );
Parameter
Parameter | Beschreibung |
---|---|
location_uri |
Objekt- oder Datei-URI. Das Format der URI ist vom verwendeten Cloud-Objektspeicherservice abhängig. Weitere Einzelheiten finden Sie unter URI-Formate für Cloud-Objektspeicher. |
Hinweis zur Verwendung
Wenn Sie Oracle Cloud Infrastructure Object Storage zum Speichern von Nachrichten verwenden, können Sie Oracle Cloud Infrastructure-native URIs oder Swift-URIs verwenden. Der Speicherort-URI und die Zugangsdaten müssen jedoch wie folgt mit dem Typ übereinstimmen:
-
Wenn Sie ein natives URI-Format für den Zugriff auf Oracle Cloud Infrastructure Object Storage verwenden, müssen Sie die native Authentifizierung für Oracle Cloud Infrastructure-Signaturschlüssel im Zugangsdatenobjekt verwenden.
-
Wenn Sie mit dem Swift-URI-Format auf Oracle Cloud Infrastructure Object Storage zugreifen, müssen Sie eine Authentifizierung mit Authentifizierungstoken im Zugangsdatenobjekt verwenden.
Beispiel
BEGIN
DBMS_PIPE.GET_LOCATION_URI(
location_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/');
END;
/