Dieses Dokument bietet eine Übersicht über ein Pull-Abo, seinen Workflow und die zugehörigen Attribute.
In einem Pull-Abo fordert ein Abonnentenclient Nachrichten vom Pub/Sub-Server an.
Im Pull-Modus kann eine der beiden Dienst-APIs verwendet werden: Pull oder StreamingPull. Zum Ausführen der ausgewählten API können Sie eine übergeordnete Clientbibliothek von Google oder eine automatisch generierte untergeordnete Clientbibliothek auswählen. Sie können auch zwischen der asynchronen und synchronen Nachrichtenverarbeitung wählen.
Hinweise
Machen Sie sich vor dem Lesen dieses Dokuments mit Folgendem vertraut:
Funktionsweise von Pub/Sub und die verschiedenen Pub/Sub-Begriffe
Welche Arten von Abos von Pub/Sub unterstützt werden und warum Sie ein Pull-Abo verwenden sollten
Workflow für Pull-Abos
Bei einem Pull-Abo initiiert Ihr 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 stützen die Clients die von Google Cloud bereitgestellte allgemeine Clientbibliothek, die Streaming-Pull-Anfragen intern ausführt und Nachrichten asynchron sendet. Für einen Abonnentenclient, der mehr Kontrolle darüber benötigt, wie Nachrichten abgerufen werden, verwendet Pub/Sub eine untergeordnete und automatisch generierte gRPC-Bibliothek. Diese Bibliothek führt Pull- oder Streaming-Pull-Anfragen direkt aus. 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 Methode
pull
auf, die Nachrichten zur Zustellung anfordert. Diese Anfrage ist derPullRequest
, wie in der Abbildung dargestellt. Der Pub/Sub-Server antwortet mit null oder mehr Nachrichten und Bestätigungs-IDs. Eine Antwort mit null Nachrichten oder einem Fehler bedeutet nicht unbedingt, dass keine Nachrichten zum Empfangen verfügbar sind. Diese Antwort ist der
PullResponse
, wie in der Abbildung dargestellt.Der Abonnentenclient ruft explizit die Methode
acknowledge
auf. Der Client bestätigt anhand der zurückgegebenen Bestätigungs-ID, dass die Nachricht verarbeitet wurde und nicht noch einmal zugestellt werden muss.
Für eine einzelne Streaming-Pull-Anfrage können bei einem Abonnentenclient aufgrund der offenen Verbindung mehrere Antworten zurückgegeben werden. Im Gegensatz dazu wird für jede Pull-Anfrage nur eine Antwort zurückgegeben.
Attribute eines Pull-Abos
Die Attribute, die Sie für ein Pull-Abo konfigurieren, bestimmen, wie Nachrichten in Ihr Abo geschrieben werden. Weitere Informationen findest du unter Aboattribute.
APIs für Pub/Sub-Dienste
Das Pub/Sub-Pull-Abo kann eine der folgenden beiden APIs zum Abrufen von Nachrichten verwenden:
- Pull
- StreamingPull
Verwenden Sie unäre Bestätigungs- und ModifyAckDeadline-RPCs, wenn Sie Nachrichten über diese APIs empfangen. Die beiden Pub/Sub APIs werden auf den folgenden Tabs beschrieben.
StreamingPull API
Wenn möglich, verwenden die Pub/Sub-Clientbibliotheken StreamingPull für maximalen Durchsatz und niedrigste Latenz. Auch wenn Sie die StreamingPull API möglicherweise nie direkt verwenden, ist es wichtig zu wissen, wie sie sich von der Pull API unterscheidet.
Die StreamingPull API benötigt eine persistente bidirektionale Verbindung, um mehrere Nachrichten zu empfangen, sobald sie verfügbar sind. 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 die Fehler aufgrund überschrittener Kontingentüberschreitungen automatisch.
Wenn kein Fehler auftritt oder das Verbindungskontingent wieder verfügbar ist, sendet der Server kontinuierlich Nachrichten an den verbundenen Client.
Wenn oder wenn das Durchsatzkontingent überschritten wird, sendet der Server keine Nachrichten mehr. Die Verbindung ist jedoch nicht unterbrochen. Sobald wieder genügend Durchsatzkontingent verfügbar ist, wird der Stream fortgesetzt.
Der Client oder der Server schließt die Verbindung.
Die StreamingPull API hält eine offene Verbindung aufrecht. Die Pub/Sub-Server schließen die Verbindung wiederholt nach einem bestimmten Zeitraum, um eine dauerhafte Verbindung mit langer Ausführungszeit zu vermeiden. Die Clientbibliothek stellt eine StreamingPull-Verbindung automatisch wieder her.
Nachrichten werden an die Verbindung gesendet, wenn sie verfügbar sind. Die StreamingPull API minimiert auf diese Weise die Latenz und maximiert den Durchsatz für Nachrichten.
Weitere Informationen zu StreamingPull-REST-Methoden: StreamingPullRequest und StreamingPullResponse
Weitere Informationen zu StreamingPull-RPC-Methoden: StreamingPullRequest und StreamingPullResponse
Pull-API
Diese API ist ein traditioneller unärer RPC, der auf einem Anfrage- und Antwortmodell basiert. Eine einzelne Pull-Antwort entspricht einer einzelnen Pull-Anfrage. Der Workflow lautet wie folgt:
Der Client sendet eine Anfrage an den Server. Wenn das Durchsatzkontingent überschritten wird, gibt der Server einen Fehler vom Typ „Ressource erschöpft“ zurück.
Wenn kein Fehler auftritt oder das Durchsatzkontingent wieder verfügbar ist, antwortet der Server mit null oder mehr Nachrichten und Bestätigungs-IDs.
Bei Verwendung der unären Pull API bedeutet eine Antwort mit null Nachrichten oder einem Fehler nicht unbedingt, dass keine Nachrichten zum Empfangen verfügbar sind.
Die Verwendung der Pull API garantiert keine niedrige Latenz und einen hohen Nachrichtendurchsatz. Wenn Sie einen hohen Durchsatz und eine niedrige Latenz mit der Pull API erzielen möchten, müssen Sie mehrere gleichzeitig ausstehende Anfragen haben. Neue Anfragen werden erstellt, wenn alte Anfragen eine Antwort erhalten. Die Architektur einer solchen Lösung ist fehleranfällig und schwer zu verwalten. Für solche Anwendungsfälle empfehlen wir die Verwendung der StreamingPull API.
Verwenden Sie die Pull API nur dann anstelle der StreamingPull API, wenn Sie strenge Kontrolle über Folgendes benötigen:
- 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 Pull-REST-Methoden finden Sie unter Method: projects.subscriptions.pull.
Weitere Informationen zu den Pull-RPC-Methoden: PullRequest und PullResponse.
Arten von Modi für die Nachrichtenverarbeitung
Wählen Sie einen der folgenden Pull-Modi für Ihre Abonnentenclients aus.
Asynchroner Pull-Modus
Im asynchronen Pull-Modus entkoppelt der Empfang von Nachrichten von der Verarbeitung von Nachrichten in einem Abonnentenclient. Dieser Modus ist für die meisten Abonnentenclients die Standardeinstellung. Der asynchrone Pull-Modus kann die StreamingPull API oder die unäre Pull API verwenden. Für den asynchronen Modus kann auch die übergeordnete oder automatisch generierte Clientbibliothek verwendet werden.
Weitere Informationen zu Clientbibliotheken finden Sie weiter unten in diesem Dokument.
Synchroner Pull-Modus
Im synchronen Pull-Modus erfolgen der Empfang und die Verarbeitung von Nachrichten nacheinander und sind nicht voneinander entkoppelt. Ähnlich wie StreamingPull im Vergleich zu unären Pull APIs bietet die asynchrone Verarbeitung daher 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 einigen anderen Anforderungen nicht die wichtigsten Faktoren sind. Beispielsweise kann eine Anwendung auf die Verwendung des synchronen Programmiermodells beschränkt sein. Oder eine Anwendung mit Ressourceneinschränkungen erfordert möglicherweise eine genauere Kontrolle über Arbeitsspeicher, Netzwerk oder CPU. Verwenden Sie in solchen Fällen den synchronen Modus mit der unären Pull API.
Pub/Sub-Clientbibliotheken
Pub/Sub bietet eine allgemeine und eine untergeordnete Clientbibliothek.
Übergeordnete Pub/Sub-Clientbibliothek
Die allgemeine Clientbibliothek bietet Optionen zum Steuern der Bestätigungsfristen mithilfe der Freigabeverwaltung. Diese Optionen sind detaillierter als beim Konfigurieren der Bestätigungsfristen mithilfe der Console oder der Befehlszeile auf Aboebene. Die übergeordnete Clientbibliothek unterstützt auch Funktionen wie die geordnete Zustellung, die genau einmalige Übermittlung und die Ablaufsteuerung.
Wir empfehlen, den asynchronen Pull-Modus und die StreamingPull API mit der übergeordneten Clientbibliothek zu verwenden. Nicht alle für Google Cloud unterstützten Sprachen unterstützen auch die Pull API in der allgemeinen Clientbibliothek.
Informationen zur Verwendung der allgemeinen Clientbibliotheken finden Sie unter Pub/Sub-Clientbibliotheken.
Automatisch generierte Low-Level-Pub/Sub-Clientbibliothek
Wenn Sie die Pull API direkt verwenden müssen, steht eine Low-Level-Clientbibliothek zur Verfügung. Sie können die synchrone oder asynchrone Verarbeitung mit der automatisch generierten untergeordneten Clientbibliothek verwenden. Wenn Sie die automatisch generierte Clientbibliothek auf unterer Ebene verwenden, müssen Sie Features wie die bestellte Zustellung, die genau einmalige Zustellung, die Ablaufsteuerung und die Freigabeverwaltung manuell codieren.
Sie können das Modell für die synchrone Verarbeitung nutzen, wenn Sie die automatisch generierte untergeordnete Clientbibliothek für alle unterstützten Sprachen nutzen. Sie können die automatisch generierte untergeordnete Clientbibliothek und die synchrone Pull-Funktion verwenden, wenn die direkte Verwendung der Pull API sinnvoll ist. Vielleicht haben Sie bereits eine 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 die Clientbibliothek
Codebeispiele für StreamingPull und allgemeine Clientbibliotheken
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.
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.
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.
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.
Benutzerdefinierte Attribute mithilfe der allgemeinen Clientbibliothek abrufen
Die folgenden Beispiele zeigen, wie Nachrichten asynchron abgerufen und benutzerdefinierte 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 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.
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.
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.
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.
Fehler mithilfe der allgemeinen Clientbibliothek behandeln
Die folgenden Beispiele zeigen, wie Fehler behoben 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.
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.
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.
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.
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 zur Pub/Sub Go API.
Unäre Pull-Codebeispiele
Im Folgenden sehen Sie Beispielcode zum pull und Bestätigen 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 zur 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 zur 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 zur 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 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.
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 zur Pub/Sub Python API.
Pub/Sub stellt eine Liste von Nachrichten bereit. Wenn die Liste mehrere Nachrichten enthält, ordnet Pub/Sub die Nachrichten mit demselben Sortierschlüssel an. Im Folgenden sind einige wichtige Vorbehalte aufgeführt:
Das Festlegen eines Werts für
max_messages
in der Anfrage garantiert nicht, dassmax_messages
zurückgegeben wird, auch wenn sich so viele Nachrichten im Rückstand befinden. Die Pub/Sub Pull API gibt möglicherweise weniger alsmax_messages
zurück, um die Zustellungslatenz für Nachrichten zu reduzieren, die leicht zugestellt werden können.Eine Pull-Antwort mit 0 Nachrichten darf nicht als Indikator dafür verwendet werden, dass sich keine Nachrichten im Rückstand befinden. Sie können eine Antwort mit 0 Nachrichten und eine nachfolgende Anfrage erhalten, die Nachrichten zurückgibt.
Wenn Sie mit dem unären Pull-Modus eine niedrige Latenz bei der Nachrichtenzustellung erreichen möchten, ist es wichtig, dass viele gleichzeitig ausstehende Pull-Anfragen vorliegen. Je höher der Durchsatz des Themas ist, 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.
Abo mit der gcloud CLI erstellen oder ändern
Abo mit REST APIs erstellen oder ändern
Abo mit RPC APIs erstellen oder ändern.