Exporter des messages Pub/Sub Lite vers Pub/Sub

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

Ce document explique comment configurer l'exportation automatique des messages Pub/Sub Lite vers Pub/Sub.

Voici quelques scénarios dans lesquels vous pouvez utiliser cette fonctionnalité:

  • Interopérabilité entre les charges de travail qui utilisent à la fois Pub/Sub Lite et Pub/Sub
  • Migrer une charge de travail Pub/Sub Lite vers Pub/Sub
  • Utilisez les fonctionnalités avancées de Pub/Sub, telles que les abonnements push et le filtrage, à partir d'une application existante basée sur Pub/Sub Lite.
  • Regrouper plusieurs pipelines de données

Présentation

Pour exporter des messages de Pub/Sub Lite vers Pub/Sub, vous devez créer un type d'abonnement spécial appelé abonnement d'exportation. Un abonnement à une exportation reçoit des messages d'un sujet Lite, les convertit en messages Pub/Sub et envoie les messages convertis à un sujet Pub/Sub de destination.

Schéma d'exportation des messages Pub/Sub Lite

Un sujet Lite peut combiner des abonnements d'exportation et des abonnements standards. Les deux types d'abonnements sont identiques en termes d'utilisation des quotas et de débit de réservation. Un abonnement d'exportation consomme la capacité de débit de l'abonnement Lite et est facturé pour le débit de publication Pub/Sub.

Un abonnement à une exportation connecte un sujet Lite à un seul sujet Pub/Sub. Cependant, un sujet Lite peut avoir plusieurs abonnements d'exportation qui se connectent à différents sujets Pub/Sub (architecture de distribution ramifiée). Vous pouvez également exporter de plusieurs sujets Lite vers le même sujet Pub/Sub (architecture de fan-in).

Authentification

Un abonnement d'exportation accède aux ressources Pub/Sub Lite et Pub/Sub. Pour créer un abonnement à l'exportation, vous devez disposer des autorisations suivantes:

  • pubsublite.subscriptions.create. Les rôles prédéfinis suivants disposent de cette autorisation:

    • roles/pubsublite.admin
    • roles/pubsublite.editor

    Consultez la page Contrôle des accès pour Pub/Sub Lite.

  • pubsub.topics.get. Les rôles prédéfinis suivants incluent cette autorisation:

    • roles/pubsub.admin
    • roles/pubsub.editor
    • roles/pubsub.viewer

    Consultez la page Contrôle des accès pour Pub/Sub.

Agents de service

Un abonnement à une exportation est publié en votre nom dans un sujet Pub/Sub. Pour ce faire, elle utilise un compte de service géré par Google.

Lorsque vous créez le premier abonnement à l'exportation dans un projet, un agent de service Pub/Sub Lite géré par Google est automatiquement créé. Si vous créez des abonnements d'exportation supplémentaires dans le même projet, ils utilisent le même agent de service. L'agent de service possède le schéma de nommage suivant : service-<your_project_number>@gcp-sa-pubsublite.iam.gserviceaccount.com.

L'agent de service est créé avec les autorisations nécessaires pour publier sur tous les sujets Pub/Sub et Pub/Sub Lite dans le même projet que l'abonnement à l'exportation. Si votre sujet Pub/Sub de destination se trouve dans un projet différent de celui de l'abonnement d'exportation, vous devez accorder des autorisations supplémentaires à l'agent de service en ajoutant le rôle Éditeur Pub/Sub (roles/pubsub.publisher). Vous pouvez accorder des autorisations pour un projet entier ou un sujet individuel. Nous vous recommandons d'accorder des autorisations au niveau du sujet, conformément au principe du moindre privilège.

Pour en savoir plus, consultez la page Contrôler les accès via la console Google Cloud. Vous pouvez également utiliser la commande gcloud projects add-iam-policy-binding pour ajouter des rôles IAM:

gcloud pubsub topics add-iam-policy-binding TOPIC_NAME \
 --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsublite.iam.gserviceaccount.com
 --role=roles/pubsub.publisher

