Ce document présente un abonnement par extraction, son workflow et les propriétés associées.
Dans un abonnement pull, un client abonné demande des messages au serveur Pub/Sub.
Le mode pull peut utiliser l'une des deux API de service, Pull ou StreamingPull. Pour exécuter l'API choisie, vous pouvez sélectionner une bibliothèque cliente de haut niveau fournie par Google ou une bibliothèque cliente de bas niveau générée automatiquement. Vous pouvez également choisir entre le traitement asynchrone et synchrone des messages.
Avant de commencer
Avant de lire ce document, assurez-vous de connaître les éléments suivants :
Fonctionnement de Pub/Sub et différents termes Pub/Sub.
Les différents types d'abonnements compatibles avec Pub/Sub et les raisons pour lesquelles vous pouvez utiliser un abonnement par extraction.
Workflow d'abonnement pull
Pour un abonnement pull, votre client abonné envoie des requêtes à un serveur Pub/Sub pour récupérer les messages. Le client abonné utilise l'une des API suivantes :
La plupart des clients abonnés n'effectuent pas ces demandes directement. Au lieu de cela, les clients s'appuient sur la bibliothèque cliente de haut niveau fournie par Trusted Cloud by S3NS, qui effectue des requêtes d'extraction de flux en interne et fournit des messages de manière asynchrone. Pour un client abonné qui a besoin d'un meilleur contrôle sur la façon dont les messages sont extraits, Pub/Sub utilise une bibliothèque gRPC de bas niveau et générée automatiquement. Cette bibliothèque effectue directement des requêtes d'extraction ou d'extraction en flux continu. Ces requêtes peuvent être synchrones ou asynchrones.
Les deux images suivantes illustrent le workflow entre un client abonné et un abonnement par extraction.


