Auf dieser Seite wird erläutert, wie Sie Nachrichten mit der genau einmaligen Semantik empfangen und bestätigen. Nur der Pull-Abotyp unterstützt die genau einmalige Zustellung, einschließlich Abonnenten, die die StreamingPull API verwenden.
Push- und Exportabos unterstützen keine genau einmalige Zustellung.
Empfohlene Clientbibliotheksversionen
- Die beste Leistung erzielen Sie mit der neuesten Version der Clientbibliothek: Python Version 2.13.6 oder höher, Java Version 1.120.11 oder höher, PHP Version 1.39.0 oder höher, C#, Version 3.2.0 oder höher, C++,{/1.1.0 oder höher, {1.1.5,{/1.2.2 oder höher, {1.1.2,} oder höher, {1.1.2.1.2 oder höher, {10.2.1.5, oder höher, {1.1.2,1.2, oder höher, v1.1.2, oder höher, v1.1.2, oder höher.v2.1.0
Genau einmalige Übermittlung
Pub/Sub unterstützt die genau einmalige Übermittlung innerhalb einer Cloud-Region anhand einer von Pub/Sub definierten eindeutigen Nachrichten-ID.
Wenn das Feature aktiviert ist, bietet Pub/Sub Folgendes:
Nachdem die Nachricht bestätigt wurde, findet keine erneute Übermittlung statt.
Solange eine Nachricht noch nicht zugestellt wurde, findet keine erneute Übermittlung statt. Eine Nachricht gilt als ausstehend, bis die Bestätigungsfrist abgelaufen oder die Nachricht bestätigt wird.
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 zum Bestätigen der Nachricht verwendet werden. Alle Anfragen mit einer vorherigen Bestätigungs-ID schlagen fehl.
Erneute oder doppelte Auslieferung
Es ist wichtig, den Unterschied zwischen erwarteten und unerwarteten neuen Bereitstellungen zu verstehen.
Eine erneute Zustellung kann entweder aufgrund einer vom Client initiierten negativen Bestätigung einer Nachricht erfolgen oder wenn der Client die Bestätigungsfrist der Nachricht nicht vor Ablauf der Bestätigungsfrist verlängert. Erneute Sendungen gelten als gültig und das System funktioniert wie vorgesehen.
Informationen zur Fehlerbehebung bei erneuten Sendungen finden Sie unter Umgang mit Duplikaten und Erzwingen von Wiederholungsversuchen.
Ein Duplikat liegt vor, wenn eine Nachricht nach einer erfolgreichen Bestätigung oder vor Ablauf der Bestätigungsfrist noch einmal gesendet wird.
Eine erneut zugestellte Nachricht behält bei erneuten Übermittlungsversuchen dieselbe Nachrichten-ID.
Abos mit genau einmaliger Zustellung erhalten keine doppelten Zustellungen.
Unterstützung für genau einmalige Übermittlung in Clientbibliotheken
Unterstützte Clientbibliotheken haben eine Schnittstelle für die Bestätigung mit einer Antwort (Beispiel: Go). Mit dieser Schnittstelle können Sie prüfen, ob die Bestätigungsanfrage erfolgreich war. Wenn die Bestätigungsanfrage erfolgreich war, werden die Clients garantiert nicht noch einmal gesendet. Wenn die Bestätigungsanfrage fehlschlägt, können die Clients mit einer erneuten Übermittlung rechnen.
Clients können die unterstützten Clientbibliotheken auch ohne die Bestätigungsschnittstelle verwenden. In solchen Fällen können die Bestätigungsfehler jedoch dazu führen, dass Nachrichten im Hintergrund noch einmal zugestellt werden.
Unterstützte Clientbibliotheken haben Schnittstellen zum Festlegen der minimalen Lease-Verlängerungszeit (Beispiel: Go). Sie müssen den Wert für die Mindestfreigabeerweiterung auf einen hohen Wert setzen, um zu vermeiden, dass die Bestätigung abläuft. Der Maximalwert beträgt 600 Sekunden.
Die Standardwerte und der Bereich für die Variablen, die sich auf die genau einmalige Übermittlung beziehen, und die Namen der Variablen können sich je nach Clientbibliothek unterscheiden. In der Java-Clientbibliothek wird beispielsweise die genau einmalige Übermittlung durch die folgenden Variablen gesteuert.
Variable | Beschreibung | Wert |
---|---|---|
setEnableExactlyOnceDelivery |
Aktiviert oder deaktiviert die genau einmalige Zustellung. | true oder false Standard=false |
minDurationPerAckExtension |
Die minimale Zeit in Sekunden, die zum Verlängern der Bestätigungsfrist für Änderungen verwendet werden soll. | Bereich=0 bis 600 Standard=keine |
maxDurationPerAckExtension |
Die maximale Zeit in Sekunden, die zum Verlängern der Bestätigungsfrist für Änderungen verwendet werden soll. | Bereich=0 bis 600 Standard=keine |
Bei einer genau einmaligen 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 eine neuere Zustellung möglicherweise bereits in Bearbeitung ist. Dies ist so konzipiert, dass eine
genau einmalige Übermittlung erfolgt. Sie sehen dann, dass die Anfragen acknowledgment
und ModifyAckDeadline
eine INVALID_ARGUMENT
-Antwort zurückgeben. Wenn die genau einmalige Zustellung deaktiviert ist, wird bei diesen Anfragen 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 setzen.
Abos mit genau einmaliger Zustellung erstellen
Sie können ein Abo mit genau einmaliger Zustellung mithilfe 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 genau einmaliger Zustellung:
Ö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 Bereich Genau einmalige Zustellung die Option Genau einmalige Zustellung aktivieren aus.
Klicken Sie auf Erstellen.
gcloud
Verwenden Sie den Befehl gcloud pubsub subscriptions create
mit dem Flag --enable-exactly-once-delivery
, um ein Pull-Abo mit genau einmaliger Zustellung zu erstellen:
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
Verwenden Sie die Methode projects.subscriptions.create
, um ein Abo mit genau einmaliger Zustellung zu erstellen.
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
Geben Sie dies im Anfragetext an, um ein Pull-Abo mit genau einmaliger Zustellung zu erstellen:
{ "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 zur Pub/Sub C# API.
Einfach loslegen (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 zur 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 zur 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 zur 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 zur 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 zur 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 zur 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 Pub/Sub PHP API.
Mit genau einmaliger Nachrichtenzustellung abonnieren
Im Folgenden finden Sie einige Codebeispiele für das Abonnieren mit genau einmaliger Zustellung unter Verwendung der Clientbibliothek.
Pull-Abo
Go
Folgen Sie der Einrichtungsanleitung für Go in der Pub/Sub-Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Go API.
Richten Sie 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 Pub/Sub-Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Java API.
Richten Sie 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 Pub/Sub-Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Node.js API.
Richten Sie 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 Pub/Sub-Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub PHP API.
Richten Sie 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 Pub/Sub-Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Python API.
Richten Sie 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 Pub/Sub-Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Ruby API.
Richten Sie 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 Pub/Sub-Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub C++ API.
Richten Sie 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 Pub/Sub-Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub C# API.
Richten Sie 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)
Folgen Sie der Einrichtungsanleitung für Node.js in der Pub/Sub-Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel ausprobieren. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Node.js API.
Richten Sie 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 genau einmaliger Zustellung überwachen
Mit dem Messwert subscription/exactly_once_warning_count
wird die Anzahl der Ereignisse erfasst, die zu möglichen erneuten Übermittlungen (gültig oder doppelt) führen können. Dieser Messwert zählt, wie oft Pub/Sub Anfragen für Bestätigungs-IDs (ModifyAckDeadline
- oder acknowledgment
-Anfrage) nicht verarbeitet. Die Ursache für den Fehler kann server- oder clientbasiert sein. Wenn beispielsweise die Persistenzebene zur Verwaltung der genau einmaligen Übermittlungsinformationen nicht verfügbar ist, wäre dies 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.
Den Messwert verstehen
subscription/exactly_once_warning_count
erfasst Ereignisse, die zu tatsächlichen erneuten Übermittlungen führen können oder nicht. Je nach Clientverhalten kann dies ungenau sein. 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 ablaufenden Bestätigungs-IDs an. Das Ablaufdatum von Bestätigungs-IDs kann sowohl beiModifyAckDeadline
- als auch beiacknowledgment
-Anfragen zu Fehlern führen.Der Messwert
service.serviceruntime.googleapis.com/api/request_count
kann verwendet werden, um Fehler beiModifyAckDeadline
- oderacknowledgment
-Anfragen zu erfassen, wenn die Anfragen Google Cloud erreichen, aber nicht Pub/Sub erreichen. Es gibt Fehler, die dieser Messwert nicht erfasst, z. B. wenn Clients von Google Cloud getrennt werden.
Bei den meisten Fehlerereignissen, die wiederholt werden können, wiederholen unterstützte Clientbibliotheken die Anfrage automatisch.
Kontingente
Abos mit genau einmaliger Zustellung unterliegen zusätzlichen Kontingentanforderungen. Diese Kontingente werden erzwungen für:
- Anzahl der Nachrichten, die aus Abos mit aktivierter genau einmaliger Zustellung pro Region genutzt wurden.
- Anzahl der Nachrichten, die bestätigt wurden oder deren Frist verlängert wird, wenn Abos mit genau einmaliger Zustellung pro Region aktiviert sind.
Weitere Informationen zu diesen Kontingenten finden Sie in der Tabelle unter Kontingente.
Genau einmalige Lieferung und bestellte Abos
Pub/Sub unterstützt die genau einmalige Übermittlung mit der sortierten Zustellung.
Wenn die Sortierung mit genau einmaliger Zustellung verwendet wird, erwartet Pub/Sub, dass die Bestätigungen in der richtigen Reihenfolge sind. Wenn die Bestätigungen nicht in der richtigen Reihenfolge vorliegen, schlägt der Dienst die Anfragen mit temporären Fehlern fehl. Wenn die Bestätigungsfrist vor der Bestätigung der Zustellung abläuft, erhält der Client eine erneute Zustellung der Nachricht. Wenn Sie also die Sortierung mit genau einmaliger Zustellung verwenden, ist der Clientdurchsatz auf eine Reihenfolge von tausend Nachrichten pro Sekunde begrenzt.
Genau einmalige Zustellung und Push-Abos
Pub/Sub unterstützt die genau einmalige Zustellung nur mit Pull-Abos.
Clients, die Nachrichten aus Push-Abos verwenden, bestätigen die Nachrichten, indem sie auf Push-Anfragen mit einer erfolgreichen Antwort antworten. Clients wissen jedoch nicht, ob das Pub/Sub-Abo die Antwort erhalten und verarbeitet hat. Dies unterscheidet sich von Pull-Abos, bei denen Bestätigungsanfragen von den Clients initiiert werden und das Pub/Sub-Abo reagiert, wenn die Anfrage erfolgreich verarbeitet wurde. Aus diesem Grund passt die Semantik der genau einmaligen Zustellung nicht gut zu Push-Abos.
Wichtige Informationen
Wenn zum Zeitpunkt „CreateSubscription“ keine Bestätigungsfrist angegeben ist, haben Abos mit genau einmal aktivierter Zustellung eine standardmäßige Bestätigungsfrist von 60 Sekunden.
Längere Standardfristen für die Bestätigung sind von Vorteil, um eine erneute Zustellung aufgrund von Netzwerkereignissen zu vermeiden. Unterstützte Clientbibliotheken verwenden nicht das Standardzeitlimit für die Bestätigung von Abos.
Abos mit genau einmaliger Zustellung haben im Vergleich zu regulären Abos eine erheblich höhere Latenz von „Publish-to-Subscribe“.
Wenn Sie einen hohen Durchsatz benötigen, müssen Ihre Clients mit genau einmaliger Zustellung auch Streaming-Pull verwenden.
Aufgrund von Duplikaten auf der Seite der Veröffentlichung kann ein Abo mehrere Kopien derselben Nachricht erhalten, auch wenn die einmalige Zustellung aktiviert ist. Duplikate auf der Veröffentlichungsseite können auf mehrere einmalige Veröffentlichungsversuche durch den Publisher-Client oder den Pub/Sub-Dienst zurückzuführen sein. Mehrere eindeutige Veröffentlichungen durch den veröffentlichenden Client bei mehreren Wiederholungsversuchen führen zu erneuten Übermittlungen mit unterschiedlichen Nachrichten-IDs. Mehrere eindeutige Veröffentlichungen durch den Pub/Sub-Dienst führen zu erneuten Zustellungen mit denselben Nachrichten-IDs, um auf eine Clientveröffentlichungsanfrage zu antworten.
Sie können Fehler in
subscription/exactly_once_warning_count
wiederholen. Die unterstützten Clientbibliotheken wiederholen dies automatisch. Fehler im Zusammenhang mit ungültigen Bestätigungs-IDs können jedoch nicht wiederholt werden.