Ce document présente un abonnement pull, 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 des messages synchrone ou asynchrone.
Avant de commencer
Avant de lire ce document, assurez-vous de maîtriser les points suivants:
Découvrez le fonctionnement de Pub/Sub et les différents termes de Pub/Sub.
Les différents types d'abonnements acceptés par Pub/Sub et les raisons pour lesquelles vous pouvez utiliser un abonnement pull.
Workflow pour les abonnements 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'envoient pas ces demandes directement. Les clients s'appuient plutôt sur la bibliothèque cliente de haut niveau fournie par Google Cloud, qui effectue des demandes d'extraction en flux continu en interne et distribue les messages de manière asynchrone. Pour un client abonné qui a besoin de mieux contrôler le mode d'extraction des messages, Pub/Sub utilise une bibliothèque gRPC de bas niveau générée automatiquement. Cette bibliothèque effectue des requêtes d'extraction ou d'extraction par flux directement. Ces requêtes peuvent être synchrones ou asynchrones.
Les deux images suivantes illustrent le workflow entre un client abonné et un abonnement pull.


Workflow d'extraction
Le workflow d'extraction est présenté comme suit (voir la figure 1) :
- Le client abonné appelle explicitement la méthode
pull
, qui demande la distribution des messages. Cette requête correspond auPullRequest
, comme illustré sur l'image. Le serveur Pub/Sub répond avec zéro, un ou plusieurs messages et ID d'accusé de réception. Une réponse ne comportant aucun message ou comportant une erreur n'indique pas nécessairement qu'aucun message n'est disponible à recevoir. Cette réponse correspond à la valeur
PullResponse
, comme illustré sur 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 est traité et qu'il n'a pas besoin d'être à nouveau distribué.
Pour une seule demande d'extraction en flux continu, un client abonné peut renvoyer 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 pull déterminent la manière dont vous écrivez des messages dans votre abonnement. Pour en savoir plus, consultez les 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 des messages:
- Extraction
- StreamingPull
Utilisez les RPC unary Acknowledge etModifyAck pertinents lorsque vous recevez des messages à l'aide de ces API. Les deux API Pub/Sub sont décrites dans les onglets suivants.
API StreamingPull
Dans la mesure du possible, les bibliothèques clientes Pub/Sub utilisent StreamingPull pour un débit maximal et une latence minimale. Bien que vous ne puissiez jamais utiliser directement l'API StreamingPull, il est important de savoir en quoi elle diffère 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 connexion est dépassé, le serveur affiche une erreur indiquant que la ressource est épuisée. La bibliothèque cliente relance automatiquement les erreurs hors quota.
Si aucune erreur ne se produit ou si le quota de connexion est à nouveau disponible, le serveur envoie en continu des messages au client connecté.
Si ou lorsque le quota de débit est dépassé, le serveur cesse d'envoyer des messages. Cependant, la connexion n'est pas interrompue. Dès que 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 la connexion de manière récurrente après un certain délai 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 dès qu'ils sont disponibles. L'API StreamingPull minimise ainsi la latence et maximise le débit des messages.
En savoir plus sur les méthodes REST StreamingPull : StreamingPullRequest et StreamingPullResponse
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 pull correspond à une seule demande d'extraction'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 d'épuisement de la ressource.
En l'absence d'erreur ou si le quota de débit est à nouveau disponible, le serveur ne répond avec zéro ou plusieurs messages et ID d'accusé de réception.
Lorsque vous utilisez l'API Pull unaire, une réponse ne comportant aucun message ou comportant une erreur n'indique pas nécessairement qu'il n'y a pas de message disponible à recevoir.
L'utilisation de l'API Pull ne garantit pas une faible latence ni un débit élevé des messages. Pour atteindre un débit élevé et une faible latence avec l'API Pull, vous devez avoir plusieurs requêtes simultanées en attente. De nouvelles requêtes sont créées lorsque d'anciennes requêtes reçoivent une réponse. L'architecture d'une telle solution est sujette aux erreurs et difficile à entretenir. Nous vous recommandons d'utiliser l'API StreamingPull dans de tels cas d'utilisation.
N'utilisez l'API Pull au lieu de l'API StreamingPull que si vous avez besoin d'exercer un contrôle strict sur les éléments suivants:
- Nombre de messages que le client abonné peut traiter
- La mémoire et les 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 orientée vers l'extraction.
Pour en savoir plus sur les méthodes REST 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 pull asynchrone dissocie la réception des messages du traitement des messages dans un client abonné. Il s'agit du mode par défaut pour la plupart des clients abonnés. Le mode pull asynchrone peut utiliser l'API StreamingPull ou l'API pull unaire. Le mode pull 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 trouverez plus d'informations sur les bibliothèques clientes dans la suite de ce document.
Mode pull synchrone
En mode pull synchrone, la réception et le traitement des messages se produisent en séquence et ne sont pas dissociés les uns des autres. Par conséquent, à l'instar des API StreamingPull et des API Pull unaires, 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 pour lesquelles une faible latence et un 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. Une application présentant 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 niveau et une bibliothèque cliente générée automatiquement de bas niveau.
Bibliothèque cliente Pub/Sub de haut niveau
La bibliothèque cliente de haut niveau fournit des options pour contrôler les délais de confirmation via la gestion des baux. Ces options sont plus précises que lorsque vous configurez les délais de confirmation à 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 distribution commandée, la distribution "exactement une fois" et le contrôle de flux.
Nous vous recommandons d'utiliser le mode pull asynchrone et l'API StreamingPull avec la bibliothèque cliente de haut niveau. Les langages compatibles avec Google Cloud ne sont pas tous compatibles avec l'API Pull dans la bibliothèque cliente de haut niveau.
Pour utiliser les bibliothèques clientes de haut niveau, consultez la page 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. Lorsque vous utilisez la bibliothèque cliente de bas niveau générée automatiquement, vous devez coder manuellement des fonctionnalités telles que la distribution commandée, la distribution de type "exactement une fois", le contrôle de flux et la gestion des baux.
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 toutes les langues 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ù l'utilisation directe de l'API Pull est judicieuse. 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 la page Présentation des API Pub/Sub.
Exemples de code pour les bibliothèques clientes
Exemples de code StreamingPull et de code 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
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.
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
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.
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++.
sC#
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.
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
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.
Gérer les erreurs à l'aide de la bibliothèque cliente de haut niveau
Les exemples suivants montrent comment gérer les erreurs qui surviennent 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
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.
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
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.
Exemples de code pull unaire
Vous trouverez ci-dessous un exemple de code permettant d'pull 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++.
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
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.
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 contient plusieurs messages, Pub/Sub les ordonne avec la même clé de tri. Voici quelques mises en garde importantes:
Définir une valeur pour
max_messages
dans la requête ne garantit pas quemax_messages
sont renvoyés, même s'il y a un tel nombre de messages en attente. L'API Pub/Sub Pull peut renvoyer un nombre inférieur àmax_messages
afin de réduire la latence de distribution des messages facilement disponibles.Une réponse pull fournie avec 0 message ne doit pas être utilisée comme indicateur de l'absence de messages en attente. Il est possible d'obtenir une réponse avec 0 message et d'avoir une requête ultérieure qui renvoie des messages.
Pour atteindre une faible latence de distribution des messages avec le mode pull unaire, il est essentiel de disposer simultanément de plusieurs demandes d'extraction en attente. À 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 la section Quotas et limites de Pub/Sub.
Étapes suivantes
Créez un abonnement pull pour votre sujet.
Créez ou modifiez un abonnement avec gcloud CLI.
Créez ou modifiez un abonnement avec les API REST.
Créez ou modifiez un abonnement avec les API RPC.