Remplacez les éléments suivants :

  • TOPIC_NAME: nom du sujet Pub/Sub de destination pour ajouter la liaison de stratégie IAM.
  • PROJECT_NUMBER: numéro du projet de l'abonnement à l'exportation Pub/Sub Lite.

Créer un abonnement pour l'exportation

Vous pouvez créer un abonnement d'exportation Lite à l'aide de la console Google Cloud, de Google Cloud CLI ou de l'API Pub/Sub Lite.

Un abonnement à une exportation Lite doit se trouver dans le même projet et le même emplacement que le sujet Lite auquel il est associé. Pour créer le sujet Lite, consultez Créer et gérer des sujets Lite.

Si vous associez un abonnement à une exportation à un sujet Lite, assurez-vous que tous les messages publiés sur ce sujet sont compatibles avec Pub/Sub. Pour en savoir plus, consultez Compatibilité des messages.

Une fois l'abonnement exporté, vous ne pouvez pas le transformer en abonnement standard, et inversement.

Console

  1. Accédez à la page Abonnements Lite.

    Accéder aux abonnements Lite

  2. Cliquez sur Créer un abonnement Lite.

  3. Saisissez un ID d'abonnement Lite.

  4. Sélectionnez un sujet Lite pour recevoir des messages de celui-ci.

  5. Sélectionnez Distribuer les messages immédiatement ou Distribuer les messages après leur stockage.

  6. Sélectionnez un type de décalage de départ.

  7. Sélectionnez Exporter vers le sujet Pub/Sub.

  8. Dans la liste Sujet de la destination, choisissez un sujet Pub/Sub pour recevoir les messages Lite exportés.

  9. Facultatif. Spécifiez un thème de lettres mortes.

    1. Cochez la case Activer les lettres mortes.
    2. Sélectionnez un sujet Lite à utiliser comme lettre morte ou cliquez sur Créer un sujet Lite pour créer un sujet en lettres mortes. Le sujet des lettres mortes doit se trouver dans le même emplacement (zone ou région) et dans le projet que l'abonnement d'exportation.

  10. Cliquez sur Créer.

gcloud

Pour créer un abonnement à l'exportation, utilisez la commande gcloud pubsub lite-subscriptions create:

gcloud pubsub lite-subscriptions create SUBSCRIPTION_ID \
  --location=LOCATION \
  --topic=TOPIC_ID \
  --export-pubsub-topic=PUBSUB_TOPIC_NAME \
  --export-dead-letter-topic=DEAD_LETTER_TOPIC_ID \
  --export-desired-state=DESIRED_STATE

Remplacez les éléments suivants :

  • SUBSCRIPTION_ID: ID de l'abonnement Lite à créer.
  • LOCATION: emplacement de l'abonnement Lite.
  • TOPIC_ID: ID du sujet Lite à associer à l'abonnement Lite.
  • PUBSUB_TOPIC_NAME: nom du sujet Pub/Sub vers lequel exporter. Indiquez le nom complet si le sujet se trouve dans un autre projet: projects/my-project-id/topics/my-topic-id.
  • DEAD_LETTER_TOPIC_ID : facultatif. ID d'un sujet Lite à utiliser comme sujet de lettres mortes. Le sujet des lettres mortes doit se trouver dans le même emplacement (zone ou région) et dans le projet que l'abonnement d'exportation.
  • DESIRED_STATE : facultatif. État de départ de l'abonnement. Les valeurs suivantes sont acceptées :
    • active: l'abonnement exporte les messages Lite vers Pub/Sub. (Par défaut.)
    • paused: l'exportation des messages Lite est suspendue.

Si la requête aboutit, la ligne de commande affiche une confirmation :

Created [SUBSCRIPTION_ID].

Protocole

Pour créer un abonnement à une exportation Lite, envoyez une requête POST semblable à celle-ci:

POST https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID
Authorization: Bearer $(gcloud auth print-access-token)

Remplacez les éléments suivants :

  • REGION: région dans laquelle stocker l'abonnement Lite.
  • PROJECT_NUMBER: numéro du projet dans lequel créer l'abonnement Lite.
  • LOCATION: nom d'un emplacement compatible avec Pub/Sub Lite.
  • SUBSCRIPTION_ID: ID de l'abonnement Lite.

