Push-Abos erstellen

In diesem Dokument wird beschrieben, wie Sie ein Push-Abo erstellen. Sie können ein Push-Abo über die Google Cloud Console, die Google Cloud CLI, die Clientbibliothek oder die Pub/Sub API erstellen.

Hinweis

• Informationen zu Abos
• Funktionsweise von Push-Abos

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, die erforderlich sind:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind zum Erstellen eines Push-Abos erforderlich:

• pubsub.subscriptions.create für das Projekt
• pubsub.topics.attachSubscription für das 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.

Attribute von Push-Abos

Push-Abos unterstützen alle allgemeinen Abo-Attribute. In den folgenden Abschnitten werden Attribute beschrieben, die speziell für Push-Abos gelten.

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 Google Cloud Region, in der der Pub/Sub-Dienst die Nachrichten speichert. Der Pub/Sub-Dienst sendet Nachrichten aus derselben Google Cloud Region auf Best-Effort-Basis.

• Wenn Abonnenten eine Firewall verwenden, können sie keine Push-Anfragen empfangen. Um Push-Anfragen zu erhalten, müssen Sie die Firewall deaktivieren und das in der Anfrage verwendete JSON-Webtoken (JWT) prüfen. Wenn ein Abonnent eine Firewall hat, erhalten Sie möglicherweise den Fehler 403 permission denied.

• Für Pub/Sub ist kein Eigentumsnachweis für Domains für Push-Abos mehr erforderlich. Wenn Ihre Domain unerwartete POST-Anfragen von Pub/Sub erhält, können Sie einen 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-Funktionsendpunkte, 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 Aufruf von „create“, „patch“ oder „ModifyPushConfig“ angegeben sind. Sie müssen einem Dienstkonto auch eine bestimmte Rolle zuweisen, wie im nächsten Abschnitt beschrieben.

• Zielgruppe Ein einzelner String ohne Berücksichtigung der Groß- und Kleinschreibung, mit dem der Webhook die beabsichtigte Zielgruppe dieses bestimmten Tokens prüfen kann.

• Dienstkonto Pub/Sub erstellt automatisch ein Dienstkonto für Sie im Format service-{PROJECT_NUMBER}@gcp-sa-pubsub..

Voraussetzungen für die Aktivierung der Authentifizierung

Das nutzerverwaltete Dienstkonto ist das Dienstkonto, das dem Push-Abo zugeordnet ist. Dieses Konto wird als email-Anspruch des generierten JSON-Webtokens (JWT) verwendet. Im Folgenden finden Sie eine Liste der Anforderungen für das Dienstkonto:

• Dieses nutzerverwaltete Dienstkonto muss sich im selben Projekt wie das Push-Abo befinden.

• Der Prinzipal, der das Push-Abo erstellt oder ändert, muss die iam.serviceAccounts.actAs Berechtigung fü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 gewährt werden (in der Rolle roles/iam.serviceAccountTokenCreator enthalten), 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 gesendet.

Sie können auch die Option Metadaten schreiben aktivieren. Mit der Option Metadaten schreiben werden zuvor entfernte Nachrichtenmetadaten wieder in den Anfrageheader eingefü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 Standard-URL run.app oder 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.

• Sie können vorhandene Push-Abos nicht aktualisieren. Diese Push-Abos funktionieren weiterhin, obwohl sie nicht durch VPC Service Controls geschützt werden.

Push-Abo erstellen

Die folgenden Beispiele zeigen, wie Sie ein Abo mit Push-Zustellung mit den angegebenen Standardeinstellungen erstellen.

Standardmäßig verwenden Abos die Pull-Zustellung, es sei denn, Sie legen explizit eine Push-Konfiguration fest, wie in den folgenden Beispielen gezeigt.

Console

Führen Sie die folgenden Schritte aus, um ein Push-Abo zu erstellen:

1. Rufen Sie in der Google Cloud Console die Seite Abos auf.

   Zu den Abos

2. Klicken Sie auf Abo erstellen.
3. 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.

