Cette page explique comment lancer et suivre les opérations de recherche pour les abonnements Lite.
La fonctionnalité de recherche Pub/Sub Lite vous permet de rouvrir et de supprimer définitivement des messages. Ses cas d'utilisation sont identiques à ceux de la recherche Pub/Sub. Contrairement à Pub/Sub, vous n'avez pas besoin de configurer de sujets ou d'abonnements Lite pour utiliser la fonctionnalité de recherche, et celle-ci n'entraîne aucun coût supplémentaire.
La propagation de la recherche aux abonnés peut être suivie à l'aide d'une opération de longue durée. Il s'agit d'un modèle d'API utilisé par les produits Google Cloud pour suivre la progression des tâches de longue durée.
Lancer une recherche
Les opérations de recherche Pub/Sub Lite sont lancées hors bande (c'est-à-dire à partir de la Google Cloud CLI ou de l'API Pub/Sub Lite distincte) et propagées aux abonnés. Les abonnés en ligne sont informés de la recherche et peuvent y réagir en direct. Les abonnés hors connexion réagissent à la recherche une fois qu'ils sont en ligne.
Vous devez spécifier un emplacement cible pour la recherche, lequel peut être l'un des éléments suivants :
- Début du traitement des messages en attente : rouvre tous les messages conservés. Notez que la quantité de messages en attente disponibles est déterminée par la période de conservation des messages et la capacité de stockage du sujet Lite.
- Fin des messages en attente : supprime définitivement les messages en ignorant tous les messages publiés.
- Horodatage de publication : lance la recherche jusqu'au premier message présentant un horodatage de publication (généré par le serveur) ultérieur ou égal à l'horodatage spécifié. Si aucun message de ce type ne peut être localisé, la recherche est lancée jusqu'à la fin des messages en attente. Les messages suivants sont assurés d'avoir un horodatage de publication ultérieur ou égal à l'horodatage spécifié, sauf lorsque les horodatages spécifiés se situent dans le futur.
- Horodatage de l'événement : lance la recherche jusqu'au premier message présentant un horodatage (spécifié par l'utilisateur) ultérieur ou égal à l'horodatage spécifié. Si aucun message de ce type ne peut être localisé, la recherche est lancée jusqu'à la fin des messages en attente. Étant donné que les horodatages des événements sont fournis par l'utilisateur, les messages suivants peuvent présenter des horodatages antérieurs à l'heure de l'événement spécifiée et doivent être filtrés par le client, si nécessaire. Si aucun horodatage d'événement n'est défini pour les messages, leurs horodatages de publication sont utilisés comme solution de remplacement.
Vous pouvez rechercher un abonnement Lite à l'aide de la Google Cloud CLI ou de la l'API Pub/Sub Lite ;
gcloud
Pour rechercher un abonnement Lite, exécutez la commande gcloud pubsub lite-subscriptions seek
:
gcloud pubsub lite-subscriptions seek SUBSCRIPTION_ID \ --location=LITE_LOCATION \ (--publish-time=PUBLISH_TIME | --event-time=EVENT_TIME | \ --starting-offset=STARTING_OFFSET) \ [--async]
Remplacez les éléments suivants :
SUBSCRIPTION_ID : ID de l'abonnement Lite
LITE_LOCATION : emplacement de l'abonnement Lite
PUBLISH_TIME : horodatage de publication à rechercher
EVENT_TIME : horodatage d'événement à rechercher.
STARTING_OFFSET :
beginning
ouend
Pour en savoir plus sur les formats de date et d'heure, consultez la page gcloud topic datetimes
.
Si vous spécifiez l'option --async
et que la requête aboutit, la commande
affiche l'ID de l'opération de recherche:
Check operation [projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID] for status.
Exécutez la commande gcloud pubsub lite-operations describe
pour obtenir l'ID de l'opération.
REST
Pour rechercher un abonnement Lite, envoyez une requête POST
comme suit :
POST https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID:seek Authorization: Bearer $(gcloud auth print-access-token)
Remplacez les éléments suivants :
REGION: région dans laquelle se trouve l'abonnement Lite
PROJECT_NUMBER: numéro du projet associé à l'abonnement Lite
LITE_LOCATION : emplacement de l'abonnement Lite
SUBSCRIPTION_ID : ID de l'abonnement Lite
Pour rechercher le début ou la fin des messages en attente, définissez les champs suivants dans le corps de la requête :
{ "namedTarget": NAMED_TARGET }
Remplacez les éléments suivants :
- NAMED_TARGET :
TAIL
pour le début ouHEAD
pour la fin des messages en attente.
Pour rechercher un horodatage de publication, définissez les champs suivants dans le corps de la requête :
{ "timeTarget": { "publishTime": TIMESTAMP } }
Spécifiez "eventTime"
pour rechercher un horodatage d'événement.
Remplacez les éléments suivants :
- TIMESTAMP : horodatage au format RFC 3339 UTC, avec une précision de l'ordre de la nanoseconde et jusqu'à neuf chiffres décimaux. Exemples :
"2014-10-02T15:01:23Z"
et"2014-10-02T15:01:23.045123456Z"
.
Si la requête aboutit, la réponse est une opération de longue durée au format JSON :
{ "name": projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_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 dans la section Bibliothèques clientes de Pub/Sub Lite.
Python
Avant d'exécuter cet exemple, suivez les instructions de configuration de Python dans la section Bibliothèques clientes de Pub/Sub Lite.
Si la requête de recherche aboutit, la réponse est un ID d'opération de longue durée. Consultez les informations ci-après sur le suivi de la propagation de la recherche si vous devez connaître le moment auquel les abonnés ont réagi à la recherche.
Clients compatibles
Les opérations de recherche nécessitent des abonnés qui utilisent les bibliothèques clientes Pub/Sub Lite suivantes et les versions minimales :
- java-pubsublite : version 0.15.0
- java-pubsublite-kafka : version 0.6.0 Les clients doivent également avoir activé le commit automatique.
- python-pubsublite : version 0.6.0
- google-cloud-go : pubsublite version 0.10.0.
Les opérations de recherche ne fonctionnent pas lorsque Pub/Sub Lite est utilisé avec Apache Beam ou Apache Spark, car ces systèmes effectuent leur propre suivi des décalages au sein des partitions. La solution consiste à drainer, rechercher et redémarrer les workflows.
Le service Pub/Sub Lite est capable de détecter un client abonné qui n'est pas compatible avec les opérations de recherche (par exemple, une ancienne version de bibliothèque cliente ou un framework non compatible) et annule la recherche avec un état d'erreur FAILED_PRECONDITION
.
Suivre la propagation de la recherche
Si un ID d'opération de longue durée est renvoyé pour la requête de recherche initiale, cela signifie que la recherche a bien été enregistrée dans le service Pub/Sub Lite et qu'elle finira par se propager aux abonnés (si le client est compatible, comme ci-dessus). L'opération suit cette propagation et se termine une fois que les abonnés ont réagi à la recherche, pour toutes les partitions.
Si les abonnés sont en ligne, la réception de la notification de recherche peut prendre jusqu'à 30 secondes. Les notifications de recherche sont envoyées indépendamment pour chaque partition. Par conséquent, les partitions peuvent ne pas réagir à la recherche au même moment. Si les abonnés sont hors connexion, l'opération de recherche se termine une fois qu'ils sont en ligne.
Si la propagation d'un appel de recherche précédent auprès des abonnés n'est pas terminée, cet appel est annulé et remplacé par la nouvelle opération de recherche. Les métadonnées de l'opération de recherche expirent au bout de 30 jours, ce qui entraîne l'abandon effectif des opérations de recherche incomplètes.
État de l'opération de recherche
Vous pouvez obtenir l'état d'une opération de recherche à l'aide de la Google Cloud CLI ou de l'API Pub/Sub Lite.
gcloud
Pour obtenir des détails sur une opération Lite, utilisez la commande gcloud pubsub lite-operations describe
:
gcloud pubsub lite-operations describe OPERATION_ID \ --location=LITE_LOCATION
Remplacez les éléments suivants :
OPERATION_ID : ID de l'opération Lite
LITE_LOCATION: emplacement de l'opération Lite
Si la requête aboutit, la ligne de commande affiche des métadonnées sur l'opération Lite :
metadata: '@type': type.googleapis.com/google.cloud.pubsublite.v1.OperationMetadata createTime: '2021-01-02T03:04:05Z' target: projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID verb: seek name: projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID
REST
Pour obtenir des détails sur une opération Lite, envoyez une requête GET
comme suit :
GET https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID Authorization: Bearer $(gcloud auth print-access-token)
Remplacez les éléments suivants :
REGION: région dans laquelle se trouve l'opération Lite
PROJECT_NUMBER : numéro du projet contenant l'opération Lite
LITE_LOCATION: emplacement de l'opération Lite
OPERATION_ID : ID de l'opération Lite
Si la requête aboutit, la réponse est une opération de longue durée au format JSON :
{ "name": projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID, ... }
Lister les opérations de recherche
Vous pouvez répertorier les opérations de recherche terminées et actives à l'aide de la Google Cloud CLI. l'API Pub/Sub Lite.
gcloud
Pour répertorier les opérations Lite d'un projet, exécutez la commande gcloud pubsub lite-operations list
:
gcloud pubsub lite-operations list \
--location=LITE_LOCATION \
[--subscription=SUBSCRIPTION] \
[--done=DONE] \
[--limit=LIMIT]
Remplacez les éléments suivants :
LITE_LOCATION: emplacement dans lequel se trouvent les opérations Lite
SUBSCRIPTION : filtrer les opérations par abonnement Lite
DONE :
true
pour n'inclure que les opérations complètes etfalse
pour n'inclure que les opérations actives.LIMIT : entier permettant de limiter le nombre d'opérations renvoyées.
Si la requête aboutit, la ligne de commande affiche un résumé des opérations Lite :
OPERATION_ID TARGET CREATE_TIME DONE ERROR_CODE MESSAGE operation2 projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID 2021-05-06T07:08:00Z True operation1 projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID 2021-01-02T03:04:00Z True
REST
Pour répertorier les opérations Lite dans un projet, envoyez une requête GET
comme suit :
GET https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations Authorization: Bearer $(gcloud auth print-access-token)
Remplacez les éléments suivants :
REGION: région dans laquelle se trouvent les opérations Lite
PROJECT_NUMBER : numéro du projet contenant les opérations Lite
LITE_LOCATION: emplacement dans lequel se trouvent les opérations Lite
Si la requête aboutit, la réponse est une liste d'opérations Lite au format JSON :
{ "operations": [ { "name": "projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID", ... }, { "name": "projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID", ... } ] }