Spécifiez les champs suivants dans le corps de la requête :

{
  "topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID",
  "deliveryConfig": {
      "deliveryRequirement": "DELIVERY_REQUIREMENT",
  },
  "exportConfig": {
      "desiredState": "DESIRED_STATE",
      "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
      "pubsubConfig": {
          "topic": "PUBSUB_TOPIC_NAME"
      }
  }
}

Remplacez les éléments suivants :

  • DELIVERY_REQUIREMENT: exigence de livraison, DELIVER_AFTER_STORED ou DELIVER_IMMEDIATELY.
  • DESIRED_STATE: état de départ de l'abonnement. Les valeurs suivantes sont acceptées :
    • ACTIVE: l'abonnement exporte les messages Lite vers Pub/Sub.
    • PAUSED: l'exportation des messages Lite est suspendue.
  • DEAD_LETTER_TOPIC_ID: ID d'un sujet Lite existant à utiliser comme sujet à lettres mortes. Le sujet doit se trouver au même emplacement (zone ou région) et au projet que l'abonnement à l'exportation lui-même.
  • PUBSUB_TOPIC_NAME: nom du sujet Pub/Sub vers lequel exporter. Exemple de format: projects/my-project-id/topics/my-topic-id.

Si la requête aboutit, la réponse est l'abonnement Lite au format JSON :

{
  "deliveryConfig": {
      "deliveryRequirement": "DELIVERY_REQUIREMENT",
  },
  "exportConfig": {
      "desiredState": "DESIRED_STATE",
      "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
      "pubsubConfig": {
          "topic": "PUBSUB_TOPIC_NAME"
      },
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID",
  "topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID",
}

Go

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

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsublite"
)

func createPubsubExportSubscription(w io.Writer, projectID, region, location, topicID, subID, pubsubTopicID string) error {
	// projectID := "my-project-id"
	// region := "us-central1"
	// NOTE: location can be either a region ("us-central1") or a zone ("us-central1-a")
	// For a list of valid locations, see https://cloud.google.com/pubsub/lite/docs/locations.
	// location := "us-central1"
	// NOTE: topic and subscription must be in the same region/zone (e.g. "us-central1-a")
	// topicID := "my-topic"
	// subID := "my-subscription"
	// pubsubTopicID := "destination-topic-id"
	ctx := context.Background()
	client, err := pubsublite.NewAdminClient(ctx, region)
	if err != nil {
		return fmt.Errorf("pubsublite.NewAdminClient: %v", err)
	}
	defer client.Close()

	// Initialize the subscription to the oldest retained messages for each
	// partition.
	targetLocation := pubsublite.AtTargetLocation(pubsublite.Beginning)

	sub, err := client.CreateSubscription(ctx, pubsublite.SubscriptionConfig{
		Name:                fmt.Sprintf("projects/%s/locations/%s/subscriptions/%s", projectID, location, subID),
		Topic:               fmt.Sprintf("projects/%s/locations/%s/topics/%s", projectID, location, topicID),
		DeliveryRequirement: pubsublite.DeliverImmediately, // Can also be DeliverAfterStored.
		// Configures an export subscription that writes messages to a Pub/Sub topic.
		ExportConfig: &pubsublite.ExportConfig{
			DesiredState: pubsublite.ExportActive, // Can also be ExportPaused.
			Destination: &pubsublite.PubSubDestinationConfig{
				Topic: fmt.Sprintf("projects/%s/topics/%s", projectID, pubsubTopicID),
			},
		},
	}, targetLocation)
	if err != nil {
		return fmt.Errorf("client.CreateSubscription got err: %v", err)
	}
	fmt.Fprintf(w, "Created export subscription: %s\n", sub.Name)
	return nil
}

Java

Avant d'exécuter cet exemple, suivez les instructions de configuration de Java dans les bibliothèques clientes Pub/Sub Lite. 

