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 créer un abonnement push à l'aide de la Google Cloud console, de Google Cloud CLI, de la bibliothèque cliente ou de l' API Pub/Sub.

Avant de commencer

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

Rôles et autorisations requis

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 sujet

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

Abonnements multiprojets

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

Propriétés des abonnements 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 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 même Google Cloud région où le service Pub/Sub stocke les messages. Le service Pub/Sub distribue les messages provenant de la même Google Cloud région de la manière la plus optimale 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 vérifier le jeton Web JSON (JWT) utilisé dans la requête. Si un abonné dispose d'un pare-feu, vous pouvez recevoir 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 abus présumé.

Authentification

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

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

Public visé. Chaîne unique, ne respectant pas la casse, que le webhook utilise pour valider l'audience visée par un jeton spécifique.
Compte de service. Pub/Sub crée automatiquement un compte de service au format service-{PROJECT_NUMBER}@gcp-sa-pubsub..

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 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'utilisateurpour pouvoir 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 la désencapsulation de la charge utile, les données de message sont transmises directement en tant que corps HTTP.

Vous pouvez également activer l'option Écrire les métadonnées. L'option Écrire les métadonnées ajoute à nouveau les métadonnées de message précédemment supprimées dans 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 des messages à des adresses VPC privées. Toutefois, vous pouvez utiliser Eventarc pour acheminer des messages vers des 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 limitations suivantes concernant 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, même s'ils 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 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 :

Dans la Google Cloud console, 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 la section Consignes de dénomination d'un sujet ou d'un abonnement.
Choisissez ou créez un sujet dans le menu déroulant. L'abonnement reçoit les messages du sujet.
Sélectionnez Push comme Type de distribution.
Spécifiez une URL de point de terminaison.
Conservez toutes les autres valeurs par défaut.
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 Google Cloud console, 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.
Saisissez l'ID de l'abonnement.
Pour savoir comment nommer un abonnement, consultez la section Consignes de dénomination d'un sujet ou d'un abonnement.
Sélectionnez Push comme Type de distribution.
Spécifiez une URL de point de terminaison.
Conservez toutes les autres valeurs par défaut.
Cliquez sur Créer.

gcloud

Dans la Google Cloud console, activez Cloud Shell.

Activer Cloud Shell

En bas de la Google Cloud console, une session Cloud Shell démarre et affiche une invite de ligne de commande. Cloud Shell est un environnement shell dans lequel Google Cloud CLI est déjà installé, 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 gcloud pubsub subscriptions create commande.
```
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 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 projects.subscriptions.create méthode :

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


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 une liste d'exemples de code v1, consultez les exemples de code obsolètes.

Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Go 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 pour 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 Pub/Sub pour Java .


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 pour 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 pour 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 sur l'API Pub/Sub pour Python.

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 afficher une liste d'exemples de code Ruby v2, consultez les exemples de code obsolètes.

Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Ruby 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 pour 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 leur description, consultez la documentation de surveillance pour Pub/Sub.

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

Étape suivante

Créer ou modifier un abonnement avec gcloud commandes.
Créer ou modifier un abonnement avec des API REST.

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