4. Wählen Sie im Drop-down-Menü ein Thema aus oder erstellen Sie ein Thema. Das Abo erhält Nachrichten aus dem Thema.
5. Wählen Sie als Zustellungstyp die Option Push aus.
6. Geben Sie eine Endpunkt-URL an.
7. Behalten Sie alle anderen Standardwerte bei.
8. 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.

1. Rufen Sie in der Google Cloud Console die Themen Seite auf.

   Themen aufrufen

2. Klicken Sie neben dem Thema, für das Sie ein Abo erstellen möchten, auf .
3. Wählen Sie im Kontextmenü Abo erstellen aus.
4. Geben Sie die Abo-ID ein.

   Informationen zum Benennen eines Abos finden Sie unter Richtlinien für die Benennung eines Themas oder Abos.

5. Wählen Sie als Zustellungstyp die Option Push aus.
6. Geben Sie eine Endpunkt-URL an.
7. Behalten Sie alle anderen Standardwerte bei.
8. Klicken Sie auf Erstellen.

gcloud

1. Aktivieren Sie Cloud Shell in der Google Cloud Console.

   Cloud Shell aktivieren

   Unten in der Google Cloud Console wird eine Cloud Shell Sitzung gestartet und eine Befehlszeilenaufforderung 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.

2. Führen Sie den gcloud pubsub subscriptions create Befehl aus, 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 projects.subscriptions.create Methode:

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:

PROJECT_ID ist die Projekt-ID.

SUBSCRIPTION_ID ist die Abo-ID.

TOPIC_ID ist die Themen-ID.

PUSH_ENDPOINT ist eine URL, die als Endpunkt verwendet werden soll. Beispiel: 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.

namespace pubsub = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& topic_id,
   std::string const& subscription_id, std::string const& endpoint) {
  google::pubsub::v1::Subscription request;
  request.set_name(
      pubsub::Subscription(project_id, subscription_id).FullName());
  request.set_topic(pubsub::Topic(project_id, topic_id).FullName());
  request.mutable_push_config()->set_push_endpoint(endpoint);
  auto sub = client.CreateSubscription(request);
  if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
    std::cout << "The subscription already exists\n";
    return;
  }
  if (!sub) throw std::move(sub).status();

  std::cout << "The subscription was successfully created: "
            << sub->DebugString() << "\n";

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.

using Google.Cloud.PubSub.V1;

public class CreatePushSubscriptionSample
{
    public Subscription CreatePushSubscription(string projectId, string topicId, string subscriptionId, string pushEndpoint)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);

        PushConfig pushConfig = new PushConfig { PushEndpoint = pushEndpoint };

        // The approximate amount of time in seconds (on a best-effort basis) Pub/Sub waits for the
        // subscriber to acknowledge receipt before resending the message.
        var ackDeadlineSeconds = 60;
        var subscription = subscriber.CreateSubscription(subscriptionName, topicName, pushConfig, ackDeadlineSeconds);
        return subscription;
    }
}

Go

Im folgenden Beispiel wird die Hauptversion der Go Pub/Sub-Clientbibliothek (Version 2) verwendet. Wenn Sie noch die Version 1 verwenden, lesen Sie den Migrationsleitfaden zu Version 2. Eine Liste der Codebeispiele für Version 1 finden Sie unter Veraltete Codebeispiele.

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.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

func createWithEndpoint(w io.Writer, projectID, topic, subscription, endpoint string) error {
	// projectID := "my-project-id"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	// endpoint := "https://my-test-project.appspot.com/push"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	sub, err := client.SubscriptionAdminClient.CreateSubscription(ctx, &pubsubpb.Subscription{
		Name:               subscription,
		Topic:              topic,
		AckDeadlineSeconds: 10,
		PushConfig:         &pubsubpb.PushConfig{PushEndpoint: endpoint},
	})
	if err != nil {
		return fmt.Errorf("failed to create push sub: %w", err)
	}
	fmt.Fprintf(w, "Created push subscription: %v\n", sub)
	return nil
}

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.

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.PushConfig;
import com.google.pubsub.v1.Subscription;
import com.google.pubsub.v1.SubscriptionName;
import com.google.pubsub.v1.TopicName;
import java.io.IOException;