import com.google.api.gax.rpc.AlreadyExistsException;
import com.google.cloud.pubsublite.AdminClient;
import com.google.cloud.pubsublite.AdminClientSettings;
import com.google.cloud.pubsublite.BacklogLocation;
import com.google.cloud.pubsublite.CloudRegion;
import com.google.cloud.pubsublite.CloudRegionOrZone;
import com.google.cloud.pubsublite.CloudZone;
import com.google.cloud.pubsublite.ProjectNumber;
import com.google.cloud.pubsublite.SeekTarget;
import com.google.cloud.pubsublite.SubscriptionName;
import com.google.cloud.pubsublite.SubscriptionPath;
import com.google.cloud.pubsublite.TopicName;
import com.google.cloud.pubsublite.TopicPath;
import com.google.cloud.pubsublite.proto.ExportConfig;
import com.google.cloud.pubsublite.proto.ExportConfig.PubSubConfig;
import com.google.cloud.pubsublite.proto.ExportConfig.State;
import com.google.cloud.pubsublite.proto.Subscription;
import com.google.cloud.pubsublite.proto.Subscription.DeliveryConfig;
import com.google.cloud.pubsublite.proto.Subscription.DeliveryConfig.DeliveryRequirement;
import java.util.concurrent.ExecutionException;

public class CreatePubsubExportSubscriptionExample {

  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String cloudRegion = "your-cloud-region";
    char zoneId = 'b';
    String topicId = "your-topic-id";
    String subscriptionId = "your-subscription-id";
    String pubsubTopicId = "destination-topic-id";
    long projectNumber = Long.parseLong("123456789");
    // True if using a regional location. False if using a zonal location.
    // https://cloud.google.com/pubsub/lite/docs/topics
    boolean regional = false;

    createPubsubExportSubscriptionExample(
        cloudRegion, zoneId, projectNumber, topicId, subscriptionId, pubsubTopicId, regional);
  }

  public static void createPubsubExportSubscriptionExample(
      String cloudRegion,
      char zoneId,
      long projectNumber,
      String topicId,
      String subscriptionId,
      String pubsubTopicId,
      boolean regional)
      throws Exception {

    CloudRegionOrZone location;
    if (regional) {
      location = CloudRegionOrZone.of(CloudRegion.of(cloudRegion));
    } else {
      location = CloudRegionOrZone.of(CloudZone.of(CloudRegion.of(cloudRegion), zoneId));
    }

    TopicPath topicPath =
        TopicPath.newBuilder()
            .setProject(ProjectNumber.of(projectNumber))
            .setLocation(location)
            .setName(TopicName.of(topicId))
            .build();

    SubscriptionPath subscriptionPath =
        SubscriptionPath.newBuilder()
            .setLocation(location)
            .setProject(ProjectNumber.of(projectNumber))
            .setName(SubscriptionName.of(subscriptionId))
            .build();

    com.google.pubsub.v1.TopicName pubsubTopicName =
        com.google.pubsub.v1.TopicName.of(String.valueOf(projectNumber), pubsubTopicId);

    Subscription subscription =
        Subscription.newBuilder()
            .setDeliveryConfig(
                // Possible values for DeliveryRequirement:
                // - `DELIVER_IMMEDIATELY`
                // - `DELIVER_AFTER_STORED`
                // You may choose whether to wait for a published message to be successfully written
                // to storage before the server delivers it to subscribers. `DELIVER_IMMEDIATELY` is
                // suitable for applications that need higher throughput.
                DeliveryConfig.newBuilder()
                    .setDeliveryRequirement(DeliveryRequirement.DELIVER_IMMEDIATELY))
            .setExportConfig(
                // Configures an export subscription that writes messages to a Pub/Sub topic.
                ExportConfig.newBuilder()
                    // Possible values for State:
                    // - `ACTIVE`: enable message processing.
                    // - `PAUSED`: suspend message processing.
                    .setDesiredState(State.ACTIVE)
                    .setPubsubConfig(
                        PubSubConfig.newBuilder().setTopic(pubsubTopicName.toString())))
            .setName(subscriptionPath.toString())
            .setTopic(topicPath.toString())
            .build();

    // Target location within the message backlog that the subscription should be initialized to.
    SeekTarget initialLocation = SeekTarget.of(BacklogLocation.BEGINNING);

    AdminClientSettings adminClientSettings =
        AdminClientSettings.newBuilder().setRegion(location.extractRegion()).build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources, or
    // use "try-with-close" statement to do this automatically.
    try (AdminClient adminClient = AdminClient.create(adminClientSettings)) {
      Subscription response = adminClient.createSubscription(subscription, initialLocation).get();
      System.out.println(response.getAllFields() + " created successfully.");
    } catch (ExecutionException e) {
      try {
        throw e.getCause();
      } catch (AlreadyExistsException alreadyExists) {
        System.out.println("This subscription already exists.");
      } catch (Throwable throwable) {
        throwable.printStackTrace();
      }
    }
  }
}

