Push-Abos erstellen

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

Hinweise

Erforderliche Rollen und Berechtigungen

Wenn Sie ein Abo erstellen möchten, müssen Sie die Zugriffssteuerung auf Projektebene konfigurieren. Sie benötigen auch Berechtigungen auf Ressourcenebene, wenn sich Ihre Abos und Themen in verschiedenen Projekten befinden, wie weiter unten in diesem Abschnitt erläutert.

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Pub/Sub Editor (roles/pubsub.editor) für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen von 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 von Push-Abos erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um Push-Abos zu erstellen:

  • So erstellst du ein Abo: pubsub.subscriptions.create
  • So löschen Sie ein Abo: pubsub.subscriptions.delete
  • Abo abschließen: pubsub.subscriptions.get
  • Abo auflisten: pubsub.subscriptions.list
  • Abo aktualisieren: pubsub.subscriptions.update
  • So hängen Sie ein Abo an ein Thema an: pubsub.topics.attachSubscription
  • Rufen Sie die IAM-Richtlinie für ein Abo ab: pubsub.subscriptions.getIamPolicy
  • Konfigurieren Sie die IAM-Richtlinie für ein Abo: pubsub.subscriptions.setIamPolicy

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Wenn Sie Push-Abos in einem Projekt erstellen möchten, die mit einem Thema in einem anderen Projekt verknüpft sind, bitten Sie den Administrator des Themas, Ihnen auch die IAM-Rolle „Pub/Sub Editor“ (roles/pubsub.editor) für das Thema zu gewähren.

Push-Abo-Attribute

Wenn Sie ein Push-Abo konfigurieren, können Sie die folgenden Eigenschaften angeben.

Allgemeine Eigenschaften

Weitere Informationen zu den allgemeinen Aboeigenschaften, die Sie für alle Abos festlegen können

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.

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

Aktivieren Sie die Authentifizierung. Wenn diese Option aktiviert ist, enthalten von Pub/Sub an den Push-Endpunkt gesendete Nachrichten einen Autorisierungsheader, über den der Endpunkt die Anfrage authentifizieren kann. Für App Engine Standard- und Cloud Run-Funktionen-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 Kundenservicemitarbeiter eine bestimmte Rolle zuweisen, wie im nächsten Abschnitt beschrieben.

  • Nutzerverwaltetes Dienstkonto (erforderlich) Das Dienstkonto, das dem Push-Abo zugeordnet 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:

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

  • Dienst-Agent (erforderlich)

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

    • Diesem Dienst-Agent muss die Berechtigung iam.serviceAccounts.getOpenIdToken (in der Rolle roles/iam.serviceAccountTokenCreator enthalten) gewährt werden, damit Pub/Sub JWT-Tokens für authentifizierte Push-Anfragen erstellen kann.

Entpacken der Nutzlast

Mit der Option Entpacken der Nutzlast aktivieren werden aus Pub/Sub-Nachrichten alle Nachrichtenmetadaten entfernt, mit Ausnahme der Nachrichtendaten. Beim Entfernen der Nutzlast werden die Nachrichtendaten direkt als HTTP-Textkörper gesendet.

  • Metadaten schreiben Fügt dem Anfrageheader zuvor entfernte Nachrichtenmetadaten wieder hinzu.

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 eine Workflow-Ausführung festgelegt ist. Benutzerdefinierte Domains funktionieren nicht.

  • Wenn Sie Ereignisse über Eventarc an Workflow-Ziele weiterleiten, für die der Push-Endpunkt auf eine Workflow-Ausführung festgelegt ist, können Sie nur neue Push-Abos über Eventarc erstellen.

  • Vorhandene Push-Abos können nicht aktualisiert werden. 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 bereitgestellten Standardeinstellungen erstellen.

Standardmäßig wird für Abos die Pull-Zustellung verwendet, sofern Sie nicht explizit eine Push-Konfiguration festlegen, wie in den folgenden Beispielen gezeigt.

Console

So erstellen Sie ein Push-Abo:

  1. Öffnen Sie in der Google Cloud Console die Seite Abos.

    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 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 Seite Themen 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 Push aus.
  6. Geben Sie eine Endpunkt-URL an.
  7. Behalten Sie alle anderen Standardwerte bei.
  8. Klicken Sie auf Erstellen.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Führen Sie den Befehl gcloud pubsub subscriptions create 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 des neuen Push-Abos.
    • TOPIC_ID: Der Name oder die ID des 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:

  • PROJECT_ID ist die Projekt-ID.
  • SUBSCRIPTION_ID ist Ihre Abo-ID.
  • TOPIC_ID ist Ihre 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 Referenzdokumentation zur Pub/Sub C++ API.

    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#

    Folgen Sie der Einrichtungsanleitung für C# in der Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel anwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub C# API.

    Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Pub/Sub zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

    
    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

    Folgen Sie der Einrichtungsanleitung für Go in der Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel anwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Go API.

    Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Pub/Sub zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

    import (
    	"context"
    	"fmt"
    	"io"
    	"time"
    
    	"cloud.google.com/go/pubsub"
    )
    
    func createWithEndpoint(w io.Writer, projectID, subID string, topic *pubsub.Topic, endpoint string) error {
    	// projectID := "my-project-id"
    	// subID := "my-sub"
    	// topic of type https://godoc.org/cloud.google.com/go/pubsub#Topic
    	// 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.CreateSubscription(ctx, subID, pubsub.SubscriptionConfig{
    		Topic:       topic,
    		AckDeadline: 10 * time.Second,
    		PushConfig:  pubsub.PushConfig{Endpoint: endpoint},
    	})
    	if err != nil {
    		return fmt.Errorf("CreateSubscription: %w", err)
    	}
    	fmt.Fprintf(w, "Created push subscription: %v\n", sub)
    	return nil
    }
    

    Java

    Folgen Sie der Einrichtungsanleitung für Java in der Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel anwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Java API.

    Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Pub/Sub zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

    
    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

    /**
     * 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.js

    /**
     * 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 in der Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel anwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub PHP API.

    Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Pub/Sub zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

    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

    Folgen Sie der Einrichtungsanleitung für Python in der Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel anwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Python API.

    Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Pub/Sub zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

    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

    Folgen Sie der Einrichtungsanleitung für Ruby in der Kurzanleitung zur Verwendung von Clientbibliotheken, bevor Sie dieses Beispiel anwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub Ruby API.

    Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Pub/Sub zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

    # topic_id          = "your-topic-id"
    # subscription_id   = "your-subscription-id"
    # endpoint          = "https://your-test-project.appspot.com/push"
    
    pubsub = Google::Cloud::Pubsub.new
    
    topic        = pubsub.topic topic_id
    subscription = topic.subscribe subscription_id,
                                   endpoint: endpoint
    
    puts "Push subscription #{subscription_id} created."

    Push-Abos beobachten

    Cloud Monitoring bietet eine Reihe von Messwerten, mit denen Sie Abos überwachen können.

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

    Sie können Abos auch in Pub/Sub überwachen.

    Nächste Schritte