In diesem Dokument wird beschrieben, wie Sie ein Push-Abo erstellen. Sie können ein Push-Abo über dieCloud de Confiance -Konsole, die Google Cloud CLI, die Clientbibliothek oder die Pub/Sub API erstellen.
Hinweis
Erforderliche Rollen und Berechtigungen
Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Pub/Sub-Bearbeiter (roles/pubsub.editor) für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen eines Push-Abos benötigen.
Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.
Diese vordefinierte Rolle enthält die Berechtigungen, die zum Erstellen eines Push-Abos erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:
Erforderliche Berechtigungen
Die folgenden Berechtigungen sind zum Erstellen eines Push-Abos erforderlich:
pubsub.subscriptions.createfür das Projekt-
pubsub.topics.attachSubscriptionzum Thema
Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.
Projektübergreifende Abos
Wenn Sie ein Abo in einem Projekt für ein Thema in einem anderen Projekt erstellen, benötigen Sie die Berechtigung pubsub.subscriptions.create für das Projekt, in dem Sie das Abo erstellen, und die Berechtigung pubsub.topics.attachSubscription für das Thema.
Push-Abo-Attribute
Push-Abos unterstützen alle gemeinsamen Abo-Attribute. In den folgenden Abschnitten werden Eigenschaften beschrieben, die für Push-Abos spezifisch sind.
Endpunkte
Endpunkt-URL (erforderlich). Eine öffentlich zugängliche HTTPS-Adresse. Der Server für den Push-Endpunkt muss ein gültiges SSL-Zertifikat haben, das von einer Zertifizierungsstelle signiert wurde. Der Pub/Sub-Dienst sendet Nachrichten an Push-Endpunkte aus derselben Cloud de Confiance Region, in der der Pub/Sub-Dienst die Nachrichten speichert. Der Pub/Sub-Dienst stellt Nachrichten aus derselben Cloud de Confiance -Region auf Best-Effort-Basis zu.
Wenn Abonnenten eine Firewall verwenden, können sie keine Push-Anfragen empfangen. Damit Sie Push-Anfragen erhalten, müssen Sie die Firewall deaktivieren und das in der Anfrage verwendete JSON-Webtoken (JWT) überprüfen. Wenn ein Abonnent eine Firewall hat, wird möglicherweise der Fehler
403 permission deniedangezeigt.Pub/Sub erfordert keinen Nachweis über die Inhaberschaft für Domains für Push-Abos. Wenn Ihre Domain unerwartete POST-Anfragen von Pub/Sub erhält, können Sie mutmaßlichen Missbrauch melden.
Authentifizierung
Authentifizierung aktivieren Wenn diese Option aktiviert ist, enthalten Nachrichten, die von Pub/Sub an den Push-Endpunkt gesendet werden, einen Autorisierungsheader, damit der Endpunkt die Anfrage authentifizieren kann. Für App Engine Standard- und Cloud Run Functions-Endpunkte, die im selben Projekt wie das Abo gehostet werden, sind automatische Authentifizierungs- und Autorisierungsmechanismen verfügbar.
Die Authentifizierungskonfiguration für ein authentifiziertes Push-Abo besteht aus einem nutzerverwalteten Dienstkonto und den Zielgruppenparametern, die in einem create-, patch- oder ModifyPushConfig-Aufruf angegeben werden. Außerdem müssen Sie einem Dienstkonto eine bestimmte Rolle zuweisen, wie im nächsten Abschnitt beschrieben.
Zielgruppe Ein einzelner String, bei dem die Groß-/Kleinschreibung nicht berücksichtigt wird und den der Webhook verwendet, um die Zielgruppe dieses bestimmten Tokens zu validieren.
Dienstkonto: Pub/Sub erstellt automatisch ein Dienstkonto für Sie im Format
service-{PROJECT_NUMBER}@gcp-sa-pubsub.s3ns-system.iam.gserviceaccount.com.
Voraussetzungen für die Aktivierung der Authentifizierung
Das nutzerverwaltete Dienstkonto ist das Dienstkonto, das mit dem Push-Abo verknüpft ist. Dieses Konto wird als email-Anspruch des generierten JSON Web Tokens (JWT) verwendet. Im Folgenden finden Sie eine Liste der Anforderungen an das Dienstkonto:
Dieses vom Nutzer verwaltete Dienstkonto muss sich im selben Projekt wie das Push-Abo befinden.
Das Hauptkonto, das das Push-Abo erstellt oder ändert, muss die Berechtigung
iam.serviceAccounts.actAsfür das nutzerverwaltete Dienstkonto haben, um das Dienstkonto an das Push-Abo anzuhängen. Weitere Informationen finden Sie unter Dienstkonten an Ressourcen anhängen.Erforderliche Berechtigungen: Diesem Dienstkonto muss die Berechtigung
iam.serviceAccounts.getOpenIdToken(in der Rolleroles/iam.serviceAccountTokenCreatorenthalten) gewährt werden, damit Pub/Sub JWT-Tokens für das angegebene Dienstkonto erstellen kann, um Push-Anfragen zu authentifizieren.
Entpacken der Nutzlast
Mit der Option Entpacken der Nutzlast aktivieren werden alle Nachrichtenmetadaten aus Pub/Sub-Nachrichten entfernt, mit Ausnahme der Nachrichtendaten. Beim Entpacken der Nutzlast werden die Nachrichtendaten direkt als HTTP-Textkörper bereitgestellt.
Sie können auch die Option Metadaten schreiben aktivieren. Mit der Option Metadaten schreiben werden zuvor entfernte Nachrichtenmetadaten wieder dem Anfrageheader hinzugefügt.
An private VPC-Adressen senden
Pub/Sub wird außerhalb von VPC-Netzwerken ausgeführt und kann Nachrichten nicht direkt an private VPC-Adressen senden. Sie können jedoch Eventarc verwenden, um Nachrichten an Dienste in Ihrer VPC weiterzuleiten. Pub/Sub kann Nachrichten an einen Eventarc-Trigger senden, der sie dann an einen Dienst in Ihrer VPC weiterleiten kann, z. B. an einen Cloud Run-Dienst oder eine Workflows-Ausführung. Weitere Informationen finden Sie in der Eventarc-Dokumentation.
VPC Service Controls
Für ein Projekt, das durch VPC Service Controls geschützt ist, gelten die folgenden Einschränkungen für Push-Abos:
Sie können nur neue Push-Abos erstellen, für die der Push-Endpunkt auf einen Cloud Run-Dienst mit einer standardmäßigen
run.app-URL oder auf eine Workflows-Ausführung festgelegt ist. Benutzerdefinierte Domains funktionieren nicht.Wenn Sie Ereignisse über Eventarc an Workflows-Ziele weiterleiten, für die der Push-Endpunkt auf eine Workflows-Ausführung festgelegt ist, können Sie neue Push-Abos nur über Eventarc erstellen.
Vorhandene Push-Abos können nicht aktualisiert werden. Diese Push-Abos funktionieren weiterhin, sind aber nicht durch VPC Service Controls geschützt.
Push-Abo erstellen
In den folgenden Beispielen wird gezeigt, wie Sie ein Abo mit Push-Zustellung mit den bereitgestellten Standardeinstellungen erstellen.
Standardmäßig wird für Abos die Pull-Übermittlung verwendet, sofern Sie nicht explizit eine Push-Konfiguration festlegen, wie in den folgenden Beispielen gezeigt.
Console
So erstellen Sie ein Push-Abo:
Rufen Sie in der Cloud de Confiance Console die Seite Abos auf.
Klicken Sie auf Abo erstellen.
Geben Sie im Feld Abo-ID einen Namen ein.
Informationen zum Benennen eines Abos finden Sie unter Richtlinien für die Benennung eines Themas oder Abos.
Wählen Sie in der Liste Pub/Sub-Thema ein Thema aus, aus dem das Abo Daten lesen soll.
Wählen Sie für Bereitstellungstyp die Option Push aus.
Geben Sie die Endpunkt-URL in das Feld Endpoint URL (Endpunkt-URL) ein.
Optional: So aktivieren Sie die Authentifizierung:
- Wählen Sie Authentifizierung aktivieren aus.
- Wählen Sie in der Liste Dienstkonto das Dienstkonto aus, das die Authentifizierung durchführen soll.
- Optional: Geben Sie im Feld Zielgruppe eine Zielgruppe ein.
Weitere Informationen finden Sie unter Authentifizierung für Push-Abos.
Optional: Wenn Sie Entpacken der Nutzlast aktivieren möchten, wählen Sie Entpacken der Nutzlast aktivieren aus.
Wenn Sie Nachrichtenmetadaten im Anfrageheader beibehalten möchten, wählen Sie auch Metadaten schreiben aus. Mit dieser Option wird auch ein
Content-Type-Header für Ihre Nachrichten festgelegt.Optional: Fügen Sie im Abschnitt Transformationen eine oder mehrere Transformationen einzelner Nachrichten (SMTs) hinzu. Weitere Informationen finden Sie unter Abo mit SMTs erstellen.
Optional: Geben Sie im Feld Filter einen Filterausdruck ein, um Nachrichten aus dem Abo zu filtern. Weitere Informationen finden Sie unter Nachrichten aus einem Abo filtern.
Wählen Sie unter Wiederholungsrichtlinie eine Option aus. Weitere Informationen finden Sie unter Richtlinie für erneute Aboversuche.
Optional: Aktivieren Sie ein Thema für unzustellbare Nachrichten, um unzustellbare Nachrichten zu empfangen.
Klicken Sie das Kästchen Unzustellbare Nachrichten an.
Wählen Sie in der Liste Dead-Letter-Thema das Dead-Letter-Thema aus oder erstellen Sie es.
Geben Sie im Feld Maximale Anzahl von Zustellversuchen die maximale Anzahl von Zustellversuchen ein.
Optional: Aktivieren oder deaktivieren Sie im Abschnitt Auslieferungseigenschaften die folgenden Auslieferungsoptionen:
Optional: Legen Sie im Abschnitt Bestätigungsfrist die Frist fest, innerhalb derer der Abonnent Nachrichten verarbeiten und bestätigen muss. Weitere Informationen finden Sie unter Bestätigungszeit mit der Lease-Verwaltung verlängern.
Optional: Konfigurieren Sie im Abschnitt Lifetime options (Optionen für die Lebensdauer), wie lange die Nachrichten im Abo gespeichert werden.
Geben Sie im Abschnitt Aufbewahrungsdauer für Nachrichten an, wie lange nicht bestätigte Nachrichten aufbewahrt werden.
Wenn Sie sowohl bestätigte als auch nicht bestätigte Nachrichten aufbewahren möchten, setzen Sie ein Häkchen bei Bestätigte Nachrichten aufbewahren.
Weitere Informationen finden Sie unter Nachrichtenaufbewahrung für ein Abo konfigurieren.
Optional: Wählen Sie für Ablaufzeitraum eine Option aus:
Wenn Sie das Ablaufdatum des Abos festlegen möchten, klicken Sie das Kästchen Ablauf nach dieser Anzahl von inaktiven Tagen an. Geben Sie die Anzahl der Tage ein, die das Abo inaktiv bleiben kann, bevor es von Pub/Sub gelöscht wird.
Wenn Sie den Ablauf des Abos deaktivieren möchten, klicken Sie das Kästchen Nie ablaufen an.
Weitere Informationen finden Sie unter Abo-Ablauf.
Klicken Sie auf Erstellen.
Sie können ein Abo auch im Abschnitt Themen erstellen. Diese Verknüpfung ist nützlich, um Themen mit Abos zu verknüpfen.
Rufen Sie in der Cloud de Confiance Console die Seite Themen auf.
Klicken Sie neben dem Thema, für das Sie ein Abo erstellen möchten, auf more_vert.
Wählen Sie im Kontextmenü Abo erstellen aus.
Führen Sie auf der Seite Abo zum Thema hinzufügen die Schritte aus, die im vorherigen Verfahren beschrieben werden. Die Themen-ID wird automatisch ausgefüllt.
gcloud
-
Aktivieren Sie Cloud Shell in der Cloud de Confiance Console.
Unten in der Cloud de Confiance Console wird eine Cloud Shell-Sitzung gestartet und eine Eingabeaufforderung angezeigt. Cloud Shell ist eine Shell-Umgebung, in der das Google Cloud CLI bereits installiert ist und Werte für Ihr aktuelles Projekt bereits festgelegt sind. Das Initialisieren der Sitzung kann einige Sekunden dauern.
-
Führen Sie den Befehl
gcloud pubsub subscriptions createaus, um ein Push-Abo zu erstellen.gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --push-endpoint=PUSH_ENDPOINT
Ersetzen Sie Folgendes:
SUBSCRIPTION_ID: Der Name oder die ID Ihres neuen Push-Abos.TOPIC_ID: Der Name oder die ID Ihres Themas.- PUSH_ENDPOINT: die URL, die als Endpunkt für dieses Abo verwendet werden soll.
Beispiel:
https://myproject.appspot.com/myhandler.
REST
Verwenden Sie zum Erstellen eines Push-Abos die Methode projects.subscriptions.create:
Anfrage:
Die Anfrage muss mit einem Zugriffstoken im Header Authorization authentifiziert werden. Zugriffstoken für die aktuellen Standardanmeldedaten für Anwendungen abrufen: gcloud auth application-default print-access-token
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID Authorization: Bearer ACCESS_TOKEN
Anfragetext:
{
"topic": "projects/PROJECT_ID/topics/TOPIC_ID",
// Only needed if you are using push delivery
"pushConfig": {
"pushEndpoint": "PUSH_ENDPOINT"
}
}Wobei:
https://myproject.appspot.com/myhandler.Response:
{
"name": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID",
"topic": "projects/PROJECT_ID/topics/TOPIC_ID",
"pushConfig": {
"pushEndpoint": "https://PROJECT_ID.appspot.com/myhandler",
"attributes": {
"x-goog-version": "v1"
}
},
"ackDeadlineSeconds": 10,
"messageRetentionDuration": "604800s",
"expirationPolicy": {
"ttl": "2678400s"
}
}C++
Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für C++ in der Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Pub/Sub C++ API-Referenzdokumentation.
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.
Go
Im folgenden Beispiel wird die Hauptversion der Go Pub/Sub-Clientbibliothek (v2) verwendet. Wenn Sie noch die v1-Bibliothek verwenden, lesen Sie die Migrationsanleitung zu v2. Eine Liste der Codebeispiele für Version 1 finden Sie unter Eingestellte Codebeispiele.
Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Einrichtungsanleitung für Go in der Kurzanleitung: 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 Node.js in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Node.js API.
Node.ts
Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für Node.js 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 Pub/Sub Python API-Referenzdokumentation.
Ruby
Im folgenden Beispiel wird die Ruby Pub/Sub-Clientbibliothek v3 verwendet. Wenn Sie noch die v2-Bibliothek verwenden, finden Sie hier die Migrationsanleitung für v3. Eine Liste der Ruby v2-Codebeispiele finden Sie unter eingestellte Codebeispiele.
Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Einrichtungsanleitung für Ruby in der Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Informationen finden Sie in der Pub/Sub Ruby API-Referenzdokumentation.
Push-Abos im Blick behalten
Cloud Monitoring bietet eine Reihe von Messwerten zum Überwachen von Abos.
Eine Liste aller verfügbaren Messwerte für Pub/Sub und deren Beschreibungen finden Sie in der Dokumentation zur Überwachung von Pub/Sub.
Sie können Abos auch in Pub/Sub überwachen.
Nächste Schritte
- Abo mit
gcloud-Befehlen erstellen oder ändern - Erstellen oder ändern Sie ein Abo mit REST APIs.