In diesem Dokument finden Sie einen Überblick über ein Pull-Abo, seinen Workflow und die zugehörigen Properties.
Bei einem Pull-Abo fordert ein Abonnentenclient Nachrichten vom Pub/Sub-Server an.
Für den Pull-Modus kann eine der beiden Dienst-APIs verwendet werden: Pull oder StreamingPull. Zum Ausführen der ausgewählten API können Sie eine von Google bereitgestellte Clientbibliothek der höheren Ebene oder eine automatisch generierte Clientbibliothek der unteren Ebene auswählen. Außerdem können Sie zwischen asynchroner und synchroner Nachrichtenverarbeitung wählen.
Hinweise
Bevor Sie dieses Dokument lesen, sollten Sie mit Folgendem vertraut sein:
Funktionsweise von Pub/Sub und die verschiedenen Pub/Sub-Begriffe
Die verschiedenen Arten von Abos, die Pub/Sub unterstützt, und warum Sie ein Pull-Abo verwenden sollten.
Workflow für Pull-Abos
Bei einem Pull-Abo initiiert der Abonnentenclient Anfragen an einen Pub/Sub-Server, um Nachrichten abzurufen. Der Abonnentenclient verwendet eine der folgenden APIs:
Die meisten Abonnenten-Clients stellen diese Anfragen nicht direkt. Stattdessen nutzen die Clients die von Google Cloud bereitgestellte Clientbibliothek, die intern Streaming-Pull-Anfragen ausführt und Nachrichten asynchron zustellt. Für einen Abonnentenclient, der mehr Kontrolle darüber haben möchte, wie Nachrichten abgerufen werden, verwendet Pub/Sub eine Low-Level- und automatisch generierte gRPC-Bibliothek. Diese Bibliothek stellt Pull- oder Streaming-Pull-Anfragen direkt. Diese Anfragen können synchron oder asynchron sein.
Die folgenden beiden Bilder zeigen den Workflow zwischen einem Abonnentenclient und einem Pull-Abo.
Pull-Workflow
Der Pull-Workflow sieht so aus und bezieht sich auf Abbildung 1:
- Der Abonnentenclient ruft explizit die
pull
-Methode auf, die Nachrichten zur Zustellung anfordert. Diese Anfrage ist diePullRequest
, wie auf dem Bild zu sehen. Der Pub/Sub-Server antwortet mit null oder mehr Nachrichten und Bestätigungs-IDs. Eine Antwort ohne Nachrichten oder mit einem Fehler bedeutet nicht unbedingt, dass keine Nachrichten zum Empfangen verfügbar sind. Diese Antwort ist die
PullResponse
in der Abbildung.Der Abonnentenclient ruft explizit die Methode
acknowledge
auf. Der Client verwendet die zurückgegebene Bestätigungs-ID, um zu bestätigen, dass die Nachricht verarbeitet wurde und nicht noch einmal zugestellt werden muss.
Für eine einzelne Streaming-Pull-Anfrage kann ein Abonnentenclient aufgrund der offenen Verbindung mehrere Antworten zurückgeben. Für jeden Pull-Request wird dagegen nur eine Antwort zurückgegeben.
Eigenschaften eines Pull-Abos
Die Eigenschaften, die Sie für ein Pull-Abo konfigurieren, bestimmen, wie Sie Nachrichten in Ihr Abo schreiben. Weitere Informationen finden Sie unter Abo-Attribute.
Pub/Sub-Dienst-APIs
Für das Pub/Sub-Pull-Abo kann eine der folgenden beiden APIs zum Abrufen von Nachrichten verwendet werden:
- Pull
- StreamingPull
Verwenden Sie unary Acknowledge- und ModifyAckDeadline-RPCs, wenn Sie Nachrichten über diese APIs empfangen. Die beiden Pub/Sub APIs werden in den folgenden Abschnitten beschrieben.
StreamingPull API
Wo möglich, verwenden die Pub/Sub-Clientbibliotheken StreamingPull für maximalen Durchsatz und niedrigste Latenz. Auch wenn Sie die StreamingPull API vielleicht niemals direkt verwenden, ist es wichtig, zu wissen, wie sie sich von der Pull API unterscheidet.
Die StreamingPull API benötigt eine bidirektionale Verbindung, um mehrere Nachrichten zu empfangen, sobald diese verfügbar werden. Der Workflow sieht so aus:
Der Client sendet eine Anfrage an den Server, um eine Verbindung herzustellen. Wenn das Verbindungskontingent überschritten wird, gibt der Server den Fehler „Ressource erschöpft“ zurück. Die Clientbibliothek wiederholt automatisch die Anfragen, bei denen das Kontingent überschritten wurde.
Wenn kein Fehler auftritt oder das Verbindungskontingent wieder verfügbar ist, sendet der Server kontinuierlich Nachrichten an den verbundenen Client.
Wenn das Durchsatzkontingent überschritten wird, sendet der Server keine Nachrichten mehr. Die Verbindung ist jedoch nicht unterbrochen. Sobald wieder ein ausreichendes Durchsatzkontingent verfügbar ist, wird der Stream fortgesetzt.
Die Verbindung wird schließlich vom Client oder vom Server geschlossen.
Die StreamingPull API hält eine offene Verbindung aufrecht. Die Pub/Sub-Server schließen die Verbindung nach einem bestimmten Zeitraum regelmäßig, um eine lang andauernde Sticky-Verbindung zu vermeiden. Die Clientbibliothek öffnet eine StreamingPull-Verbindung automatisch wieder.
Nachrichten werden an die Verbindung gesendet, sobald sie verfügbar sind. Die StreamingPull API minimiert so die Latenz und maximiert den Durchsatz für Nachrichten.
Weitere Informationen zu den StreamingPull-RPC-Methoden StreamingPullRequest und StreamingPullResponse
Pull API
Diese API ist eine traditionelle unary RPC, die auf einem Anfrage- und Antwortmodell basiert. Eine einzelne Pull-Antwort entspricht einer einzelnen Pull-Anfrage. Der Workflow sieht so aus:
Der Client sendet eine Anfrage an den Server. Wenn das Durchsatzkontingent überschritten wird, gibt der Server einen Fehler zurück, dass die Ressourcen erschöpft sind.
Wenn kein Fehler vorliegt oder das Durchsatzkontingent wieder verfügbar ist, antwortet der Server mit null oder mehr Nachrichten und Bestätigungs-IDs.
Bei der Verwendung der unary Pull API bedeutet eine Antwort ohne Nachrichten oder mit einem Fehler nicht unbedingt, dass keine Nachrichten zum Empfangen verfügbar sind.
Die Verwendung der Pull API garantiert keine niedrige Latenz und keinen hohen Durchsatz von Nachrichten. Um mit der Pull API einen hohen Durchsatz und eine niedrige Latenz zu erzielen, müssen mehrere gleichzeitig ausstehende Anfragen vorhanden sein. Neue Anfragen werden erstellt, wenn alte Anfragen eine Antwort erhalten. Das Entwerfen einer solchen Lösung ist fehleranfällig und schwer zu verwalten. Für solche Anwendungsfälle empfehlen wir die StreamingPull API.
Verwenden Sie die Pull API anstelle der StreamingPull API nur, wenn Sie Folgendes genau steuern möchten:
- Die Anzahl der Nachrichten, die der Abonnentenclient verarbeiten kann
- Arbeitsspeicher und Ressourcen des Clients
Sie können diese API auch verwenden, wenn Ihr Abonnent ein Proxy zwischen Pub/Sub und einem anderen Dienst ist, der eher pull-orientiert arbeitet.
Weitere Informationen zu den Pull-REST-Methoden: Methode: projects.subscriptions.pull
Weitere Informationen zu den Pull-RPC-Methoden PullRequest und PullResponse
Arten von Nachrichtenverarbeitungsmodi
Wähle für deine Abonnenten-Clients einen der folgenden Pull-Modi aus.
Asynchroner Pull-Modus
Im asynchronen Pull-Modus wird der Empfang von Nachrichten von der Verarbeitung von Nachrichten in einem Abonnentenclient entkoppelt. Dieser Modus ist die Standardeinstellung für die meisten Abonnenten-Clients. Für den asynchronen Pull-Modus kann die StreamingPull API oder die unary Pull API verwendet werden. Für den asynchronen Pull können auch die Clientbibliothek der höheren Ebene oder die automatisch generierte Clientbibliothek der unteren Ebene verwendet werden.
Weitere Informationen zu Clientbibliotheken finden Sie weiter unten in diesem Dokument.
Synchroner Pull-Modus
Im synchronen Pull-Modus erfolgen Empfang und Verarbeitung von Nachrichten nacheinander und sind nicht voneinander entkoppelt. Ähnlich wie bei StreamingPull- und unary Pull-APIs bietet die asynchrone Verarbeitung eine geringere Latenz und einen höheren Durchsatz als die synchrone Verarbeitung.
Verwenden Sie den synchronen Pull-Modus nur für Anwendungen, bei denen niedrige Latenz und hoher Durchsatz im Vergleich zu anderen Anforderungen nicht die wichtigsten Faktoren sind. Eine Anwendung kann beispielsweise nur das synchrone Programmiermodell verwenden. Oder eine Anwendung mit Ressourceneinschränkungen erfordert eine genauere Steuerung von Arbeitsspeicher, Netzwerk oder CPU. Verwenden Sie in solchen Fällen den synchronen Modus mit der unary Pull API.
Pub/Sub-Clientbibliotheken
Pub/Sub bietet eine automatisch generierte Clientbibliothek auf höherer und niedriger Ebene.
Hochrangige Pub/Sub-Clientbibliothek
Die allgemeine Clientbibliothek bietet Optionen zur Steuerung der Fristen für die Bestätigung mithilfe der Freigabeverwaltung. Diese Optionen sind detaillierter als wenn Sie die Fristen für die Bestätigung über die Console oder die Befehlszeile auf Aboebene konfigurieren. Die Clientbibliothek der höheren Ebene unterstützt auch Funktionen wie die geordnete Zustellung, die Zustellung genau einmal und die Ablaufsteuerung.
Wir empfehlen die Verwendung von asynchronem Pull und der StreamingPull API mit der Clientbibliothek der höheren Ebene. Nicht alle Sprachen, die für Google Cloud unterstützt werden, unterstützen auch die Pull API in der Clientbibliothek der höheren Ebene.
Informationen zur Verwendung der Clientbibliotheken der höheren Ebene finden Sie unter Pub/Sub-Clientbibliotheken.
Automatisch generierte Pub/Sub-Clientbibliothek auf niedriger Ebene
Eine Clientbibliothek auf niedriger Ebene ist verfügbar, wenn Sie die Pull API direkt verwenden müssen. Sie können die synchrone oder asynchrone Verarbeitung mit der automatisch generierten Low-Level-Clientbibliothek verwenden. Wenn Sie die automatisch generierte Clientbibliothek auf niedriger Ebene verwenden, müssen Sie Funktionen wie die geordnete Zustellung, die Zustellung genau einmal, die Ablaufsteuerung und die Leasingverwaltung manuell codieren.
Sie können das synchrone Verarbeitungsmodell verwenden, wenn Sie die automatisch generierte Clientbibliothek für alle unterstützten Sprachen verwenden. Sie können die automatisch generierte Clientbibliothek auf niedriger Ebene und den synchronen Pull verwenden, wenn die direkte Verwendung der Pull API sinnvoll ist. Möglicherweise haben Sie beispielsweise eine vorhandene Anwendungslogik, die auf diesem Modell basiert.
Informationen zur direkten Verwendung der automatisch generierten Clientbibliotheken auf niedriger Ebene finden Sie unter Pub/Sub APIs – Übersicht.
Codebeispiele für Clientbibliotheken
Codebeispiele für StreamingPull und Clientbibliotheken auf höherer Ebene
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.
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.
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.
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.
Benutzerdefinierte Attribute mit der Clientbibliothek der höheren Ebene abrufen
In den folgenden Beispielen wird gezeigt, wie Nachrichten asynchron abgerufen und die benutzerdefinierten Attribute aus den Metadaten abgerufen werden.
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.
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.
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.
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.
Fehler mit der Clientbibliothek der höheren Ebene behandeln
In den folgenden Beispielen wird dargestellt, wie Fehler behandelt werden, die beim Abonnieren von Nachrichten auftreten können.
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.
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.
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.
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.
Ruby
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.
Codebeispiele für unäres Pull
Hier sehen Sie Beispielcode für die Pull-Zustellung und die Bestätigung einer festen Anzahl von Nachrichten:
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.
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.
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.
PHP
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.
Protokoll
Anfrage:
POST https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription:pull
{
"returnImmediately": "false",
"maxMessages": "1"
}
Antwort:
200 OK
{
"receivedMessages": [{
"ackId": "dQNNHlAbEGEIBERNK0EPKVgUWQYyODM2LwgRHFEZDDsLRk1SK...",
"message": {
"data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
"messageId": "19917247034"
}
}]
}
Anfrage:
POST https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription:acknowledge
{
"ackIds": [
"dQNNHlAbEGEIBERNK0EPKVgUWQYyODM2LwgRHFEZDDsLRk1SK..."
]
}
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.
Pub/Sub stellt eine Liste von Nachrichten bereit. Wenn die Liste mehrere Nachrichten enthält, sortiert Pub/Sub die Nachrichten mit demselben Reihenfolgeschlüssel. Beachten Sie dabei Folgendes:
Wenn Sie in der Anfrage einen Wert für
max_messages
festlegen, ist nicht garantiert, dassmax_messages
Nachrichten zurückgegeben werden, auch wenn sich so viele Nachrichten im Backlog befinden. Die Pub/Sub Pull API gibt möglicherweise weniger alsmax_messages
zurück, um die Übermittlungslatenz für Nachrichten zu reduzieren, die zur Übermittlung bereitstehen.Eine Pull-Antwort, die keine Nachrichten enthält, darf nicht als Hinweis darauf gewertet werden, dass sich keine Nachrichten im Backlog befinden. Es ist möglich, dass Sie eine Antwort mit 0 Nachrichten erhalten und eine nachfolgende Anfrage Nachrichten zurückgibt.
Voraussetzung für die Effektivität des unary-Pull-Modus ist, dass eine hohe Zahl gleichzeitig ausstehender Pull-Anfragen vorliegt. Je höher der Durchsatz des Themas wird, desto mehr Pull-Anfragen werden benötigt. Im Allgemeinen ist der StreamingPull-Modus für latenzempfindliche Anwendungen zu bevorzugen.
Kontingente und Limits
Sowohl Pull- als auch StreamingPull-Verbindungen unterliegen Kontingenten und Limits. Weitere Informationen finden Sie unter Pub/Sub-Kontingente und Limits.
Nächste Schritte
Erstellen Sie ein Pull-Abo für Ihr Thema.
Erstellen oder ändern Sie ein Abo mit der gcloud CLI.
Mit REST APIs ein Abo erstellen oder ändern
Mit RPC APIs ein Abo erstellen oder ändern