Auf dieser Seite wird beschrieben, wie Sie Nachrichten mit der genau einmal-Funktion von Pub/Sub empfangen und bestätigen. So können Sie die doppelte Verarbeitung von Nachrichten nachverfolgen und verhindern. Wenn die Funktion aktiviert ist, bietet Pub/Sub die folgende Semantik:
Abonnenten können feststellen, ob die Bestätigungen von Nachrichten erfolgreich waren.
Nach der erfolgreichen Bestätigung der Nachricht erfolgt keine erneute Zustellung.
Solange eine Nachricht ausstehend ist, erfolgt keine erneute Zustellung. Eine Nachricht gilt als ausstehend, bis die Bestätigungsfrist abgelaufen ist oder die Nachricht bestätigt wurde.
Bei mehreren gültigen Übermittlungen kann aufgrund des Ablaufs der Bestätigungsfrist oder einer vom Client initiierten negativen Bestätigung nur die letzte Bestätigungs-ID verwendet werden, um die Nachricht zu bestätigen. Alle Anfragen mit einer vorherigen Bestätigungs-ID schlagen fehl.
Wenn die Funktion „Genau einmal“ aktiviert ist, können Abonnenten dafür sorgen, dass Nachrichten nur einmal verarbeitet werden. Beachten Sie dazu die folgenden Richtlinien:
Bestätigen Sie Nachrichten innerhalb der Bestätigungsfrist.
Behalten Sie Informationen zum Fortschritt der Verarbeitung einer Nachricht im Auge, bis sie bestätigt wurde.
Anhand der Informationen zum Fortschritt der Verarbeitung einer Nachricht können Sie verhindern, dass Sie doppelte Arbeit leisten müssen, wenn eine Bestätigung fehlschlägt.
Nur der Pull-Abotyp unterstützt die Übermittlung genau einmal, einschließlich Abonnenten, die die StreamingPull API verwenden. Push- und Exportabos unterstützen die genau einmalige Zustellung nicht.
Pub/Sub unterstützt die genau einmalige Zustellung innerhalb einer Cloud-Region auf Grundlage einer von Pub/Sub definierten eindeutigen Nachrichten-ID.
Empfohlene Clientbibliotheksversionen
- Für eine optimale Leistung verwenden Sie die neueste Version der Clientbibliothek: Python v2.13.6 oder höher, Java v1.120.11 oder höher, PHP v1.39.0 oder höher, C# v3.2.0 oder höher, C++ v2.1.0, Go v1.25.1 oder höher, Node v3.2.0 oder höher und Ruby v2.12.1 oder höher.
Erneute Übermittlung im Vergleich zu Duplikaten
Es ist wichtig, den Unterschied zwischen erwarteten und unerwarteten erneuten Übermittlungen zu verstehen.
Eine erneute Zustellung kann entweder aufgrund einer vom Client initiierten negativen Bestätigung einer Nachricht oder wenn der Client die Bestätigungsfrist der Nachricht nicht verlängert, bevor sie abläuft, erfolgen. Wiederholte Übermittlungen gelten als gültig und das System funktioniert wie vorgesehen.
Informationen zur Fehlerbehebung bei erneuten Übermittlungen finden Sie unter Duplikate.
Eine Nachricht gilt als Duplikat, wenn sie nach einer erfolgreichen Bestätigung oder vor Ablauf der Bestätigungsfrist noch einmal gesendet wird.
Eine noch einmal übermittelte Nachricht behält zwischen den Übermittlungsversuchen dieselbe Nachrichten-ID.
Bei Abos mit aktivierter Funktion „Genau einmal zugestellt“ werden keine doppelten Zustellungen ausgeführt.
Unterstützung der genau einmaligen Zustellung in Clientbibliotheken
Unterstützte Clientbibliotheken haben eine Schnittstelle für die Bestätigung mit Antwort (z. B. Go). Über diese Benutzeroberfläche können Sie prüfen, ob die Bestätigungsanfrage erfolgreich war. Wenn die Bestätigungsanfrage erfolgreich ist, erhalten die Clients garantiert keine erneute Zustellung. Wenn die Bestätigungsanfrage fehlschlägt, erhalten die Kunden eine erneute Zustellung.
Clients können die unterstützten Clientbibliotheken auch ohne die Bestätigungsoberfläche verwenden. In solchen Fällen können die Bestätigungsfehler jedoch zu einer stillen erneuten Zustellung von Nachrichten führen.
Unterstützte Clientbibliotheken haben Schnittstellen zum Festlegen der Mindestdauer der Verlängerung der Laufzeit (z. B. Go). Sie müssen den Wert für die minimale Verlängerung der Laufzeit auf eine hohe Zahl festlegen, um Netzwerkfehler bei der Bestätigung zu vermeiden. Der Höchstwert beträgt 600 Sekunden.
Die Standardwerte und der Bereich für die Variablen, die sich auf die Zustellung genau einmal beziehen, sowie die Namen der Variablen können sich je nach Clientbibliothek unterscheiden. In der Java-Clientbibliothek werden beispielsweise die folgenden Variablen für die Zustellung genau einmal gesteuert.
Variable | Beschreibung | Wert |
---|---|---|
setEnableExactlyOnceDelivery |
Aktiviert oder deaktiviert die Funktion „Genau einmal zugestellt“. | „wahr“ oder „falsch“ (Standardeinstellung: „falsch“) |
minDurationPerAckExtension |
Die Mindestdauer in Sekunden, die für die Verlängerung der Frist für die Bestätigung der Änderung verwendet werden soll. | Bereich: 0 bis 600; Standard: „none“ |
maxDurationPerAckExtension |
Die maximale Zeit in Sekunden, um die die Frist für die Bestätigung der Änderung verlängert werden kann. | Bereich: 0 bis 600; Standard: „none“ |
Bei der genau einmal erfolgenden Zustellung schlägt die modifyAckDeadline
- oder acknowledgment
-Anfrage an Pub/Sub fehl, wenn die Bestätigungs-ID bereits abgelaufen ist. In solchen Fällen betrachtet der Dienst die abgelaufene Bestätigungs-ID als ungültig, da möglicherweise bereits eine neue Zustellung in Bearbeitung ist. Das ist so gewollt, damit die Nachrichten genau einmal zugestellt werden. Sie sehen dann, dass acknowledgment
- und ModifyAckDeadline
-Anfragen eine INVALID_ARGUMENT
-Antwort zurückgeben. Wenn die Zustellung genau einmal deaktiviert ist, wird bei abgelaufenen Bestätigungs-IDs OK
zurückgegeben.
Damit acknowledgment
- und ModifyAckDeadline
-Anfragen gültige Bestätigungs-IDs haben, sollten Sie den Wert für minDurationPerAckExtension
auf eine hohe Zahl festlegen.
Regionale Einschränkungen
Die Garantie für die genau einmalige Zustellung gilt nur, wenn Abonnenten eine Verbindung zum Dienst in derselben Region herstellen. Wenn Ihre Abonnentenanwendung auf mehrere Regionen verteilt ist, kann es zu doppelten Nachrichtenzustellungen kommen, auch wenn die Zustellung genau einmal aktiviert ist. Publisher können Nachrichten an jede Region senden und die Garantie, dass Nachrichten nur einmal gesendet werden, bleibt bestehen.
Wenn Sie Ihre Anwendung in Google Cloud ausführen, wird standardmäßig eine Verbindung zum Pub/Sub-Endpunkt in derselben Region hergestellt. Wenn Sie Ihre Anwendung also in einer einzelnen Region in Google Cloud ausführen, interagieren Sie in der Regel mit einer einzelnen Region.
Wenn Sie Ihre Abonnentenanwendung außerhalb von Google Cloud oder in mehreren Regionen ausführen, können Sie eine Verbindung zu einer einzelnen Region herstellen, indem Sie beim Konfigurieren Ihres Pub/Sub-Clients einen Standortendpunkt verwenden. Alle Standortendpunkte für Pub/Sub verweisen auf einzelne Regionen. Weitere Informationen zu Standortendpunkten finden Sie unter Pub/Sub-Endpunkte. Eine Liste aller standortbezogenen Endpunkte für Pub/Sub finden Sie unter Liste der standortbezogenen Endpunkte.
Abos mit genau einmaliger Zustellung erstellen
Sie können ein Abo mit einer Zustellung genau einmal mit der Google Cloud Console, der Google Cloud CLI, der Clientbibliothek oder der Pub/Sub API erstellen.
Pull-Abo
Console
So erstellen Sie ein Pull-Abo mit der Zustellung genau einmal:
Öffnen Sie in der Google Cloud Console die Seite Abos.
Klicken Sie auf Abo erstellen.
Geben Sie die Abo-ID ein.
Wählen Sie im Drop-down-Menü ein Thema aus oder erstellen Sie ein Thema.
Das Abo erhält Nachrichten aus dem Thema.
Wählen Sie im Abschnitt Genau einmal zugestellt die Option Genau einmal zugestellt aktivieren aus.
Klicken Sie auf Erstellen.
gcloud
Verwenden Sie zum Erstellen eines Pull-Abos mit einer Zustellung genau einmal den Befehl gcloud pubsub subscriptions create
mit dem Flag --enable-exactly-once-delivery
:
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --enable-exactly-once-delivery
Ersetzen Sie Folgendes:
- SUBSCRIPTION_ID: Die ID des zu erstellenden Abos
- TOPIC_ID: Die ID des Themas, das an das Abo angehängt werden soll
REST
Wenn Sie ein Abo mit genau einmal erfolgender Zustellung erstellen möchten, verwenden Sie die Methode projects.subscriptions.create
.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID Authorization: Bearer $(gcloud auth print-access-token)
Ersetzen Sie Folgendes:
- PROJECT_ID: die Projekt-ID des Projekts, in dem das Abo erstellt werden soll
- SUBSCRIPTION_ID: Die ID des zu erstellenden Abos
Wenn Sie ein Pull-Abo mit der Zustellung genau einmal erstellen möchten, geben Sie dies im Anfragetext an:
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "enableExactlyOnceDelivery": true, }
Ersetzen Sie Folgendes:
- PROJECT_ID: Die Projekt-ID des Projekts mit dem Thema
- TOPIC_ID: Die ID des Themas, das an das Abo angehängt werden soll
C++
Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für C++ in der Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub C++ API.
C#
Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für C# in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zu Pub/Sub C# API.
Go
Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für Go in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zu Pub/Sub Go API.
Java
Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für Java in der Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zu Pub/Sub Java API.
Python
Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für Python in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zu Pub/Sub Python API.
Node.js
Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für PHP in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zu Pub/Sub Node.js API.
Node.js
Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für PHP in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zu Pub/Sub Node.js API.
Ruby
Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für Ruby in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zu Pub/Sub Ruby API.
PHP
Folgen Sie der Einrichtungsanleitung für PHP unter Schnellstart: Clientbibliotheken verwenden, bevor Sie dieses Beispiel ausprobieren. Weitere Informationen finden Sie in der Referenzdokumentation zur PHP-API von Pub/Sub.
Abo mit genau einmal zugestellten Nachrichten
Im Folgenden findest du einige Codebeispiele für die Registrierung mit Übermittlung genau einmal mithilfe der Clientbibliothek.
Pull-Abo
Go
Folgen Sie der Einrichtungsanleitung für Go in der Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel anwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Go API.
Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Pub/Sub zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Java
Folgen Sie der Einrichtungsanleitung für Java in der Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel anwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Java API.
Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Pub/Sub zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Node.js
Folgen Sie der Einrichtungsanleitung für Node.js in der Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel anwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Node.js API.
Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Pub/Sub zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
PHP
Folgen Sie der Einrichtungsanleitung für PHP in der Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel anwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub PHP API.
Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Pub/Sub zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Python
Folgen Sie der Einrichtungsanleitung für Python in der Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel anwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Python API.
Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Pub/Sub zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Ruby
Folgen Sie der Einrichtungsanleitung für Ruby in der Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel anwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Ruby API.
Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Pub/Sub zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
C++
Folgen Sie der Einrichtungsanleitung für C++ in der Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel anwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub C++ API.
Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Pub/Sub zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
C#
Folgen Sie der Einrichtungsanleitung für C# in der Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel anwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub C# API.
Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Pub/Sub zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Node.js (TypeScript)
Lesen Sie unter Pub/Sub-Kurzanleitung: Clientbibliotheken verwenden die Anleitung für die Einrichtung von Node.js, bevor Sie dieses Beispiel ausprobieren. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Node.js API.
Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Pub/Sub zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Abos mit der Funktion „Genau einmal zugestellt“ beobachten
Der Messwert subscription/exactly_once_warning_count
erfasst die Anzahl der Ereignisse, die zu möglichen erneuten Übermittlungen (gültige oder doppelte) führen können. Dieser Messwert zählt die Anzahl der Fälle, in denen Pub/Sub Anfragen mit Bestätigungs-IDs (ModifyAckDeadline
- oder acknowledgment
-Anfrage) nicht verarbeiten kann. Die Gründe für den Fehler können server- oder clientseitig sein. Wenn beispielsweise die Speicherebene, die zum Speichern der Informationen zur genau einmal erfolgenden Übermittlung verwendet wird, nicht verfügbar ist, handelt es sich um ein serverbasiertes Ereignis. Wenn der Client versucht, eine Nachricht mit einer ungültigen Bestätigungs-ID zu bestätigen, handelt es sich um ein clientbasiertes Ereignis.
Messwert
subscription/exactly_once_warning_count
erfasst Ereignisse, die möglicherweise zu tatsächlichen erneuten Übermittlungen führen. Je nach Clientverhalten kann es zu vielen unnötigen Daten kommen. Beispiel: Wiederholte acknowledgment
- oder ModifyAckDeadline
-Anfragen mit ungültigen Bestätigungs-IDs erhöhen den Messwert wiederholt.
Die folgenden Messwerte sind ebenfalls hilfreich, um das Kundenverhalten zu verstehen:
Der Messwert
subscription/expired_ack_deadlines_count
gibt die Anzahl der abgelaufenen Bestätigungs-IDs an. Abgelaufene Bestätigungs-IDs können sowohl beiModifyAckDeadline
- als auch beiacknowledgment
-Anfragen zu Fehlern führen.Mit dem Messwert
service.serviceruntime.googleapis.com/api/request_count
können Fehler beiModifyAckDeadline
- oderacknowledgment
-Anfragen erfasst werden, wenn die Anfragen Google Cloud erreichen, aber nicht Pub/Sub. Es gibt Fehler, die mit diesem Messwert nicht erfasst werden, z. B. wenn die Verbindung von Clients zu Google Cloud unterbrochen wird.
In den meisten Fällen von Fehlerereignissen, die wiederholt werden können, wiederholen unterstützte Clientbibliotheken den Antrag automatisch.
Kontingente
Für Abos mit genau einmal zugestellter Zustellung gelten zusätzliche Kontingentanforderungen. Diese Kontingente gelten für:
- Anzahl der Nachrichten, die über Abos mit der Zustellung genau einmal pro Region verbraucht wurden.
- Anzahl der Nachrichten, die bei Verwendung von Abos mit aktivierter „Genau einmal“-Zustellung pro Region bestätigt oder deren Frist verlängert wurde.
Weitere Informationen zu diesen Kontingenten finden Sie in der Tabelle im Thema Kontingente.
Genau einmal zugestellt und geordnete Abos
Pub/Sub unterstützt die genau einmalige Zustellung mit sortierter Zustellung.
Wenn Sie die Sortierung mit der genau einmal erfolgenden Zustellung verwenden, erwartet Pub/Sub, dass die Bestätigungen in der richtigen Reihenfolge sind. Wenn die Bestätigungen nicht in der richtigen Reihenfolge sind, schlägt der Dienst die Anfragen mit temporären Fehlern fehl. Wenn die Bestätigungsfrist abläuft, bevor eine ordnungsgemäße Bestätigung für die Zustellung erfolgt, erhält der Client eine erneute Zustellung der Nachricht. Wenn Sie die Sortierung mit der Zustellung genau einmal verwenden, ist der Clientdurchsatz daher auf etwa tausend Nachrichten pro Sekunde begrenzt.
Genau einmal zugestellt und Push-Abos
Pub/Sub unterstützt die genau einmalige Zustellung nur mit Pull-Abos.
Clients, die Nachrichten von den Push-Abos nutzen, bestätigen die Nachrichten, indem sie auf die Push-Anfragen mit einer Erfolgsantwort antworten. Clients wissen jedoch nicht, ob das Pub/Sub-Abo die Antwort erhalten und verarbeitet hat. Das unterscheidet sich von Pull-Abos, bei denen Bestätigungsanfragen von den Clients initiiert werden und das Pub/Sub-Abo antwortet, wenn die Anfrage erfolgreich verarbeitet wurde. Aus diesem Grund eignen sich die genau einmal-Semantiken nicht gut für Push-Abos.
Wichtige Informationen
Wenn beim Erstellen eines Abos keine Frist für die Bestätigung angegeben wird, gilt für Abos mit aktivierter Zustellung genau einmal eine Standardfrist von 60 Sekunden.
Längere Standardfristen für die Bestätigung helfen, eine erneute Zustellung aufgrund von Netzwerkereignissen zu vermeiden. Bei unterstützten Clientbibliotheken wird die Standardfrist für die Bestätigung von Abos nicht verwendet.
Bei Abos mit der genau einmaligen Zustellung ist die Latenz zwischen Veröffentlichung und Abo deutlich höher als bei regulären Abos.
Wenn Sie einen hohen Durchsatz benötigen, müssen Ihre Clients für die „Genau einmal“-Auslieferung auch Streaming-Pull verwenden.
Ein Abo kann aufgrund von Duplikaten auf der Veröffentlichungsseite auch dann mehrere Kopien derselben Nachricht erhalten, wenn die Zustellung genau einmal aktiviert ist. Duplikate auf Veröffentlichungsseite können auf mehrere eindeutige Veröffentlichungswiederholungen durch den Veröffentlichungsclient oder den Pub/Sub-Dienst zurückzuführen sein. Mehrere eindeutige Veröffentlichungen durch den Publish-Client bei mehreren Versuchen führen zu erneuten Übermittlungen mit unterschiedlichen Nachrichten-IDs. Mehrere eindeutige Veröffentlichungen durch den Pub/Sub-Dienst, um auf eine Client-Veröffentlichungsanfrage zu reagieren, führen zu erneuten Übermittlungen mit denselben Nachrichten-IDs.
Sie können fehlgeschlagene Abfragen in
subscription/exactly_once_warning_count
wiederholen. Die unterstützten Clientbibliotheken wiederholen diese automatisch. Fehler im Zusammenhang mit ungültigen Bestätigungs-IDs können jedoch nicht wiederholt werden.