Python

Avant d'exécuter cet exemple, suivez les instructions de configuration de Python dans les bibliothèques clientes Pub/Sub Lite. 

from google.api_core.exceptions import AlreadyExists
from google.cloud.pubsub_v1 import PublisherClient
from google.cloud.pubsublite import AdminClient, Subscription, ExportConfig
from google.cloud.pubsublite.types import (
    BacklogLocation,
    CloudRegion,
    CloudZone,
    SubscriptionPath,
    TopicPath,
)

def create_lite_pubsub_export_subscription(
    project_number,
    cloud_region="us-central1",
    zone_id="a",
    topic_id="my-topic-id",
    subscription_id="my-subscription-id",
    pubsub_topic_id="destination-topic-id",
    regional=True,
    target_location=BacklogLocation.BEGINNING,
):
    if regional:
        location = CloudRegion(cloud_region)
    else:
        location = CloudZone(CloudRegion(cloud_region), zone_id)

    topic_path = TopicPath(project_number, location, topic_id)
    subscription_path = SubscriptionPath(project_number, location, subscription_id)
    destination_topic_path = PublisherClient.topic_path(project_number, pubsub_topic_id)

    subscription = Subscription(
        name=str(subscription_path),
        topic=str(topic_path),
        delivery_config=Subscription.DeliveryConfig(
            # Possible values for delivery_requirement:
            # - `DELIVER_IMMEDIATELY`
            # - `DELIVER_AFTER_STORED`
            # You may choose whether to wait for a published message to be successfully written
            # to storage before the server delivers it to subscribers. `DELIVER_IMMEDIATELY` is
            # suitable for applications that need higher throughput.
            delivery_requirement=Subscription.DeliveryConfig.DeliveryRequirement.DELIVER_IMMEDIATELY,
        ),
        # Configures an export subscription that writes messages to a Pub/Sub topic.
        export_config=ExportConfig(
            # Possible values for desired_state:
            # - `ACTIVE`: enable message processing.
            # - `PAUSED`: suspend message processing.
            desired_state=ExportConfig.State.ACTIVE,
            pubsub_config=ExportConfig.PubSubConfig(
                topic=destination_topic_path,
            ),
        ),
    )

    # Initialize client that will be used to send requests across threads. This
    # client only needs to be created once, and can be reused for multiple requests.
    client = AdminClient(cloud_region)
    try:
        response = client.create_subscription(subscription, target_location)
        print(f"{response.name} created successfully.")
    except AlreadyExists:
        print(f"{subscription_path} already exists.")

Mettre à jour un abonnement à l'exportation

Vous pouvez mettre à jour les abonnements Lite à l'aide de la console Google Cloud, de Google Cloud CLI ou de l'API Pub/Sub Lite. L'application des nouveaux paramètres peut prendre jusqu'à 30 secondes.

Console

  1. Accédez à la page Abonnements Lite.

    Accéder aux abonnements Lite

  2. Cliquez sur l'ID d'abonnement Lite.

  3. Sur la page Détails de l'abonnement Lite, cliquez sur Modifier.

gcloud

Pour mettre à jour un abonnement Lite, exécutez la commande gcloud pubsub lite-subscriptions update :

gcloud pubsub lite-subscriptions update SUBSCRIPTION_ID \
--location=LOCATION \
--delivery-requirement=DELIVERY_REQUIREMENT \
--export-pubsub-topic=PUBSUB_TOPIC_NAME \
--export-dead-letter-topic=DEAD_LETTER_TOPIC_ID \
--export-desired-state=DESIRED_STATE

Remplacez les éléments suivants :

  • SUBSCRIPTION_ID: ID de l'abonnement Lite
  • LOCATION: emplacement de l'abonnement Lite.
  • DELIVERY_REQUIREMENT : facultatif. Exigences liées à la diffusion (deliver-after-stored ou deliver-immediately).
  • PUBSUB_TOPIC_NAME : facultatif. Nom du sujet Pub/Sub vers lequel exporter. Spécifiez le nom complet si le sujet se trouve dans un autre projet : projects/my-project-id/topics/my-topic-id.
  • DEAD_LETTER_TOPIC_ID: ID d'un sujet Lite existant à utiliser comme sujet à lettres mortes. Le sujet doit se trouver au même emplacement (zone ou région) et au projet que l'abonnement à l'exportation lui-même.
  • DESIRED_STATE : facultatif. État souhaité de l'abonnement. Les valeurs suivantes sont acceptées :
    • active: l'abonnement exporte les messages Lite vers Pub/Sub. (Par défaut.)
    • paused: l'exportation des messages Lite est suspendue.

Si la requête aboutit, la ligne de commande affiche l'abonnement Lite :

Updated subscription [SUBSCRIPTION_ID].
deliveryConfig:
deliveryRequirement: DELIVERY_REQUIREMENT
exportConfig:
currentState: DESIRED_STATE
deadLetterTopic: projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID
desiredState: DESIRED_STATE
pubsubConfig:
  topic: PUBSUB_TOPIC_NAME
name: projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID
topic: projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID

Protocole

Pour mettre à jour un abonnement Lite, envoyez une requête PATCH comme suit :

PATCH https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID?updateMask=deliveryConfig.deliveryRequirement,exportConfig
Authorization: Bearer $(gcloud auth print-access-token)

Remplacez les éléments suivants :

  • REGION: région dans laquelle l'abonnement Lite a été créé.
  • PROJECT_NUMBER: numéro du projet dans lequel l'abonnement Lite a été créé.
  • LOCATION: emplacement de création de l'abonnement Lite.
  • SUBSCRIPTION_ID: ID de l'abonnement Lite.

Spécifiez les champs suivants dans le corps de la requête :

{
  "deliveryConfig": {
      "deliveryRequirement": "DELIVERY_REQUIREMENT",
  },
  "exportConfig": {
      "desiredState": "DESIRED_STATE",
      "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
      "pubsubConfig": {
          "topic": "PUBSUB_TOPIC_NAME"
      }
  }
}

Remplacez les éléments suivants :

  • DELIVERY_REQUIREMENT: exigence de livraison, DELIVER_AFTER_STORED ou DELIVER_IMMEDIATELY.
  • DESIRED_STATE: état souhaité pour l'abonnement. Les valeurs suivantes sont acceptées :
    • ACTIVE: l'abonnement exporte les messages Lite vers Pub/Sub.
    • PAUSED: l'exportation des messages Lite est suspendue.
  • DEAD_LETTER_TOPIC_ID: ID d'un sujet Lite existant à utiliser comme sujet à lettres mortes. Le sujet doit se trouver au même emplacement (zone ou région) et au projet que l'abonnement à l'exportation lui-même.
  • PUBSUB_TOPIC_NAME: nom du sujet Pub/Sub de destination. Exemple de format : projects/my-project-id/topics/my-topic-id.

Si la requête aboutit, la réponse est l'abonnement Lite au format JSON :

{
"deliveryConfig": {
  "deliveryRequirement": "DELIVERY_REQUIREMENT",
},
"exportConfig": {
  "desiredState": "DESIRED_STATE",
  "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
  "pubsubConfig": { "topic": "PUBSUB_TOPIC_NAME" }
},
"name": "projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID",
"topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID",
}

Suspendre ou démarrer un abonnement à l'exportation

Les abonnements exportés possèdent un paramètre appelé état souhaité qui présente l'une des deux valeurs suivantes:

  • Actif: l'abonnement exporte les messages Lite vers Pub/Sub.
  • Suspendu: l'exportation des messages Lite est suspendue.

Pour modifier l'état souhaité dans la console Google Cloud:

  1. Accédez à la page Abonnements Lite.

    Accéder aux abonnements Lite

  2. Cliquez sur l'ID d'abonnement Lite.

  3. Sur la page Détails de l'abonnement Lite, cliquez sur Suspendre ou sur Démarrer.

Vous pouvez également mettre à jour l'état souhaité à l'aide de Google Cloud CLI ou de l'API Pub/Sub Lite. Consultez la section Mettre à jour un abonnement à une exportation.

Bonnes pratiques

Cette section décrit certaines bonnes pratiques concernant l'utilisation des abonnements exportés.

Réservations

Nous vous recommandons d'utiliser un abonnement d'exportation avec réservation plutôt que de définir explicitement la capacité de débit de l'abonnement.

Compatibilité des messages

Si un message Pub/Sub Lite n'est pas compatible avec Pub/Sub, l'abonnement d'exportation ne le publie pas dans Pub/Sub. Au lieu de cela, il place le message dans le sujet des lettres mortes, le cas échéant. Si aucun sujet en lettres mortes n'a été attribué, les messages incompatibles sont simplement ignorés.

Lors de la publication de messages dans le sujet Lite, tenez compte des problèmes de compatibilité suivants:

  • Clés : Les clés Pub/Sub Lite sont de type bytes, tandis que les clés de tri Pub/Sub sont de type string. Pour être compatible, la clé Pub/Sub Lite ne doit contenir que des caractères UTF-8.

  • Attributs : Les attributs de message doivent respecter les conditions suivantes:

    • Pour être compatibles, tous les attributs de message Pub/Sub Lite doivent avoir une seule valeur. Pub/Sub Lite accepte les attributs de message à valeurs multiples, mais Pub/Sub n'accepte que les attributs à valeur unique.
    • Les attributs de message ne doivent pas dépasser les limites de messages Pub/Sub, y compris le nombre maximal d'attributs par message, ainsi que la taille maximale de la clé et de la valeur par attribut.

Sujet de lettres mortes

Pour conserver et gérer les messages incompatibles, nous vous recommandons d'utiliser un sujet en lettres mortes. Vous pouvez attribuer un sujet en lettres mortes lorsque vous créez l'abonnement à exporter ou mettre à jour un abonnement existant pour utiliser un sujet en lettres mortes. Si l'abonnement reçoit un message incompatible avec Pub/Sub, il le publie dans le sujet des lettres mortes.

Un sujet de lettre morte est un sujet Pub/Sub Lite standard. Il doit se trouver dans le même emplacement et le même projet que l'abonnement d'exportation, et il doit s'agir d'un sujet différent du sujet source.

En règle générale, un sujet de lettres mortes présente une faible utilisation du débit. Par conséquent, nous vous recommandons d'attribuer une réservation au sujet des lettres mortes plutôt que d'allouer le débit au sujet.

Erreurs de distribution

