Créer des abonnements push

Ce document explique comment créer un abonnement push. Vous pouvez utiliser la console Google Cloud, la Google Cloud CLI, la bibliothèque cliente l'API Pub/Sub pour créer un abonnement push ;

Avant de commencer

• En savoir plus sur les abonnements
• Découvrez le fonctionnement des abonnements push.

Rôles et autorisations requis

Pour créer un abonnement, vous devez configurer le contrôle des accès au niveau au niveau du projet. Vous avez également besoin d'autorisations au niveau des ressources si vos abonnements et les sujets appartiennent à des projets différents, comme expliqué plus loin dans cette section.

Pour obtenir les autorisations nécessaires pour créer des abonnements push, demandez à votre administrateur de vous accorder le rôle IAM Éditeur Pub/Sub (roles/pubsub.editor) sur le projet. Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient les autorisations requises pour créer des abonnements push. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour créer des abonnements push :

• Créez un abonnement: pubsub.subscriptions.create
• Supprimer un abonnement : pubsub.subscriptions.delete
• Obtenir un abonnement : pubsub.subscriptions.get
• Lister un abonnement : pubsub.subscriptions.list
• Pour mettre à jour un abonnement: pubsub.subscriptions.update
• Joindre un abonnement à un sujet : pubsub.topics.attachSubscription
• Obtenez la stratégie IAM d'un abonnement: pubsub.subscriptions.getIamPolicy
• Configurez la stratégie IAM pour un abonnement : pubsub.subscriptions.setIamPolicy

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Si vous avez besoin de créer abonnements d'un projet qui sont associés à un sujet dans un autre demandez à l'administrateur du sujet de vous accorder également le rôle d'éditeur Pub/Sub (roles/pubsub.editor) sur le sujet.

Propriétés des abonnements push

Lorsque vous configurez un abonnement push, vous pouvez spécifier les propriétés suivantes.

Propriétés communes

En savoir plus sur les propriétés d'abonnement courantes que vous pouvez définir pour tous les abonnements.

Points de terminaison

URL du point de terminaison (obligatoire) Adresse HTTPS accessible publiquement. Le serveur associé au point de terminaison push doit disposer d'un certificat SSL valide signé par une autorité de certification. Le service Pub/Sub envoie les messages aux points de terminaison push situés dans la région Google Cloud où le service stocke les messages. Le service Pub/Sub distribue les messages provenant de la même région Google Cloud de la manière la plus optimale possible.

Pub/Sub n'a plus besoin d'une preuve de propriété pour le push domaines d'URL d'abonnement. Si votre domaine reçoit des requêtes POST inattendues de la part de Pub/Sub, vous pouvez signaler un abus présumé.

Authentification

Activez l'authentification. Lorsque cette option est activée, les messages distribués par Pub/Sub au point de terminaison push incluent un en-tête d'autorisation pour pour autoriser le point de terminaison à authentifier la requête. Les mécanismes d'authentification et d'autorisation automatiques sont disponibles pour les points de terminaison de fonctions App Engine Standard et Cloud Run hébergés dans le même projet que l'abonnement.

La configuration de l'authentification d'un abonnement push authentifié se compose d'un compte de service géré par l'utilisateur, et les paramètres d'audience sont spécifiés dans une commande create, patch ou ModifyPushConfig . Vous devez également attribuer un rôle spécifique à un agent de service, comme indiqué dans la section suivante.

• Compte de service géré par l'utilisateur (obligatoire). Compte de service associé au déploiement abonnement. Ce compte est utilisé comme revendication email du jeton Web JSON (JWT) généré. Voici la liste des exigences concernant le compte de service :

  • Ce compte de service doit appartenir au même projet que l'abonnement push.

  • Le compte principal qui crée ou modifie l'abonnement push doit disposer de l'autorisation iam.serviceAccounts.actAs sur le compte de service ; Vous pouvez accorder un rôle avec cette autorisation au projet, au dossier ou à l'organisation pour autoriser l'appelant à usurper l'identité de plusieurs comptes de service ou accorder un rôle avec cette autorisation au compte de service pour autoriser l'appelant à usurper l'identité de ce compte de service uniquement.

• Audience : Chaîne unique, ne respectant pas la casse, utilisée par le webhook pour valider l'audience visée par ce jeton spécifique.

• Agent de service (obligatoire).

  • Pub/Sub crée automatiquement un compte de service au format service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com.

  • Cet agent de service doit disposer du rôle Autorisation iam.serviceAccounts.getOpenIdToken (incluse dans roles/iam.serviceAccountTokenCreator ) afin d'autoriser Pub/Sub à créer des jetons JWT pour des requêtes push authentifiées.

Désencapsulation de la charge utile

L'option Enable payload unwrapping (Activer la désencapsulation de la charge utile) supprime toutes les métadonnées des messages Pub/Sub, à l'exception des données de message. Avec le déballage de la charge utile, les données du message sont transmises directement en tant que corps HTTP.

• Écrivez des métadonnées. Réajoute les métadonnées de message précédemment supprimées dans la section en-tête de requête.

VPC Service Controls

Pour un projet protégé par VPC Service Controls, notez les limites suivantes pour les abonnements push:

• Vous ne pouvez créer des abonnements push que pour lesquels le point de terminaison push est défini sur un service Cloud Run avec une URL run.app par défaut ou une exécution Workflows. Les domaines personnalisés ne fonctionnent pas.

• Lorsque vous acheminez des événements via Eventarc vers des destinations Workflows pour lesquelles le point de terminaison push est défini sur une exécution Workflows, vous ne pouvez créer que des abonnements push via Eventarc.

