Cette page explique comment recevoir et accuser réception des messages à l'aide de la méthode "exactement une fois" la sémantique. Seul le type d'abonnement pull est compatible avec la distribution "exactement une fois", y compris les abonnés qui utilisent API StreamingPull :
Transférer et exporter des abonnements ne prennent pas en charge la distribution de type "exactement une fois".
Versions recommandées de la bibliothèque cliente
- Pour des performances optimales, utilisez la dernière version de la bibliothèque cliente, Python v2.13.6 ou version ultérieure, Java v1.120.11 ou version ultérieure, PHP v1.39.0 ou version ultérieure, C# v3.2.0 ou version ultérieure, C++ v2.1.0, Accéder v1.25.1 ou ultérieure, Nœud v3.2.0 ou version ultérieure et Ruby v2.12.1 ou ultérieure.
Diffusion de type "exactement une fois"
Pub/Sub permet la distribution "exactement une fois" dans une région cloud, en fonction d'une règle de pare-feu unique définie par Pub/Sub ID du message.
Lorsque cette fonctionnalité est activée, Pub/Sub fournit les éléments suivants:
Aucune nouvelle distribution n'est effectuée une fois le message confirmé.
Aucune nouvelle distribution n'est effectuée tant qu'un message est en attente. Un message est considéré en attente jusqu'à l'expiration du délai de confirmation ou jusqu'à ce que le message soit confirmé.
En cas de plusieurs envois valides, en raison du délai de confirmation ou accusé de réception négatif déclenché par le client, uniquement L'ID d'accusé de réception peut être utilisé pour accuser réception du message. Toute requête avec d'un ID d'accusé de réception précédent.
Nouvelle distribution ou doublon
Il est important de comprendre la différence entre les prévisions et les imprévus à nouveau.
Une nouvelle diffusion peut se produire en raison d'un accusé de réception négatif d'un message initié par le client ou lorsque le client n'étend pas le délai d'accusé de réception du message avant son expiration. Nouvelles livraisons sont considérés comme valides et fonctionnent comme prévu.
Pour résoudre les problèmes liés aux renvois, consultez la section Gérer les doublons.
Un doublon se produit lorsqu'un message est renvoyé après un accusé de réception réussi ou avant l'expiration du délai d'accusé de réception.
Un message distribué conserve le même ID entre deux tentatives.
Les abonnements pour lesquels la distribution de type "exactement une fois" est activée ne reçoivent pas de doublons livraisons.
Prise en charge de la distribution de type "exactement une fois" dans les bibliothèques clientes
Les bibliothèques clientes compatibles disposent d'une interface de confirmation avec réponse (par exemple, Go). Vous pouvez utiliser cette interface pour vérifier si la demande de confirmation a abouti. Si la demande d'accusé de réception aboutit, les clients sont assurés de ne pas recevoir de nouvelle livraison. Si la demande de confirmation échoue, le les clients peuvent s'attendre à une nouvelle livraison.
Les clients peuvent également utiliser les bibliothèques clientes compatibles sans le d'accusé de réception. Cependant, dans de tels cas, les échecs de confirmation peuvent entraîner une nouvelle distribution silencieuse des messages.
Les bibliothèques clientes compatibles disposent d'interfaces permettant de définir la durée de prolongation de bail (exemple: OK). Vous devez définir une valeur élevée pour l'extension de location minimale. pour éviter toute expiration d'accusé de réception liée au réseau. La valeur maximale est définie sur 600 secondes.
Valeurs et plage par défaut des variables associées à la distribution de type "exactement une fois" et les noms des variables peuvent différer d'une bibliothèque cliente à l'autre. Pour exemple, dans la bibliothèque cliente Java, les variables suivantes contrôlent une distribution de type "exactement une fois".
Variable | Description | Valeur |
---|---|---|
setEnableExactlyOnceDelivery |
Active ou désactive la distribution "exactement une fois". | true ou false Default=false |
minDurationPerAckExtension |
Durée minimale, en secondes, pour prolonger le délai d'accusé de réception des modifications. | Plage=0 à 600 Par défaut=aucun |
maxDurationPerAckExtension |
Durée maximale, en secondes, pour prolonger le délai d'accusé de réception des modifications. | Plage=0 à 600 Par défaut=aucun |
Dans le cas d'une distribution de type "exactement une fois", modifyAckDeadline
ou acknowledgment
La requête envoyée à Pub/Sub échoue lorsque l'ID d'accusé de réception a déjà expiré. Dans ces
le service considère l'ID d'accusé de réception expiré comme non valide,
une livraison plus récente
est peut-être déjà en cours. C'est la conception pour une fois
la livraison. Les requêtes acknowledgment
et ModifyAckDeadline
renvoient ensuite
INVALID_ARGUMENT
. Lorsque la distribution de type "exactement une fois" est désactivée, ces
renvoient OK
si les ID d'accusé de réception ont expiré.
Pour garantir que les requêtes acknowledgment
et ModifyAckDeadline
sont valides
d'accusé de réception, pensez à définir la valeur
minDurationPerAckExtension
sur un nombre élevé.
Points à prendre en compte concernant les régions
La garantie de distribution de type "exactement une fois" ne s'applique que lorsque les abonnés se connectent au dans la même région. Si votre application d'abonné est répartie dans plusieurs régions, cela peut entraîner la duplication de la distribution des messages, la diffusion de type "exactement une fois". Les éditeurs peuvent envoyer des messages à n'importe quelle région, la garantie est toujours maintenue.
Par défaut, lorsque vous exécutez votre application dans Google Cloud, se connecte au point de terminaison Pub/Sub dans la même région. Par conséquent, votre application dans une seule région de Google Cloud garantit généralement que vous interagissez avec une seule région.
Lorsque vous exécutez votre application d'abonné en dehors de Google Cloud ou dans plusieurs régions, vous pouvez vous assurer de vous connecter à une seule région à l'aide d'un point de terminaison localisé lors de la configuration client. Tous les points de terminaison de l'emplacement pour Pub/Sub pointent vers un seul dans différentes régions. Pour en savoir plus sur les points de terminaison locaux, consultez la page Points de terminaison Pub/Sub. Pour obtenir la liste de tous les points de terminaison localisés pour Pub/Sub, consultez la section Liste des points de terminaison locaux.
Créer des abonnements avec distribution de type "exactement une fois"
Vous pouvez créer un abonnement avec distribution de type "exactement une fois" à l'aide de la console Google Cloud, de Google Cloud CLI, de la bibliothèque cliente ou de l'API Pub/Sub.
Abonnement pull
Console
Pour créer un abonnement pull avec distribution de type "exactement une fois", procédez comme suit:
Dans la console Google Cloud, accédez à la page Abonnements.
Cliquez sur Créer un abonnement.
Saisissez l'ID de l'abonnement.
Choisissez ou créez un sujet dans le menu déroulant.
L'abonnement reçoit les messages du sujet.
Dans la section Distribution de type "exactement une fois", sélectionnez Activer la distribution de type "exactement une fois".
Cliquez sur Créer.
gcloud
Pour créer un abonnement pull avec distribution de type "exactement une fois", utilisez la méthode
gcloud pubsub subscriptions create
avec l'option --enable-exactly-once-delivery
:
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --enable-exactly-once-delivery
Remplacez les éléments suivants :
- SUBSCRIPTION_ID : ID de l'abonnement à créer
- TOPIC_ID : ID du sujet à associer à l'abonnement
REST
Pour créer un abonnement avec distribution de type "exactement une fois", utilisez la méthode
projects.subscriptions.create
.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID Authorization: Bearer $(gcloud auth print-access-token)
Remplacez les éléments suivants :
- PROJECT_ID : ID du projet dans lequel créer l'abonnement
- SUBSCRIPTION_ID : ID de l'abonnement à créer
Pour créer un abonnement pull avec distribution de type "exactement une fois", spécifiez ce dans le corps de la requête:
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "enableExactlyOnceDelivery": true, }
Remplacez les éléments suivants :
- PROJECT_ID : ID du projet contenant le sujet.
- TOPIC_ID : ID du sujet à associer à l'abonnement
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++.
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#.
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'essayer cet exemple, suivez les instructions d'installation dans le langage Java 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 Java.
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.
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 sur l'API Pub/Sub pour Node.js.
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 sur l'API Pub/Sub pour Node.js.
Ruby
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 sur l'API Pub/Sub pour Ruby.
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 sur l'API Pub/Sub pour PHP.
S'abonner avec la distribution de messages "exactement une fois"
Voici quelques exemples de code pour l'abonnement avec distribution de type "exactement une fois" à l'aide de la bibliothèque cliente.
Abonnement pull
Go
Avant d'essayer cet exemple, suivez les instructions de configuration de Go dans le Guide de démarrage rapide de Pub/Sub bibliothèques clientes. Pour en savoir plus, consultez les API Go Pub/Sub documentation de référence.
Pour vous authentifier auprès de Pub/Sub, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Java
Avant d'essayer cet exemple, suivez les instructions de configuration de Java dans le Guide de démarrage rapide de Pub/Sub bibliothèques clientes. Pour en savoir plus, consultez les API Java Pub/Sub documentation de référence.
Pour vous authentifier auprès de Pub/Sub, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Node.js
Avant d'essayer cet exemple, suivez les instructions de configuration de Node.js dans le Guide de démarrage rapide de Pub/Sub bibliothèques clientes. Pour en savoir plus, consultez les API Node.js Pub/Sub documentation de référence.
Pour vous authentifier auprès de Pub/Sub, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
PHP
Avant d'essayer cet exemple, suivez les instructions de configuration de PHP dans le Guide de démarrage rapide de Pub/Sub bibliothèques clientes. Pour en savoir plus, consultez les API PHP Pub/Sub documentation de référence.
Pour vous authentifier auprès de Pub/Sub, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Python
Avant d'essayer cet exemple, suivez les instructions de configuration de Python dans le Guide de démarrage rapide de Pub/Sub bibliothèques clientes. Pour en savoir plus, consultez les API Python Pub/Sub documentation de référence.
Pour vous authentifier auprès de Pub/Sub, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Ruby
Avant d'essayer cet exemple, suivez les instructions de configuration de Ruby dans le Guide de démarrage rapide de Pub/Sub bibliothèques clientes. Pour en savoir plus, consultez les API Ruby Pub/Sub documentation de référence.
Pour vous authentifier auprès de Pub/Sub, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
C++
Avant d'essayer cet exemple, suivez les instructions de configuration de C++ dans le Guide de démarrage rapide de Pub/Sub bibliothèques clientes. Pour en savoir plus, consultez les API C++ Pub/Sub documentation de référence.
Pour vous authentifier auprès de Pub/Sub, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
C#
Avant d'essayer cet exemple, suivez les instructions de configuration de C# dans le Guide de démarrage rapide de Pub/Sub bibliothèques clientes. Pour en savoir plus, consultez les API C# Pub/Sub documentation de référence.
Pour vous authentifier auprès de Pub/Sub, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Node.js (TypeScript)
Avant d'essayer cet exemple, suivez les instructions de configuration de Node.js dans le Guide de démarrage rapide de Pub/Sub bibliothèques clientes. Pour en savoir plus, consultez les API Pub/Sub Node.js documentation de référence.
Pour vous authentifier auprès de Pub/Sub, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Surveiller les abonnements à distribution de type "exactement une fois"
La
subscription/exactly_once_warning_count
enregistre le nombre d'événements
peut entraîner d'éventuelles renvois (valides ou en double). Cette métrique comptabilise les
de fois que Pub/Sub ne parvient pas à traiter les requêtes associées à
ID d'accusé de réception (requête ModifyAckDeadline
ou acknowledgment
). Raisons
pour l'échec peut être lié au serveur ou au client. Par exemple, si la persistance
utilisée pour gérer l'indisponibilité des informations de livraison de type "exactement une fois",
serait un événement basé sur le serveur. Si le client tente d'accuser réception d'un message avec
un ID d'accusé de réception non valide, il s'agit d'un événement basé sur le client.
Comprendre la métrique
subscription/exactly_once_warning_count
capture des événements qui peuvent ou non
de nouvelles livraisons et peut générer
du bruit en fonction du comportement du client. Pour
exemple: requêtes acknowledgment
ou ModifyAckDeadline
répétées avec des
Les ID d'accusé de réception incrémentent la métrique de manière répétée.
Les métriques suivantes sont également utiles pour comprendre le comportement des clients:
subscription/expired_ack_deadlines_count
indique le nombre d'expirations d'ID d'accusé de réception. Reconnaissance L'expiration des ID peut entraîner des échecs pourModifyAckDeadline
et Requêtesacknowledgment
.service.serviceruntime.googleapis.com/api/request_count
peut être utilisée pour capturer les défaillances deModifyAckDeadline
ouacknowledgment
lorsqu'elles parviennent à Google Cloud, mais pas atteindre Pub/Sub. Cette métrique ne peut pas être utilisée par exemple, lorsque les clients sont déconnectés de Google Cloud.
Dans la plupart des cas d'événements d'échec pouvant faire l'objet de nouvelles tentatives, les bibliothèques clientes compatibles relancer la requête automatiquement.
Quotas
Les abonnements à la distribution de type "exactement une fois" sont soumis à des quotas supplémentaires. exigences. Ces quotas s'appliquent aux éléments suivants:
- Nombre de messages consommés par des abonnements avec distribution de type "exactement une fois" activées par région.
- Nombre de messages confirmés ou dont le délai est prolongé lors de l'utilisation avec la distribution de type "exactement une fois" activée par région.
Pour en savoir plus sur ces quotas, consultez le tableau Quotas.
Distribution de type "exactement une fois" et abonnements commandés
Pub/Sub permet la distribution de type "exactement une fois" avec la distribution commandée.
Dans le cas d'une commande avec distribution de type "exactement une fois", Pub/Sub s'attend à ce que les accusés de réception doivent être dans l’ordre. Si les accusés de réception sont dans le désordre, les requêtes échouent avec des erreurs temporaires. Si le délai de confirmation expire avant qu'un accusé de réception de la livraison soit envoyé, le client que le message soit distribué à nouveau. C'est pourquoi, lorsque vous utilisez la commande distribution de type "exactement une fois", le débit du client est limité à des milliers messages par seconde.
Distribution de type "exactement une fois" et abonnements push
Pub/Sub n'accepte la distribution "exactement une fois" qu'avec les abonnements pull.
Les clients qui consomment les messages des abonnements push accusent réception des messages en répondant aux requêtes push avec une réponse positive. Toutefois, les clients ne savent pas si l'abonnement Pub/Sub a reçu la réponse l'a traité. Cela diffère des abonnements pull, où l'accusé de réception sont initiées par les clients et l'abonnement Pub/Sub répond si la requête a été correctement traitée. Pour cette raison, la sémantique de distribution de type "exactement une fois" ne concorde pas bien avec les abonnements push.
Bon à savoir
Si aucun délai d'accusé de réception n'est spécifié au moment de CreateSubscription, les abonnements avec distribution de type "exactement une fois" ont un accusé de réception par défaut de 60 secondes.
Des délais d'accusé de réception par défaut plus longs permettent d'éviter en raison d'événements réseau. Les bibliothèques clientes compatibles n'utilisent pas délai par défaut de confirmation de l'abonnement.
Les abonnements à la livraison de type exactement une fois ont considérablement augmenté de publication et d'abonnement par rapport aux abonnements standards.
Si vous avez besoin d'un débit élevé, vos clients de distribution de type "exactement une fois" doivent également utiliser le traitement pull en flux continu.
Un abonnement peut recevoir plusieurs copies du même message en raison de doubles du côté de la publication, même si la distribution "exactement une fois" est activée. Les doublons côté publication peuvent être dus à plusieurs tentatives de publication uniques ou le service Pub/Sub. Les publications uniques multiples par le client éditeur, lors des nouvelles tentatives, entraînent de nouvelles livraisons avec des ID de message différents. Les publications uniques multiples par le service Pub/Sub, pour répondre à une requête de publication client, entraînent de nouvelles livraisons avec les mêmes ID de message.
Vous pouvez relancer les échecs dans
subscription/exactly_once_warning_count
, et les bibliothèques clientes compatibles relancent ces automatiquement. Toutefois, les échecs liés à des ID d'accusé de réception non valides ne peuvent pas une nouvelle tentative.