Workflow de retrait
Le workflow d'extraction est le suivant (voir figure 1) :
- Le client abonné appelle explicitement la méthode
pull
, qui demande la distribution des messages. Cette requête correspond àPullRequest
, comme indiqué dans l'image. Le serveur Pub/Sub répond par zéro message ou plus et des ID de confirmation. Une réponse sans message ou avec une erreur n'indique pas nécessairement qu'aucun message n'est disponible. Cette réponse correspond à
PullResponse
, comme illustré dans l'image.Le client abonné appelle explicitement la méthode
acknowledge
. Le client utilise l'ID d'accusé de réception renvoyé pour confirmer que le message a été traité et qu'il n'a pas besoin d'être envoyé à nouveau.
Pour une seule demande d'extraction de flux, un client abonné peut recevoir plusieurs réponses en raison de la connexion ouverte. En revanche, une seule réponse est renvoyée pour chaque demande d'extraction;extraction.
Propriétés d'un abonnement pull
Les propriétés que vous configurez pour un abonnement par extraction déterminent la façon dont vous écrivez des messages dans votre abonnement. Pour en savoir plus, consultez Propriétés d'abonnement.
API de service Pub/Sub
L'abonnement pull Pub/Sub peut utiliser l'une des deux API suivantes pour récupérer les messages :
- Pull
- StreamingPull
Utilisez les RPC unaires Acknowledge et ModifyAckDeadline lorsque vous recevez des messages à l'aide de ces API. Les deux API Pub/Sub sont décrites dans les sections suivantes.
API StreamingPull
Dans la mesure du possible, les bibliothèques clientes Pub/Sub utilisent StreamingPull afin d'assurer un débit maximal et une latence minimale. Bien que vous ne vous servirez peut-être jamais directement de l'API StreamingPull, il est important de comprendre ce qui la distingue de l'API Pull.
L'API StreamingPull s'appuie sur une connexion bidirectionnelle persistante pour recevoir plusieurs messages dès qu'ils sont disponibles. Voici le workflow :
Le client envoie une requête au serveur pour établir une connexion. Si le quota de connexions est dépassé, le serveur renvoie une erreur "Ressource épuisée". La bibliothèque cliente réessaie automatiquement les erreurs de dépassement de quota.
Si aucune erreur ne se produit ou si le quota de connexions est à nouveau disponible, le serveur envoie en continu des messages au client connecté.
Si le quota de débit est dépassé, le serveur cesse d'envoyer des messages. Toutefois, la connexion n'est pas interrompue. Lorsque le quota de débit est à nouveau disponible, le flux reprend.
Le client ou le serveur finit par fermer la connexion.
L'API StreamingPull maintient une connexion ouverte. Les serveurs Pub/Sub ferment régulièrement la connexion après un certain temps pour éviter une connexion persistante de longue durée. La bibliothèque cliente rouvre automatiquement une connexion StreamingPull.
Les messages sont envoyés à la connexion lorsqu'ils sont disponibles. L'API StreamingPull minimise ainsi la latence et maximise le débit des messages.
En savoir plus sur les méthodes RPC StreamingPull : StreamingPullRequest et StreamingPullResponse.
API Pull
Cette API est un RPC unaire traditionnel basé sur un modèle de requête et de réponse. Une seule réponse d'extraction correspond à une seule demande d'extraction d'extraction. Voici le workflow :
Le client envoie une requête de messages au serveur. Si le quota de débit est dépassé, le serveur renvoie une erreur de ressource épuisée.
S'il n'y a pas d'erreur ou si le quota de débit est à nouveau disponible, le serveur répond par zéro message ou plus et par des ID d'accusé de réception.
Lorsque vous utilisez l'API Pull unaire, une réponse sans message ou avec une erreur n'indique pas nécessairement qu'aucun message n'est disponible.
L'utilisation de l'API Pull ne garantit pas une faible latence ni un débit de messages élevé. Pour obtenir un débit élevé et une faible latence avec l'API Pull, vous devez avoir plusieurs requêtes en attente simultanément. De nouvelles demandes sont créées lorsque d'anciennes demandes reçoivent une réponse. Concevoir une telle solution est source d'erreurs et difficile à gérer. Nous vous recommandons d'utiliser l'API StreamingPull pour ces cas d'utilisation.
N'utilisez l'API Pull au lieu de l'API StreamingPull que si vous avez besoin d'un contrôle strict sur les éléments suivants :
- Nombre de messages que le client abonné peut traiter
- Mémoire et ressources du client
Vous pouvez également utiliser cette API lorsque votre abonné est un proxy entre Pub/Sub et un autre service fonctionnant de manière plus axée sur l'extraction.
En savoir plus sur les méthodes REST de type "pull" : Méthode : projects.subscriptions.pull.
En savoir plus sur les méthodes RPC Pull : PullRequest et PullResponse.
Types de modes de traitement des messages
Choisissez l'un des modes d'extraction suivants pour vos clients abonnés.
Mode pull asynchrone
Le mode d'extraction asynchrone découple la réception des messages de leur traitement dans un client abonné. Ce mode est celui par défaut pour la plupart des clients abonnés. Le mode pull asynchrone peut utiliser l'API StreamingPull ou l'API Pull unaire. L'extraction asynchrone peut également utiliser la bibliothèque cliente de haut niveau ou la bibliothèque cliente de bas niveau générée automatiquement.
Vous en apprendrez plus sur les bibliothèques clientes plus loin dans ce document.
Mode pull synchrone
En mode pull synchrone, la réception et le traitement des messages se font de manière séquentielle et ne sont pas dissociés. Par conséquent, comme pour les API StreamingPull par rapport aux API Pull unitaires, le traitement asynchrone offre une latence plus faible et un débit plus élevé que le traitement synchrone.
N'utilisez le mode pull synchrone que pour les applications où la faible latence et le débit élevé ne sont pas les facteurs les plus importants par rapport à d'autres exigences. Par exemple, une application peut être limitée à l'utilisation du modèle de programmation synchrone uniquement. Une application avec des contraintes de ressources peut également nécessiter un contrôle plus précis de la mémoire, du réseau ou du processeur. Dans ce cas, utilisez le mode synchrone avec l'API Pull unaire.
Bibliothèques clientes Pub/Sub
Pub/Sub propose une bibliothèque cliente de haut et de bas niveau générée automatiquement.
Bibliothèque cliente Pub/Sub de haut niveau
La bibliothèque cliente de haut niveau propose des options permettant de contrôler les délais de confirmation à l'aide de la gestion des baux. Ces options sont plus précises que lorsque vous configurez les délais d'accusé de réception à l'aide de la console ou de la CLI au niveau de l'abonnement. La bibliothèque cliente de haut niveau est également compatible avec des fonctionnalités telles que la diffusion ordonnée, la diffusion exactement une fois et le contrôle du flux.
Nous vous recommandons d'utiliser l'extraction asynchrone et l'API StreamingPull avec la bibliothèque cliente de haut niveau. Tous les langages compatibles avecTrusted Cloud by S3NS ne sont pas compatibles avec l'API Pull dans la bibliothèque cliente de haut niveau.
Pour utiliser les bibliothèques clientes de haut niveau, consultez Bibliothèques clientes Pub/Sub.
Bibliothèque cliente Pub/Sub de bas niveau générée automatiquement
Une bibliothèque cliente de bas niveau est disponible dans les cas où vous devez utiliser directement l'API Pull. Vous pouvez utiliser le traitement synchrone ou asynchrone avec la bibliothèque cliente de bas niveau générée automatiquement. Vous devez coder manuellement des fonctionnalités telles que la diffusion ordonnée, la diffusion exactement une fois, le contrôle du flux et la gestion des baux lorsque vous utilisez la bibliothèque cliente de bas niveau générée automatiquement.
Vous pouvez utiliser le modèle de traitement synchrone lorsque vous utilisez la bibliothèque cliente de bas niveau générée automatiquement pour tous les langages compatibles. Vous pouvez utiliser la bibliothèque cliente de bas niveau générée automatiquement et le mode pull synchrone dans les cas où il est judicieux d'utiliser directement l'API Pull. Par exemple, vous pouvez avoir une logique d'application existante qui repose sur ce modèle.
Pour utiliser directement les bibliothèques clientes de bas niveau générées automatiquement, consultez Présentation des API Pub/Sub.
Exemples de code de bibliothèque cliente
Exemples de code StreamingPull et de bibliothèque cliente de haut niveau
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
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 consulter la liste des exemples de code de la version 1, consultez les exemples de code obsolètes.
Avant d'essayer cet exemple, suivez les instructions de configuration pour Go du guide de démarrage rapide : Utiliser les 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.
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.
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.
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 la liste des exemples de code Ruby v2, consultez les exemples de code obsolètes.
Avant d'essayer cet exemple, suivez les instructions de configuration pour Ruby du guide de démarrage rapide : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Ruby.
Récupérer des attributs personnalisés à l'aide de la bibliothèque cliente de haut niveau
Les exemples suivants montrent comment extraire des messages de manière asynchrone et récupérer les attributs personnalisés à partir des métadonnées.
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
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 consulter la liste des exemples de code de la version 1, consultez les exemples de code obsolètes.
Avant d'essayer cet exemple, suivez les instructions de configuration pour Go du guide de démarrage rapide : Utiliser les 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.
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.
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.
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 la liste des exemples de code Ruby v2, consultez les exemples de code obsolètes.
Avant d'essayer cet exemple, suivez les instructions de configuration pour Ruby du guide de démarrage rapide : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Ruby.
Gérer les erreurs à l'aide de la bibliothèque cliente de haut niveau
Les exemples suivants montrent comment gérer les erreurs survenant lors de l'abonnement à des messages.
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
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 consulter la liste des exemples de code de la version 1, consultez les exemples de code obsolètes.
Avant d'essayer cet exemple, suivez les instructions de configuration pour Go du guide de démarrage rapide : Utiliser les 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.
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.
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.
Ruby
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 consulter la liste des exemples de code de la version 1, consultez les exemples de code obsolètes.
Avant d'essayer cet exemple, suivez les instructions de configuration pour Go du guide de démarrage rapide : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Go.
Exemples de code de pull unaire
Voici un exemple de code permettant d'extraire et de confirmer un nombre fixe de messages.
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#.
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.
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.
PHP
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
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 la liste des exemples de code Ruby v2, consultez les exemples de code obsolètes.
Avant d'essayer cet exemple, suivez les instructions de configuration pour Ruby du guide de démarrage rapide : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Ruby.
Protocole
Requête :
POST https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription:pull
{
"returnImmediately": "false",
"maxMessages": "1"
}
Réponse :
200 OK
{
"receivedMessages": [{
"ackId": "dQNNHlAbEGEIBERNK0EPKVgUWQYyODM2LwgRHFEZDDsLRk1SK...",
"message": {
"data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
"messageId": "19917247034"
}
}]
}
Requête :
POST https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription:acknowledge
{
"ackIds": [
"dQNNHlAbEGEIBERNK0EPKVgUWQYyODM2LwgRHFEZDDsLRk1SK..."
]
}
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.
Pub/Sub transmet une liste de messages. Si la liste comporte plusieurs messages, Pub/Sub les classe suivant la même clé de tri. Voici quelques points importants à retenir :
Définir une valeur pour
max_messages
dans la requête ne garantit pas quemax_messages
seront renvoyés, même s'il y a autant de messages dans le backlog. L'API Pull de Pub/Sub peut renvoyer moins demax_messages
messages afin de réduire la latence de distribution des messages qui sont facilement disponibles.Une réponse d'extraction contenant zéro message ne doit pas être utilisée comme indicateur de l'absence de messages dans le backlog. Il est possible d'obtenir une réponse avec 0 message, puis d'effectuer une requête ultérieure qui renvoie des messages.
Pour obtenir une faible latence de distribution des messages avec le mode pull unaire, il est essentiel de disposer de nombreuses requêtes pull en attente simultanément. Au fur et à mesure que le débit du sujet augmente, davantage de requêtes pull sont nécessaires. En général, le mode StreamingPull est préférable pour les applications sensibles à la latence.
Quotas et limites
Les connexions Pull et StreamingPull sont soumises à des quotas et des limites. Pour en savoir plus, consultez Quotas et limites de Pub/Sub.
Étapes suivantes
Créez un abonnement pull pour votre sujet.
Résolvez les problèmes liés à un abonnement pull.
Créez ou modifiez un abonnement avec la gcloud CLI.
Créez ou modifiez un abonnement avec les API REST.
Créez ou modifiez un abonnement avec les API RPC.