In diesem Dokument erfahren Sie mehr zum Veröffentlichen von Nachrichten.
Eine Publisher-Anwendung erstellt und sendet Nachrichten an ein Thema. Pub/Sub bietet die mindestens einmalige Nachrichtenzustellung und Best-Effort-Reihenfolge für bestehende Abonnenten.
Der allgemeine Ablauf für eine Publisher-Anwendung ist:
- Eine Nachricht mit den entsprechenden Daten erstellen.
- Sie senden eine Anfrage an den Pub/Sub-Server, um die Nachricht unter dem angegebenen Thema zu veröffentlichen.
Hinweise
Bevor Sie den Veröffentlichungsworkflow konfigurieren, müssen Sie die folgenden Aufgaben ausgeführt haben:
Erforderliche Rollen
Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Pub/Sub Publisher (roles/pubsub.publisher
) für das Thema zu gewähren, um die Berechtigungen zu erhalten, die Sie zum Veröffentlichen von Nachrichten zu einem Thema benötigen.
Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff verwalten.
Möglicherweise können Sie die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.
Sie benötigen zusätzliche Berechtigungen, um Themen und Abos zu erstellen oder zu aktualisieren.
Nachrichtenformat
Eine Nachricht besteht aus Feldern mit den Nachrichtendaten und Metadaten. Geben Sie in der Nachricht mindestens eine der folgenden Optionen an:
- Nachrichtendaten
- Ein Sortierschlüssel
- Attribute mit zusätzlichen Metadaten
Der Pub/Sub-Dienst fügt der Nachricht die folgenden Felder hinzu:
- Eine für das Thema eindeutige Nachrichten-ID
- Ein Zeitstempel, wenn der Pub/Sub-Dienst die Nachricht empfängt
Weitere Informationen zu Nachrichten finden Sie unter Nachrichtenformat.
Nachrichten veröffentlichen
Sie können Nachrichten mit der Google Cloud Console, der Google Cloud CLI, der Pub/Sub API und den Clientbibliotheken veröffentlichen. Die Clientbibliotheken können Nachrichten asynchron veröffentlichen.
Die folgenden Beispiele zeigen, wie Sie eine Nachricht zu einem Thema veröffentlichen.
Console
So veröffentlichen Sie eine Nachricht:
Rufen Sie in der Google Cloud Console die Seite Pub/Sub-Themen auf.
Klicken Sie auf die Themen-ID.
Klicken Sie auf der Seite Themendetails unter Nachrichten auf Nachricht veröffentlichen.
Geben Sie im Feld Nachrichtentext die Nachrichtendaten ein.
Klicken Sie auf Veröffentlichen.
gcloud
Veröffentlichen Sie eine Nachricht mit dem Befehl gcloud pubsub topics publish:
gcloud pubsub topics publish TOPIC_ID \ --message=MESSAGE_DATA \ [--attribute=KEY="VALUE",...]
Ersetzen Sie Folgendes:
- TOPIC_ID: ID des Themas
- MESSAGE_DATA: ein String mit den Nachrichtendaten
- KEY ist der Schlüssel eines Nachrichtenattributs
- VALUE: der Wert für den Schlüssel des Nachrichtenattributs
REST
Senden Sie eine POST-Anfrage wie die folgende, um eine Nachricht zu veröffentlichen:
POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID:publish Content-Type: application/json Authorization: Bearer $(gcloud auth application-default print-access-token)
Ersetzen Sie Folgendes:
- PROJECT_ID: Projekt-ID des Projekts mit dem Thema
- TOPIC_ID: ID des Themas
Geben Sie im Anfragetext die folgenden Felder an:
{ "messages": [ { "attributes": { "KEY": "VALUE", ... }, "data": "MESSAGE_DATA", } ] }
Ersetzen Sie Folgendes:
- KEY: der Schlüssel eines Nachrichtenattributs
- VALUE: der Wert für den Schlüssel des Nachrichtenattributs
- MESSAGE_DATA ist ein base64-codierter String mit den Nachrichtendaten
Die Nachricht muss entweder ein nicht leeres Datenfeld oder mindestens ein Attribut enthalten.
Wenn die Anfrage erfolgreich ist, ist die Antwort ein JSON-Objekt mit der Nachrichten-ID. Das folgende Beispiel ist eine Antwort mit einer Nachrichten-ID:
{ "messageIds": [ "19916711285", ] }
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.
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.
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.
Nachdem Sie eine Nachricht veröffentlicht haben, gibt der Pub/Sub-Dienst die Nachrichten-ID an den Publisher zurück.
Attribute zum Veröffentlichen einer Mitteilung verwenden
Sie können benutzerdefinierte Attribute als Metadaten in Pub/Sub-Nachrichten einbetten. Mit Attributen werden zusätzliche Informationen zur Nachricht bereitgestellt, z. B. Priorität, Ursprung oder Ziel. Attribute können auch zum Filtern von Nachrichten im Abo verwendet werden.
Beachten Sie bei der Verwendung von Attributen in Ihren Nachrichten die folgenden Richtlinien:
Attribute können Text- oder Bytestrings sein.
Pro Nachricht sind maximal 100 Attribute zulässig.
Attributschlüssel dürfen nicht mit
goog
beginnen und dürfen nicht größer als 256 Byte sein.Attributwerte dürfen 1.024 Byte nicht überschreiten.
Das Nachrichtenschema kann wie folgt dargestellt werden:
{ "data": string, "attributes": { string: string, ... }, "messageId": string, "publishTime": string, "orderingKey": string }
Bei Duplikaten auf der Veröffentlichungsseite kann es vorkommen, dass unterschiedliche publishTime
-Werte für dieselbe clientseitige Originalnachricht angezeigt werden, selbst mit demselben messageId
.
Das JSON-Schema PubsubMessage
wird als Teil der Dokumentation zu REST und RPC veröffentlicht. Sie können benutzerdefinierte Attribute für Ereigniszeitstempel verwenden.
Die folgenden Beispiele zeigen, wie Sie eine Nachricht mit Attributen zu einem Thema veröffentlichen.
Console
So veröffentlichen Sie eine Mitteilung mit Attributen:
Rufen Sie in der Google Cloud Console die Seite Themen auf.
Klicken Sie auf das Thema, für das Sie Nachrichten veröffentlichen möchten.
Klicken Sie auf der Seite mit den Themendetails auf Nachrichten.
Klicken Sie auf Nachricht veröffentlichen.
Geben Sie im Feld Nachrichtentext die Nachrichtendaten ein.
Klicken Sie unter Nachrichtenattribute auf Attribut hinzufügen.
Geben Sie ein Schlüssel/Wert-Paar ein.
Fügen Sie bei Bedarf weitere Attribute hinzu.
Klicken Sie auf Veröffentlichen.
gcloud
gcloud pubsub topics publish my-topic --message="hello" \ --attribute="origin=gcloud-sample,username=gcp,eventTime='2021-01-01T12:00:00Z'"
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.
Nachrichten mithilfe von Sortierungsschlüsseln veröffentlichen
Damit Sie Nachrichten in der richtigen Reihenfolge in Ihren Abonnentenclients empfangen können, müssen Sie Ihre Publisher-Clients so konfigurieren, dass Nachrichten mit Sortierungsschlüsseln veröffentlicht werden.
Weitere Informationen zum Konzept von Sortierschlüsseln finden Sie unter Bestellnachrichten.
Im Folgenden finden Sie eine Liste der wichtigsten Aspekte bei der geordneten Benachrichtigung für Publisher-Clients:
Reihenfolge in einem einzelnen Publisher-Client: Wenn ein einzelner Publisher-Client Nachrichten mit demselben Reihenfolgeschlüssel in derselben Region veröffentlicht, erhält der Abonnentenclient diese Nachrichten in genau der Reihenfolge, in der sie veröffentlicht wurden. Wenn ein Publisher-Client beispielsweise die Nachrichten 1, 2 und 3 mit dem Reihenfolgeschlüssel A veröffentlicht, erhält der Abonnentenclient die Nachrichten in der Reihenfolge 1, 2, 3.
Reihenfolge in mehreren Publisher-Clients: Die Reihenfolge der Nachrichten, die von Abonnentenclients empfangen werden, entspricht der Reihenfolge, in der sie in derselben Region veröffentlicht wurden, auch wenn mehrere Publisher-Clients denselben Reihenfolgeschlüssel verwenden. Die Publisher-Kunden selbst kennen diesen Auftrag jedoch nicht.
Wenn beispielsweise die Publisher-Clients X und Y jeweils Nachrichten mit dem Reihenfolgeschlüssel A veröffentlichen und die Nachricht von X von Pub/Sub vor der von Y empfangen wird, erhalten alle Abonnentenclients die Nachricht von X vor der von Y. Wenn eine strikte Reihenfolge der Nachrichten über verschiedene Publisher-Clients hinweg erforderlich ist, müssen diese Clients einen zusätzlichen Koordinationsmechanismus implementieren, damit sie nicht gleichzeitig Nachrichten mit demselben Reihenfolgeschlüssel veröffentlichen. Beispielsweise kann ein Sperrdienst verwendet werden, um die Inhaberschaft eines Bestellschlüssels während der Veröffentlichung beizubehalten.
Nach Region sortieren: Die Nachrichtensortierung wird nur für Nachrichten erwartet, die in derselben Region veröffentlicht wurden. Achten Sie daher darauf, dass Ihre Publisher-Clients die Standortdienste-Endpunkte verwenden, um Nachrichten für denselben Reihenfolgeschlüssel in derselben Region zu veröffentlichen. Abonnentenclients können diese Nachrichten dann der Reihe nach empfangen.
Veröffentlichungsfehler: Wenn die Veröffentlichung mit einem Sortierungsschlüssel fehlschlägt, schlagen Nachrichten aus der Warteschlange mit demselben Sortierungsschlüssel beim Publisher fehl, einschließlich zukünftiger Veröffentlichungsanfragen mit diesem Sortierungsschlüssel. Wenn solche Fehler auftreten, müssen Sie die Veröffentlichung mit Reihenfolgeschlüsseln fortsetzen. Ein Beispiel für die Wiederaufnahme des Veröffentlichungsvorgangs finden Sie unter Anfragen mit Sortierungsschlüsseln wiederholen.
Sie können Nachrichten mit Sortierschlüsseln mit der Google Cloud Console, der Google Cloud CLI, der Pub/Sub API oder den Clientbibliotheken veröffentlichen.
Console
So veröffentlichen Sie eine Mitteilung mit Attributen:
Rufen Sie in der Google Cloud Console die Seite Themen auf.
Klicken Sie auf das Thema, für das Sie Nachrichten veröffentlichen möchten.
Klicken Sie auf der Seite mit den Themendetails auf Nachrichten.
Klicken Sie auf Nachricht veröffentlichen.
Geben Sie im Feld Nachrichtentext die Nachrichtendaten ein.
Geben Sie im Feld Nachrichtenreihenfolge einen Reihenfolgeschlüssel ein.
Klicken Sie auf Veröffentlichen.
gcloud
Verwenden Sie zum Veröffentlichen einer Nachricht mit einem Reihenfolgenschlüssel den Befehl gcloud pubsub topics publish
und das Flag --ordering-key
:
gcloud pubsub topics publish TOPIC_ID \ --message=MESSAGE_DATA \ --ordering-key=ORDERING_KEY
Ersetzen Sie Folgendes:
- TOPIC_ID: ID des Themas
- MESSAGE_DATA: ein String mit den Nachrichtendaten
- ORDERING_KEY ist ein String mit einem Sortierungsschlüssel
REST
Senden Sie eine POST-Anfrage wie die folgende, um eine Nachricht mit einem Reihenfolgeschlüssel zu veröffentlichen:
POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID:publish Content-Type: application/json Authorization: Bearer $(gcloud auth application-default print-access-token)
Ersetzen Sie Folgendes:
- PROJECT_ID: Projekt-ID des Projekts mit dem Thema
- TOPIC_ID: ID des Themas
Geben Sie im Anfragetext die folgenden Felder an:
{ "messages": [ { "attributes": { "KEY": "VALUE", ... }, "data": "MESSAGE_DATA", "ordering_key": "ORDERING_KEY", } ] }
Ersetzen Sie Folgendes:
- KEY: der Schlüssel eines Nachrichtenattributs
- VALUE: der Wert für den Schlüssel des Nachrichtenattributs
- MESSAGE_DATA ist ein base64-codierter String mit den Nachrichtendaten
- ORDERING_KEY ist ein String mit einem Sortierungsschlüssel
Die Nachricht muss entweder ein nicht leeres Datenfeld oder mindestens ein Attribut enthalten.
Wenn die Anfrage erfolgreich ist, ist die Antwort ein JSON-Objekt mit der Nachrichten-ID. Das folgende Beispiel ist eine Antwort mit einer Nachrichten-ID:
{ "messageIds": [ "19916711285", ] }
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.
Publisher im Blick behalten
Cloud Monitoring bietet eine Reihe von Messwerten zum Beobachten von Themen.
Informationen zum Überwachen eines Themas und zur Gewährleistung eines fehlerfreien Publishers finden Sie unter Stabilen Publisher aufrechterhalten.
Nächste Schritte
Informationen zum Einschränken der Standorte, an denen Pub/Sub Nachrichtendaten speichert, finden Sie unter Pub/Sub-Ressourcenstandorte einschränken.
Informationen zum Veröffentlichen von Nachrichten mit Schema finden Sie unter Schemaübersicht.
Hier erfahren Sie, wie Sie die Optionen für die erweiterte Zustellung konfigurieren: