Ce document explique comment configurer l'exportation automatique des messages Pub/Sub Lite vers Pub/Sub.
Voici quelques scénarios dans lesquels vous pourriez utiliser cette fonctionnalité:
- Interopérabilité entre les charges de travail qui utilisent une combinaison de Pub/Sub Lite et Pub/Sub.
- Migrer une charge de travail Pub/Sub Lite vers Pub/Sub
- utiliser 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.
- Consolider 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 à l'exportation reçoit les messages d'un sujet Lite, les convertit en messages Pub/Sub et envoie les messages convertis à un sujet Pub/Sub de destination.
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 à l'exportation permet de connecter un sujet Lite à un seul sujet Pub/Sub. Toutefois, un sujet Lite peut disposer de plusieurs abonnements d'exportation qui se connectent à différents sujets Pub/Sub (architecture ramifiée). Vous pouvez également exporter plusieurs sujets Lite vers le même sujet Pub/Sub (architecture fan-in).
Ratio d'économie d'énergie (EER)
Un abonnement à l'exportation accède à la fois 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 contiennent 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 disposent de 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 d'exportation est publié dans un sujet Pub/Sub en votre nom. Pour ce faire, il utilise un agent de service.
Une fois que vous avez créé le premier abonnement d'exportation dans un projet, un agent de service Pub/Sub Lite 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 dénomination suivant : service-<your_project_number>@gcp-sa-pubsublite.iam.gserviceaccount.com
.
L'agent de service est créé avec les autorisations nécessaires pour publier dans 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 associé à l'abonnement pour l'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 l'ensemble d'un projet ou pour un sujet individuel. Nous vous recommandons d'accorder des autorisations au niveau du sujet, en suivant le 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 dans lequel 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 à l'exportation Lite avec la console Google Cloud, Google Cloud CLI ou l'API Pub/Sub Lite.
Un abonnement aux exportations 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 à l'exportation à un sujet Lite, assurez-vous que tous les messages publiés dans ce sujet sont compatibles avec Pub/Sub. Pour en savoir plus, consultez l'article Compatibilité des messages.
Une fois qu'il a été créé, vous ne pouvez pas transformer un abonnement d'exportation en abonnement standard, ou inversement.
Console
Accédez à la page Abonnements Lite.
Cliquez sur Créer un abonnement Lite.
Saisissez un ID d'abonnement Lite.
Sélectionnez un sujet Lite pour recevoir des messages de celui-ci.
Sélectionnez Distribuer les messages immédiatement ou Distribuer les messages après stockage.
Sélectionnez un type de Décalage de départ.
Sélectionnez Export to Pub/Sub topic (Exporter vers un sujet Pub/Sub).
Dans la liste Sujet de destination, choisissez un sujet Pub/Sub qui recevra les messages Lite exportés.
Facultatif. Spécifiez un sujet de lettres mortes.
- Cochez la case Activer la gestion des lettres mortes.
- Sélectionnez un sujet Lite à utiliser comme file d'attente de lettres mortes ou cliquez sur Create Lite Topic (Créer un sujet Lite) pour créer un sujet de lettres mortes. Le file d'attente de lettres mortes doit se trouver au même emplacement (zone ou région) et projet que l'abonnement d'exportation.
Cliquez sur Créer.
gcloud
Pour créer un abonnement d'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 lettre morte. Le file d'attente de lettres mortes doit se trouver au même emplacement (zone ou région) et projet que l'abonnement associé à l'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 Lite Export, envoyez une requête POST
comme suit:
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: condition de livraison,
DELIVER_AFTER_STORED
ouDELIVER_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 de lettre morte. Le sujet doit se trouver dans le même emplacement (zone ou région) et dans le même projet que l'abonnement d'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.
Java
Avant d'exécuter cet exemple, suivez les instructions de configuration de Java décrites dans les bibliothèques clientes Pub/Sub Lite.
Python
Avant d'exécuter cet exemple, suivez les instructions de configuration de Python décrites dans les bibliothèques clientes Pub/Sub Lite.
Mettre à jour un abonnement d'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
Accédez à la page Abonnements Lite.
Cliquez sur l'ID d'abonnement Lite.
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. Critère de livraison,
deliver-after-stored
oudeliver-immediately
. - PUBSUB_TOPIC_NAME : facultatif. Nom du sujet Pub/Sub vers lequel effectuer l'exportation. 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: ID d'un sujet Lite existant à utiliser comme sujet de lettre morte. Le sujet doit se trouver dans le même emplacement (zone ou région) et dans le même projet que l'abonnement d'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 où l'abonnement Lite a été créé.
- 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: condition de livraison,
DELIVER_AFTER_STORED
ouDELIVER_IMMEDIATELY
. - DESIRED_STATE: état souhaité 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 de lettre morte. Le sujet doit se trouver dans le même emplacement (zone ou région) et dans le même projet que l'abonnement d'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 d'exportation
Les abonnements à l'exportation ont un paramètre appelé état souhaité, qui a 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:
Accédez à la page Abonnements Lite.
Cliquez sur l'ID d'abonnement Lite.
Sur la page Détails de l'abonnement Lite, cliquez sur Suspendre ou Commencer.
Vous pouvez également mettre à jour l'état souhaité à l'aide de la Google Cloud CLI ou de l'API Pub/Sub Lite. Consultez Mettre à jour un abonnement d'exportation.
Bonnes pratiques
Cette section décrit certaines bonnes pratiques concernant l'utilisation d'abonnements d'exportation.
Réservations
Nous vous recommandons d'utiliser un abonnement d'exportation avec une 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 à l'exportation ne le publie pas dans Pub/Sub. À la place, il place le message dans le file d'attente de lettres mortes, le cas échéant. Si aucun file d'attente de lettres mortes n'a été attribué, les messages incompatibles sont simplement supprimés.
Lorsque vous publiez des 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 typestring
. Pour être compatible, la clé Pub/Sub Lite ne doit contenir que des caractères UTF-8.Attributs : Les attributs de message sont soumis aux exigences 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 à plusieurs valeurs, mais Pub/Sub n'accepte que les attributs à valeur unique.
- Les attributs de message ne doivent pas dépasser les limites applicables aux messages Pub/Sub, y compris le nombre maximal d'attributs par message, ainsi que la taille maximale de clé et de valeur par attribut.
Sujet de lettres mortes
Pour conserver et gérer les messages incompatibles, nous vous recommandons d'utiliser un sujet de lettres mortes. Vous pouvez attribuer un file d'attente de lettres mortes lorsque vous créez l'abonnement pour l'exportation. Vous pouvez également mettre à jour un abonnement d'exportation existant pour utiliser un file d'attente de lettres mortes. Si l'abonnement reçoit un message incompatible avec Pub/Sub, il le publie dans le file d'attente de lettres mortes.
Un file d'attente de lettres mortes 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 file d'attente de lettres mortes présente un faible débit. Par conséquent, nous vous recommandons d'attribuer une réservation au file d'attente de lettres mortes plutôt que d'allouer un débit à ce sujet.
Erreurs de distribution
Un abonnement à l'exportation tente de distribuer tous les messages compatibles au sujet Pub/Sub de destination. Si la distribution du message é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 sont introuvables. Par exemple, le sujet de destination n'existe pas.
Pour en savoir plus sur le dépannage, consultez Résoudre les problèmes liés à l'exportation des abonnements.
Une fois l'erreur résolue, l'abonnement à l'exportation est automatiquement redémarré en raison de nouvelles tentatives périodiques.
Tarification
Les ressources Pub/Sub Lite et Pub/Sub utilisées par l'abonnement à l'exportation vous sont facturées. Plus précisément, vous êtes facturé pour le débit et le stockage alloués pour l'abonnement Pub/Sub Lite, qui 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 section Tarifs de Pub/Sub.
L'utilisation de la fonctionnalité d'exportation n'entraîne aucuns frais supplémentaires, et il n'y a aucune différence de prix entre les abonnements d'exportation Pub/Sub Lite et les abonnements standards.
Résoudre les problèmes liés à l'exportation des abonnements
Cette section donne des conseils de dépannage pour l'exportation d'abonnements.
L'abonnement à l'exportation est suspendu
Si l'abonnement est suspendu, aucun message n'est exporté.
Pour détecter ce problème:
Console Google Cloud: consultez les détails de l'abonnement. Si l'abonnement est suspendu, les états désired state (état souhaité) et Current state (état actuel) sont définis sur
Paused
.Métriques: la métrique
subscription/export_status
correspond àPAUSED
.
Pour résoudre ce problème, démarrez l'abonnement.
Le sujet de destination ou le file d'attente de lettres mortes a été supprimé
Si vous supprimez le sujet Pub/Sub associé à un abonnement d'exportation ou le file d'attente de lettres mortes, une erreur se produit.
Pour détecter ce problème:
Console Google Cloud: consultez les détails de l'abonnement. Si le sujet a été supprimé, l'état actuel est
Not found
.Métriques:
subscription/export_status
. Si le sujet a été supprimé, la valeur estNOT_FOUND
.
Pour résoudre ce problème, vérifiez le sujet Pub/Sub de destination et le file d'attente de lettres mortes (le cas échéant).
Si la destination Pub/Sub de destination a été supprimée, recréez le sujet avec le même nom. L'abonnement à l'exportation reprend la publication, en supposant que les autorisations n'ont pas changé.
Si le file d'attente de lettres mortes a été supprimé, créez-en un autre et mettez à jour l'abonnement à l'exportation pour le référencer.
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, conservez les messages incompatibles à l'aide d'un sujet de lettres mortes. Examinez les messages pour en déterminer la cause, puis transformez-les et republiez-les si nécessaire. Consultez la section Compatibilité des messages.
Exportation limitée
Pour détecter ce problème:
- Métriques: la métrique
subscription/flow_control_status
indique un motif de contrôle de flux défini surNO_CLIENT_TOKENS
, ce qui indique que la limite d'octets ou de messages en attente par partition a été atteinte. Jusqu'à ce que le problème soit résolu, le traitement en attente augmentera pour les abonnements d'exportation associés.
Cette erreur peut avoir plusieurs causes. La plupart des causes possibles se produisent sur le 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 à l'exportation écrit les clés de message Lite en tant que clés de tri Pub/Sub, et Pub/Sub limite de 1 Mio/s par 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:
Console Google Cloud: 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
correspond à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 à l'exportation.
- L'agent de service Pub/Sub Lite est toujours en cours de configuration. Un agent de service est automatiquement créé 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 a reçu l'autorisation ou le rôle appropriés. Consultez la section Agents de service.
Étapes suivantes
Choisissez entre Pub/Sub et Pub/Sub Lite.