Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Créer des abonnements push

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

Avant de commencer

En savoir plus sur les abonnements
Comprendre le fonctionnement des abonnements push

Rôles et autorisations nécessaires

Pour obtenir les autorisations nécessaires pour créer un abonnement 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 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 un abonnement push. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour créer un abonnement push :

pubsub.subscriptions.create sur le projet
pubsub.topics.attachSubscription sur le thème

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

Abonnements interprojets

Si vous créez un abonnement dans un projet pour un sujet dans un autre projet, vous devez disposer de l'autorisation pubsub.subscriptions.create dans le projet dans lequel vous créez l'abonnement et de l'autorisation pubsub.topics.attachSubscription sur le sujet.

Propriétés de l'abonnement push

Les abonnements push sont compatibles avec toutes les propriétés d'abonnement courantes. Les sections suivantes décrivent les propriétés spécifiques aux abonnements push.

Points de terminaison

URL du point de terminaison (obligatoire). Adresse HTTPS accessible au public. Le serveur du point de terminaison push doit disposer d'un certificat SSL valide signé par une autorité de certification. Le service Pub/Sub envoie des messages à des points de terminaison push à partir de la même région Google Cloud où il les stocke. Le service Pub/Sub distribue les messages de la même région Google Cloud dans la mesure du possible.

Si les abonnés utilisent un pare-feu, ils ne peuvent pas recevoir de requêtes push. Pour recevoir des requêtes push, vous devez désactiver le pare-feu et valider le jeton Web JSON (JWT) utilisé dans la requête. Si un abonné dispose d'un pare-feu, il est possible que vous receviez une erreur 403 permission denied.
Pub/Sub ne nécessite pas de preuve de propriété pour les domaines d'URL d'abonnement push. Si votre domaine reçoit des requêtes POST inattendues de la part de Pub/Sub, vous pouvez signaler un cas d'utilisation abusive suspecté.

Authentification

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

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

Audience Chaîne unique non sensible à la casse que le webhook utilise pour valider l'audience prévue de ce jeton particulier.
Compte de service. Pub/Sub crée automatiquement un compte de service pour vous au format service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com.

Conditions préalables à l'activation de l'authentification

Le compte de service géré par l'utilisateur est le compte de service associé à l'abonnement push. Ce compte est utilisé comme revendication email du jeton Web JSON (JWT) généré. Voici une liste des exigences concernant le compte de service :

Ce compte de service géré par l'utilisateur doit se trouver dans le 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 géré par l'utilisateur afin d'associer le compte de service à l'abonnement push. Pour en savoir plus, consultez Associer des comptes de service à des ressources.
Autorisations requises : ce compte de service doit disposer de l'autorisation iam.serviceAccounts.getOpenIdToken (incluse dans le rôle roles/iam.serviceAccountTokenCreator) pour permettre à Pub/Sub de créer des jetons JWT pour le compte de service spécifié afin d'authentifier les requêtes push.

Désencapsulation de la charge utile

L'option 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 directement fournies en tant que corps HTTP.

Vous pouvez également activer l'option Écrire des métadonnées. L'option Écrire les métadonnées ajoute les métadonnées de message précédemment supprimées à l'en-tête de requête.

Distribuer à des adresses VPC privées

Pub/Sub fonctionne en dehors des réseaux VPC et ne peut pas envoyer directement de messages à des adresses VPC privées. Toutefois, vous pouvez utiliser Eventarc pour acheminer les messages vers les services de votre VPC. Pub/Sub peut envoyer des messages à un déclencheur Eventarc, qui peut ensuite les transférer à un service de votre VPC, tel qu'un service Cloud Run ou une exécution Workflows. Pour en savoir plus, consultez la documentation Eventarc.

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 que des abonnements push 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, mais ne sont pas protégés par VPC Service Controls.

Créer un abonnement push

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

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

Console

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

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

Accéder à "Abonnements"
Cliquez sur Créer un abonnement.
Dans le champ ID d'abonnement, saisissez un nom.

Pour savoir comment nommer un abonnement, consultez Consignes de dénomination d'un sujet ou d'un abonnement.
Dans la liste Sujet Pub/Sub, sélectionnez un sujet à partir duquel l'abonnement doit lire les messages.
Pour Type de distribution, sélectionnez Push.
Dans le champ Endpoint URL (URL du point de terminaison), saisissez l'URL du point de terminaison.
Facultatif : Pour activer l'authentification, procédez comme suit :
1. Sélectionnez Activer l'authentification.
2. Dans la liste Compte de service, sélectionnez le compte de service à utiliser pour l'authentification.
3. Facultatif : Dans le champ Audience, saisissez une audience.
Pour en savoir plus, consultez la section Authentification pour les abonnements push.
Facultatif : Pour activer la désencapsulation de la charge utile, sélectionnez Activer la désencapsulation de la charge utile.

Pour conserver les métadonnées des messages dans l'en-tête de requête, sélectionnez également Écrire les métadonnées. Cette option définit également un en-tête Content-Type pour vos messages.
(Facultatif) Dans la section Transformations, ajoutez une ou plusieurs transformations de message unique (SMT). Pour en savoir plus, consultez Créer un abonnement avec des SMT.
Facultatif : Dans le champ Filtre, saisissez une expression de filtre pour filtrer les messages de l'abonnement. Pour en savoir plus, consultez Filtrer les messages d'un abonnement.
Pour Stratégie de nouvelle tentative, sélectionnez une option. Pour en savoir plus, consultez la Politique de relance des abonnements.
Facultatif : Activez une file d'attente de lettres mortes pour recevoir les messages non distribuables.
1. Cochez la case Mise en file d'attente de lettres mortes.
2. Dans la liste Thème de messages non distribués, sélectionnez ou créez le thème de messages non distribués.
3. Dans le champ Nombre maximal de tentatives d'envoi, saisissez le nombre maximal de tentatives d'envoi.
Facultatif : Dans la section Propriétés de la diffusion, activez ou désactivez les options de diffusion suivantes :
- Distribution de type "exactement une fois"
- Tri des messages
Facultatif : Dans la section Délai de confirmation, définissez le délai dont dispose l'abonné pour traiter et confirmer les messages. Pour en savoir plus, consultez Prolonger le délai d'accusé de réception avec la gestion des baux.
Facultatif : dans la section Options de durée de vie, configurez la durée de conservation des messages par l'abonnement.
1. Dans la section Durée de conservation des messages, spécifiez la durée de conservation des messages non reconnus.
2. Pour conserver les messages confirmés et non confirmés, cochez la case Conserver les messages confirmés.
Pour en savoir plus, consultez Configurer la conservation des messages pour un abonnement.
Facultatif : Pour Période d'expiration, sélectionnez une option :
1. Pour définir l'expiration de l'abonnement, cochez la case Expire après ce nombre de jours d'inactivité. Saisissez le nombre de jours pendant lesquels l'abonnement peut rester inactif avant que Pub/Sub ne le supprime.
2. Pour désactiver l'expiration de l'abonnement, cochez la case Jamais.
Pour en savoir plus, consultez Expiration de l'abonnement.
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.

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

Accéder aux sujets
Cliquez sur à côté du sujet pour lequel vous souhaitez créer un abonnement.
Dans le menu contextuel, sélectionnez Créer un abonnement.
Sur la page Ajouter un abonnement au sujet, suivez les étapes décrites dans la procédure précédente. L'ID de la chaîne est automatiquement renseigné.

gcloud

Dans la console Google Cloud , activez Cloud Shell.

Activer Cloud Shell

En bas de la console Google Cloud , une session Cloud Shell démarre et affiche une invite de ligne de commande. Cloud Shell est un environnement de shell dans lequel la Google Cloud CLI est déjà installée, et dans lequel des valeurs sont déjà définies pour votre projet actuel. L'initialisation de la session peut prendre quelques secondes.
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 nouvel abonnement push.
- TOPIC_ID : nom ou ID de votre thème.
- 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 de l'application actuels : 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 correspond à l'ID du 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 de configuration pour C++ dans le guide de démarrage rapide : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Pub/Sub 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 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 de l'API Pub/Sub C#.


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

L'exemple suivant utilise la version majeure de la bibliothèque cliente Go Pub/Sub (v2). Si vous utilisez toujours la bibliothèque v1, consultez le guide de migration vers la v2. Pour afficher la liste des exemples de code v1, consultez les exemples de code obsolètes.

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

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

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


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

Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Node.js 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 de l'API Pub/Sub en langage 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.ts

/**
 * 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 d'installation dans le langage PHP 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 de l'API Pub/Sub en langage PHP.

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 d'installation dans le langage Python 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 de l'API Python Pub/Sub.

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

L'exemple suivant utilise la bibliothèque cliente Ruby Pub/Sub v3. Si vous utilisez toujours la bibliothèque v2, consultez le guide de migration vers la v3. Pour obtenir la liste des exemples de code Ruby v2, consultez les exemples de code obsolètes.

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

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

Surveiller les abonnements push

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

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

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

Étapes suivantes

Créez ou modifiez un abonnement à l'aide des commandes gcloud.
Créez ou modifiez un abonnement avec les API REST.

Créer des abonnements push Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.