• Vous ne pouvez pas mettre à jour les abonnements push existants. Ces abonnements push continuent de fonctionner, bien qu'elles ne soient pas protégées par VPC Service Controls.

Créer un abonnement push

Les exemples suivants montrent comment créer un abonnement avec une distribution push, à l'aide des paramètres par défaut fournis.

Par défaut, les abonnements utilisent la distribution pull, sauf si vous définissez explicitement une configuration push, comme illustré dans les exemples suivants.

Console

Pour créer un abonnement push, procédez comme suit:

1. Dans la console Google Cloud, accédez à la page Abonnements.

   Accéder à la page "Abonnements"

2. Cliquez sur Créer un abonnement.
3. Dans le champ ID d'abonnement, saisissez un nom.

   Pour savoir comment nommer un abonnement, consultez la section Consignes de dénomination d'un sujet ou d'un abonnement.

4. Choisissez ou créez un sujet dans le menu déroulant. L'abonnement reçoit les messages du sujet.
5. Sélectionnez Push pour le champ Type de diffusion.
6. Spécifiez une URL de point de terminaison.
7. Conservez toutes les autres valeurs par défaut.
8. Cliquez sur Créer.

Vous pouvez également créer un abonnement à partir de la section Sujets. Ce raccourci est utile pour associer des sujets à des abonnements.

1. Dans la console Google Cloud, accédez à la page Sujets.

   Accéder aux sujets

2. Cliquez sur à côté du sujet pour lequel vous souhaitez créer un abonnement.
3. Dans le menu contextuel, sélectionnez Créer un abonnement.
4. Saisissez l'ID de l'abonnement.

   Pour savoir comment nommer un abonnement, consultez Consignes pour nommer un sujet ou un abonnement.

5. Sélectionnez Push dans le champ Type de distribution.
6. Spécifiez une URL de point de terminaison.
7. Conservez toutes les autres valeurs par défaut.
8. Cliquez sur Créer.

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. Pour créer un abonnement push, exécutez la commande gcloud pubsub subscriptions create.

   gcloud pubsub subscriptions create SUBSCRIPTION_ID \
       --topic=TOPIC_ID \
       --push-endpoint=PUSH_ENDPOINT

   Remplacez les éléments suivants :

   • SUBSCRIPTION_ID: nom ou ID de votre nouvelle transmission abonnement.
   • TOPIC_ID : nom ou ID de votre sujet.
   • PUSH_ENDPOINT: URL à utiliser comme point de terminaison pour cet abonnement. Exemple :https://myproject.appspot.com/myhandler

REST

Pour créer un abonnement push, utilisez la méthode projects.subscriptions.create :

Requête :

La demande doit être authentifiée à l'aide d'un jeton d'accès dans l'en-tête Authorization. Pour obtenir un jeton d'accès pour les identifiants par défaut actuels de l'application, exécutez la commande suivante : gcloud auth application-default print-access-token.

PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID
Authorization: Bearer ACCESS_TOKEN

Corps de la requête :

{
  "topic": "projects/PROJECT_ID/topics/TOPIC_ID",
  // Only needed if you are using push delivery
  "pushConfig": {
    "pushEndpoint": "PUSH_ENDPOINT"
  }
}

Où :

PROJECT_ID est l'ID de votre projet.

SUBSCRIPTION_ID est l'ID de votre abonnement.

TOPIC_ID est l'ID de votre sujet.

PUSH_ENDPOINT est une URL à utiliser comme point de terminaison. Exemple :https://myproject.appspot.com/myhandler

Réponse :

{
  "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++

Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage C++ qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour C++.

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#

Avant d'essayer cet exemple, suivez les instructions de configuration pour C# du guide de démarrage rapide de Pub/Sub : utiliser les bibliothèques clientes. Pour en savoir plus, consultez les API C# Pub/Sub documentation de référence.

Pour vous authentifier auprès de Pub/Sub, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

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

Avant d'essayer cet exemple, suivez les instructions de configuration pour Go du guide de démarrage rapide de Pub/Sub : utiliser les bibliothèques clientes. Pour en savoir plus, consultez les API Go Pub/Sub documentation de référence.

Pour vous authentifier auprès de Pub/Sub, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

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

Avant d'essayer cet exemple, suivez les instructions de configuration de Java dans le Guide de démarrage rapide de Pub/Sub bibliothèques clientes. Pour en savoir plus, consultez les API Java Pub/Sub documentation de référence.

Pour vous authentifier auprès de Pub/Sub, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

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

Avant d'essayer cet exemple, suivez les instructions de configuration pour PHP du guide de démarrage rapide de Pub/Sub : utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub PHP.

Pour vous authentifier auprès de Pub/Sub, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

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

Avant d'essayer cet exemple, suivez les instructions de configuration de Python dans le Guide de démarrage rapide de Pub/Sub bibliothèques clientes. Pour en savoir plus, consultez les API Python Pub/Sub documentation de référence.

Pour vous authentifier auprès de Pub/Sub, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

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

Avant d'essayer cet exemple, suivez les instructions de configuration de Ruby dans le Guide de démarrage rapide de Pub/Sub bibliothèques clientes. Pour en savoir plus, consultez les API Ruby Pub/Sub documentation de référence.

Pour vous authentifier auprès de Pub/Sub, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

# 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."

Surveiller les abonnements push

Cloud Monitoring fournit un certain nombre de métriques surveiller les abonnements.

Pour obtenir la liste de toutes les métriques disponibles liées à Pub/Sub et leurs descriptions, consultez la documentation de surveillance de Pub/Sub.

Vous pouvez également surveiller les abonnements depuis Pub/Sub.

Étape suivante

• Créer ou modifier un abonnement à l'aide de commandes gcloud
• Créez ou modifiez un abonnement à l'aide des API REST.