Un abonnement à une exportation tente de distribuer tous les messages compatibles au sujet Pub/Sub de destination. Si la distribution des messages échoue, l'abonnement à l'exportation est suspendu. Pour trouver la catégorie d'erreur, consultez la métrique subscription/export_status. Les valeurs suivantes indiquent une erreur:

  • PERMISSION_DENIED: autorisations insuffisantes pour exporter les messages.
  • NOT_FOUND: une ou plusieurs ressources (par exemple, le sujet de destination n'existent pas).

Pour en savoir plus sur le dépannage, consultez Résoudre les problèmes liés aux abonnements.

Une fois l'erreur résolue, l'abonnement à l'exportation redémarre automatiquement en raison de nouvelles tentatives périodiques.

Tarifs

Les ressources Pub/Sub Lite et Pub/Sub consommées par l'abonnement d'exportation vous sont facturées. Plus précisément, le débit et le stockage alloués à l'abonnement Pub/Sub Lite sont configurés pour le sujet Pub/Sub Lite. La publication dans le sujet Pub/Sub de destination vous est également facturée. Consultez la page Tarifs de Pub/Sub.

L'utilisation de la fonctionnalité d'exportation est gratuite et il n'y a aucune différence de prix entre les abonnements à l'exportation Pub/Sub Lite et les abonnements standards.

Résoudre les problèmes liés à l'exportation des abonnements

Cette section fournit des conseils de dépannage pour les abonnements exportés.

L'abonnement à l'exportation est suspendu

Si l'abonnement est suspendu, aucun message n'est exporté.

Pour détecter ce problème:

  • Google Cloud Console: consultez les détails de l'abonnement. Si l'abonnement est suspendu, les options État souhaité et État actuel sont définies sur Paused.

  • Métriques: la métrique subscription/export_status est PAUSED.

Pour résoudre ce problème, démarrez l'abonnement.

Le sujet de destination ou le sujet des lettres mortes a été supprimé

Si vous supprimez le sujet Pub/Sub associé à un abonnement à l'exportation ou le sujet des lettres mortes, une erreur se produit.

Pour détecter ce problème:

  • Google Cloud Console: consultez les détails de l'abonnement. Si le sujet a été supprimé, l'état actuel est Not found.

  • Métriques: métrique subscription/export_status. Si le sujet a été supprimé, la valeur est NOT_FOUND.

Pour résoudre ce problème, vérifiez le sujet Pub/Sub de destination et le sujet des lettres mortes (le cas échéant).

Si le sujet Pub/Sub de destination a été supprimé, recréez le sujet avec le même nom. L'abonnement aux exportations reprend la publication, car les autorisations n'ont pas été modifiées.

Si le sujet des lettres mortes a été supprimé, créez un sujet de lettres mortes et mettez à jour l'abonnement d'exportation pour y faire référence.

Messages incompatibles

Si les messages ne sont pas compatibles avec Pub/Sub, ils ne sont pas exportés.

Pour détecter ce problème:

  • Métriques: la métrique subscription/unexportable_message_count indique le nombre de messages incompatibles qui n'ont pas pu être exportés.

Pour résoudre ce problème, utilisez un sujet de lettre morte pour conserver les messages incompatibles. Examinez les messages pour déterminer la cause, puis transformez-les et republiez-les si nécessaire. Consultez Compatibilité des messages.

Limitation de l'exportation

Pour détecter ce problème:

  • Métriques: la métrique subscription/flow_control_status indique un motif de contrôle de flux de NO_CLIENT_TOKENS, qui indique que la limite par partition d'octets ou de messages en attente a été atteinte. Tant que le problème n'est pas résolu, le nombre de demandes d'exportation associées en attente augmente.

Cette erreur a plusieurs causes possibles. La plupart des causes possibles sont du backend, mais vérifiez les points suivants:

  • Veillez à publier des messages Lite partageant la même clé à un débit inférieur à 1 Mio/s par clé. L'abonnement d'exportation écrit les clés de message Lite en tant que clés de tri Pub/Sub, et Pub/Sub possède une limite de 1 Mio/s sur chaque clé de tri. Le dépassement de cette limite peut entraîner une limitation.

Utilisateur non autorisé à effectuer cette action

L'agent de service Pub/Sub Lite doit être autorisé à publier dans le sujet Pub/Sub de destination.

Pour détecter ce problème:

  • Google Cloud Console: consultez les détails de l'abonnement. En cas d'erreurs d'autorisation, l'état actuel est Permission denied.

  • Métriques: la métrique subscription/export_status est PERMISSON_DENIED.

Par exemple, les situations suivantes peuvent provoquer cette erreur:

  • L'agent de service Pub/Sub Lite ne dispose pas de l'autorisation ou du rôle approprié pour publier des messages dans le sujet Pub/Sub de destination dans un autre projet.
  • L'agent de service a été supprimé de la stratégie IAM du projet parent de l'abonnement d'exportation.
  • L'agent de service Pub/Sub Lite est toujours en cours de configuration. Un agent de service est créé automatiquement lorsque vous créez le premier abonnement à l'exportation dans un projet. L'erreur d'autorisation devrait être automatiquement résolue dans les 10 minutes.

Pour résoudre le problème, vérifiez si l'agent de service dispose de l'autorisation ou du rôle appropriés. Consultez la page Agents de service.

Étapes suivantes

Choisissez entre Pub/Sub et Pub/Sub Lite.