public class CreatePushSubscriptionExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String subscriptionId = "your-subscription-id";
    String topicId = "your-topic-id";
    String pushEndpoint = "https://my-test-project.appspot.com/push";

    createPushSubscriptionExample(projectId, subscriptionId, topicId, pushEndpoint);
  }

  public static void createPushSubscriptionExample(
      String projectId, String subscriptionId, String topicId, String pushEndpoint)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
      TopicName topicName = TopicName.of(projectId, topicId);
      SubscriptionName subscriptionName = SubscriptionName.of(projectId, subscriptionId);
      PushConfig pushConfig = PushConfig.newBuilder().setPushEndpoint(pushEndpoint).build();

      // Create a push subscription with default acknowledgement deadline of 10 seconds.
      // Messages not successfully acknowledged within 10 seconds will get resent by the server.
      Subscription subscription =
          subscriptionAdminClient.createSubscription(subscriptionName, topicName, pushConfig, 10);
      System.out.println("Created push subscription: " + subscription.getName());
    }
  }
}

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.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const pushEndpoint = 'YOUR_ENDPOINT_URL';
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createPushSubscription(
  pushEndpoint,
  topicNameOrId,
  subscriptionNameOrId,
) {
  const options = {
    pushConfig: {
      // Set to an HTTPS endpoint of your choice. If necessary, register
      // (authorize) the domain on which the server is hosted.
      pushEndpoint,
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);
  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

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.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const pushEndpoint = 'YOUR_ENDPOINT_URL';
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';

// Imports the Google Cloud client library
import {PubSub, CreateSubscriptionOptions} from '@google-cloud/pubsub';

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createPushSubscription(
  pushEndpoint: string,
  topicNameOrId: string,
  subscriptionNameOrId: string,
) {
  const options: CreateSubscriptionOptions = {
    pushConfig: {
      // Set to an HTTPS endpoint of your choice. If necessary, register
      // (authorize) the domain on which the server is hosted.
      pushEndpoint,
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);
  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

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.

use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub push subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 * @param string $endpoint  The endpoint for the push subscription.
 */
function create_push_subscription($projectId, $topicName, $subscriptionName, $endpoint)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $subscription->create([
        'pushConfig' => ['pushEndpoint' => $endpoint]
    ]);

    printf('Subscription created: %s' . PHP_EOL, $subscription->name());
}

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.

from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# endpoint = "https://my-test-project.appspot.com/push"

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic_path = publisher.topic_path(project_id, topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_id)

push_config = pubsub_v1.types.PushConfig(push_endpoint=endpoint)

# Wrap the subscriber in a 'with' block to automatically call close() to
# close the underlying gRPC channel when done.
with subscriber:
    subscription = subscriber.create_subscription(
        request={
            "name": subscription_path,
            "topic": topic_path,
            "push_config": push_config,
        }
    )

print(f"Push subscription created: {subscription}.")
print(f"Endpoint for subscription is: {endpoint}")

Ruby

Im folgenden Beispiel wird die Ruby Pub/Sub-Clientbibliothek Version 3 verwendet. Wenn Sie noch die Version 2 verwenden, lesen Sie den Migrationsleitfaden zu Version 3. Eine Liste der Codebeispiele für Ruby Version 2 finden Sie unter Veraltete Codebeispiele.

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.

# topic_id          = "your-topic-id"
# subscription_id   = "your-subscription-id"
# endpoint          = "https://your-test-project.appspot.com/push"

pubsub = Google::Cloud::PubSub.new
subscription_admin = pubsub.subscription_admin

subscription = subscription_admin.create_subscription \
  name: pubsub.subscription_path(subscription_id),
  topic: pubsub.topic_path(topic_id),
  push_config: {
    push_endpoint: endpoint
  }

puts "Push subscription #{subscription_id} created."

Push-Abos beobachten

Cloud Monitoring bietet eine Reihe von Messwerten zum Beobachten von Abos.

Eine Liste aller verfügbaren Messwerte im Zusammenhang mit Pub/Sub und deren Beschreibungen finden Sie in der Monitoring-Dokumentation für Pub/Sub.

Sie können Abos auch in Pub/Sub beobachten.

Nächste Schritte

• Abo mit gcloud Befehlen erstellen oder ändern
• Abo mit REST APIs erstellen oder ändern