Después de confirmar los mensajes en Pub/Sub, el cliente suscriptor no puede acceder a ellos. Además, los clientes suscriptores deben procesar todos los mensajes de una suscripción, incluso si solo se necesita un subconjunto.
La función buscar amplía las capacidades de los suscriptores, ya que te permite modificar el estado de confirmación de los mensajes de forma masiva. Por ejemplo, puedes reproducir mensajes ya confirmados o borrar definitivamente mensajes de forma masiva. Además, puedes copiar el estado de confirmación de una suscripción en otra si usas la función de búsqueda en combinación con una instantánea.
Para obtener una demostración rápida de cómo funcionan estas características, consulta Repite un mensaje en Pub/Sub buscando una instantánea o una marca de tiempo.
Descripción general de instantáneas y búsquedas
Una instantánea de Pub/Sub es una vista de un momento determinado duradera, coherente y confiable del estado de confirmación (confirmación) del mensaje de una suscripción. Una instantánea registra el estado de confirmación de todos los mensajes dentro de una suscripción en el momento en que se crea. Una instantánea conserva los mensajes no confirmados de la suscripción de origen en el momento de la creación de la instantánea y cualquier mensaje publicado en el tema después de su creación.
La vida útil de una instantánea se determina según el trabajo pendiente existente de la suscripción de origen. El ciclo de vida es igual a 7 días menos la antigüedad del mensaje no confirmado más antiguo de la suscripción. Por ejemplo, imagina una instantánea de una suscripción con una lista de tareas pendientes en la que el mensaje sin confirmar más antiguo tiene 1 día de antigüedad. La instantánea vence después de 6 días. Este cronograma es necesario para que las instantáneas ofrezcan una garantía sólida de entrega al menos una vez.
La duración máxima posible de una instantánea es de siete días. No puedes crear una instantánea que venza en menos de 1 hora después de su creación.
La función de búsqueda te permite buscar una instantánea o una marca de tiempo específica para una suscripción. Esta función te permite controlar la forma en que Pub/Sub puede entregar mensajes desde un momento específico o desde una instantánea específica.
Para buscar una hora anterior y volver a reproducir mensajes ya confirmados, primero debes configurar la retención de mensajes en el tema o configurar la suscripción para que retenga los mensajes confirmados.
Coherencia eventual de las operaciones de búsqueda
Las operaciones de búsqueda son estrictamente coherentes con respecto a la garantía de entrega de mensajes. Esto significa que cualquier mensaje que no se confirme en función de la condición de búsqueda se entregará, finalmente, después de que la operación de búsqueda se realice correctamente. Sin embargo, los mensajes enviados no son coherentes de inmediato con la operación de búsqueda. Por lo tanto, un mensaje que se publicó antes de la marca de tiempo de búsqueda o que se confirmó en una instantánea podría entregarse después de la operación de búsqueda. En cierto modo, la entrega de mensajes funciona como un sistema de coherencia eventual con respecto a la operación de búsqueda. La operación puede tardar hasta un minuto en aplicarse.
Casos de uso para operaciones de búsqueda
- Actualiza el código de suscriptor de forma segura. Un problema con la implementación de un nuevo código de suscriptor es que el ejecutable nuevo puede confirmar mensajes de forma errónea, lo que puede provocar la pérdida de mensajes. La incorporación de instantáneas en el proceso de implementación te permite recuperarte antes errores en el nuevo código de suscriptor.
- Recupérate ante problemas inesperados de suscriptores. En los casos en los que los problemas del suscriptor no estén asociados con un evento de implementación específico, es posible que no tengas una instantánea relevante. En ese caso, si habilitaste la retención de mensajes confirmados para una suscripción, la búsqueda de un horario anterior te brinda una forma de recuperarte ante el error.
- Reduce los costos y el tiempo de procesamiento. Realiza una confirmación masiva de una gran cantidad de mensajes pendientes que ya no son relevantes.
- Prueba el código del suscriptor en datos conocidos. Cuando se prueba el rendimiento y la coherencia del código del suscriptor, es útil usar los mismos datos en cada ejecución. Las instantáneas son compatibles con datos coherentes con una semántica sólida. Además, las instantáneas se pueden aplicar a cualquier suscripción a un tema determinado, incluso una nueva.
Configura la retención de mensajes
Puedes configurar la retención de mensajes en un tema y configurar cualquiera de sus suscripciones para retener los mensajes confirmados. Te recomendamos configurar la retención de mensajes por tema si deseas que los mensajes se retengan para volver a reproducirlos durante un período mayor que el que se configuró en la suscripción. En este caso, el almacenamiento de mensajes se cobra al proyecto del tema y al proyecto de suscripción según su configuración de retención de mensajes respectiva.
Si no se configura la retención de mensajes por temas, se borra un mensaje no confirmado de la suscripción cuando su antigüedad supera la propiedad message_retention_duration de la suscripción. Por otro lado, si está configurada la retención de mensajes por tema, el mensaje no confirmado se borra de la suscripción solo cuando su antigüedad supera el máximo de los message_retention_duration del tema y de la suscripción.
Configura la retención de mensajes de temas
De forma predeterminada, un tema de Pub/Sub descarta los mensajes en cuanto los reconocen todas las suscripciones adjuntas al tema.
Configurar un tema con retención de mensajes te brinda más flexibilidad, ya que permite que cualquier suscripción adjunta al tema pueda realizar búsquedas en el tiempo y volver a reproducir los mensajes confirmados con anterioridad hasta la message_retention_duration del tema.
La retención de mensajes por tema también permite que una suscripción vuelva a reproducir mensajes que se publican antes de que crearas una suscripción.
Un tema puede retener mensajes publicados durante un máximo de 31 días (configurable por la propiedad message_retention_duration del tema) incluso después de que todas las suscripciones adjuntas los hayan confirmado. En los casos en que la message_retention_duration del tema es mayor que la message_retention_duration de la suscripción, Pub/Sub descarta un mensaje solo cuando su antigüedad supera la message_retention_duration del tema.
Si la retención de mensajes de temas está habilitada, los costos de almacenamiento de los mensajes retenidos por el tema se facturan al proyecto del tema.
Console
Para crear un tema con la retención de mensajes habilitada, sigue estos pasos:
En la consola de Google Cloud, ve a la página Temas de Pub/Sub.
Haga clic en Crear tema.
En el campo ID de tema, ingresa un ID para tu tema.
Habilita Establecer la duración de la retención de mensajes.
Deja las otras opciones de configuración con sus valores predeterminados.
Usa el menú desplegable Duración de la retención de mensajes para seleccionar la cantidad de días, horas y minutos en los que se retendrán los mensajes.
Haz clic en Crear tema para guardar el tema.
Para actualizar la configuración de retención de mensajes de un tema, haz lo siguiente:
Selecciona tu tema en la página de temas de Pub/Sub.
Haz clic en Editar en la parte superior de la página de detalles del tema.
Ajusta el tiempo de retención o habilita o inhabilita la retención de mensajes. Para ello, marca o desmarca la opción Habilitar la retención de mensajes.
Haz clic en Actualizar para guardar los cambios en el tema.
gcloud
Para crear un tema con una duración de retención de mensajes de 7 días, usa el siguiente comando gcloud pubsub topics create:
gcloud pubsub topics create TOPIC_ID --message-retention-duration=7d
Puedes actualizar esta configuración mediante gcloud pubsub topics update. Esto también te permite habilitar la retención de mensajes para un tema existente:
gcloud pubsub topics update TOPIC_ID --message-retention-duration=1d
También puedes inhabilitar la retención de mensajes para un tema con el comando update:
gcloud pubsub topics update TOPIC_ID --clear-message-retention-duration
Configura la retención de mensajes de suscripción
Pub/Sub comienza a retener mensajes en nombre de una suscripción cuando esta se crea. Según la configuración predeterminada, Pub/Sub descarta un mensaje de una suscripción en cuanto se confirma.
Los mensajes no confirmados se retienen durante un valor predeterminado de 7 días (configurable por la propiedad message_retention_duration de la suscripción).
Configurar una suscripción para retener los mensajes confirmados (mediante la propiedad retain_acked_messages) te permite volver a reproducir mensajes confirmados con anterioridad que retenía la suscripción. Puedes configurar los mensajes para que se retengan durante un máximo de 7 días en una suscripción. Esta configuración se aplica a los mensajes confirmados y no confirmados. Sin embargo, se pueden conservar los mensajes en una suscripción por más de 7 días si la duración de retención de mensajes configurada en el tema es superior a 7 días.
Si se configura una suscripción para que retenga los mensajes confirmados, los costos de almacenamiento de los mensajes confirmados que retiene la suscripción se facturan al proyecto de la suscripción.
Console
Para crear una suscripción con la retención de mensajes confirmados habilitada, sigue estos pasos:
En la consola de Google Cloud, ve a la página Suscripciones de Pub/Sub.
Haz clic en Crear suscripción.
En el campo ID de suscripción, ingresa un ID para tu suscripción.
Usa el menú desplegable Duración de retención de mensajes para seleccionar la cantidad de días, horas y minutos en los que se retendrán los mensajes.
Habilita la opción Retener mensajes confirmados. Deja las otras opciones de configuración con sus valores predeterminados.
Haz clic en Crear suscripción para guardar la suscripción.
Para actualizar la configuración de la retención de mensajes de una suscripción, haz lo siguiente:
Selecciona tu suscripción en la página Suscripciones de Pub/Sub.
Haz clic en Editar en la parte superior de la página de detalles de la suscripción.
Puedes ajustar la duración de la retención de mensajes o habilitar o inhabilitar la retención de mensajes confirmados. Para ello, marca o desmarca el campo con la etiqueta Retener mensajes confirmados.
Haz clic en Actualizar para guardar los cambios en la suscripción.
gcloud
Para crear una suscripción con la retención de mensajes confirmados habilitada, usa el siguiente comando gcloud pubsub subscriptions create:
gcloud pubsub subscriptions create SUBSCRIPTION_ID
--retain-acked-messages
--message-retention-duration=5d
Puedes actualizar esta configuración mediante gcloud pubsub subscriptions update. Esto también te permite habilitar la retención de mensajes confirmados para una suscripción existente:
gcloud pubsub subscriptions update SUBSCRIPTION_ID --message-retention-duration=1d
También puedes inhabilitar la retención de mensajes confirmados para una suscripción con el comando update:
gcloud pubsub subscriptions update SUBSCRIPTION_ID --no-retain-acked-messages
Crea una instantánea
Puedes crear una instantánea con la consola, las APIs de Google o la CLI de Google Cloud CLI.
Console
Para crear una instantánea, sigue estos pasos:
En la consola de Google Cloud, ve a la página Instantáneas.
Haz clic en Crear instantánea.
En Selecciona una suscripción a Pub/Sub, elige una suscripción.
En ID de instantánea (Snapshot ID), ingresa un nombre para la instantánea.
Si quieres obtener más información para asignar nombres a los recursos de Pub/Sub, consulta los Lineamientos para asignar nombres a un tema, una suscripción, un esquema o una instantánea.
Haz clic en Crear para crear la instantánea.
También puedes crear un resumen desde la página Suscripciones.
gcloud
Para crear una instantánea, usa el siguiente comando gcloud pubsub snapshots create:
gcloud pubsub snapshots create \
--project=PROJECT_ID \
--subscription=SUBSCRIPTION_ID \
SNAPSHOT_ID
Reemplaza lo siguiente:
PROJECT_ID. Especifica el ID del proyecto.SUBSCRIPTION_ID. Especifica el ID de la suscripción.SNAPSHOT_ID. Especifica el ID de la instantánea.
Busca una marca de tiempo
Cuando se busca un horario, se marcan todos los mensajes recibidos por Pub/Sub antes de ese horario como confirmados y todos los mensajes recibidos después como no confirmados.
Puedes realizar los siguientes tipos de operaciones de búsqueda basadas en marcas de tiempo:
Para borrar definitivamente todos los mensajes, puedes buscar una hora en el futuro.
Para volver a reproducir y procesar mensajes confirmados con anterioridad, busca una hora en el pasado.
Los servidores de Pub/Sub generan la hora de publicación del mensaje (consulta publishTime en la referencia de la API). Este enfoque es impreciso debido a los siguientes motivos:
Un posible sesgo del reloj entre los servidores Pub/Sub
El hecho de que Pub/Sub tenga que trabajar con el horario de llegada de la solicitud de publicación en lugar de hacerlo cuando ocurre un evento en el sistema de origen
Puedes buscar una marca de tiempo mediante la consola, las APIs de Google o la CLI de Google Cloud CLI. Antes de buscar una marca de tiempo en una suscripción, asegúrate de que la retención de mensajes esté habilitada en la suscripción.
Console
Para buscar una marca de tiempo, sigue estos pasos:
En la consola de Google Cloud, ve a la página Suscripción.
Haz clic en una suscripción que tenga habilitada la retención de mensajes.
En la página de detalles de la suscripción, haz clic en Volver a reproducir mensajes.
En Buscar, haz clic en A un momento anterior.
Selecciona una fecha y hora adecuadas y, luego, haz clic en Buscar.
gcloud
Para buscar una marca de tiempo, usa el siguiente comando gcloud pubsub subscriptions seek:
gcloud pubsub subscriptions seek SUBSCRIPTION_ID \
--time=TIME \
Reemplaza lo siguiente:
- TIME: La hora en la que deseas realizar la operación de búsqueda.
- SUBSCRIPTION_ID: Es el ID de la suscripción.
Para obtener más información sobre los formatos de hora admitidos, consulta gcloud topic datetimes.
Busca una instantánea
Puedes volver a reproducir los mensajes no confirmados si usas una instantánea para buscar cualquiera de las suscripciones del tema.
A diferencia de la búsqueda de un horario, no necesitas realizar ninguna configuración de suscripción especial para buscar una instantánea. Solo debes crear la instantánea con anticipación. Por ejemplo, puedes crear una instantánea cuando implementes un código nuevo de suscriptor, en caso de que necesites solucionar confirmaciones inesperadas o erróneas.
Si el trabajo pendiente en la suscripción es demasiado antiguo y la instantánea resultante vence en menos de 1 hora, la operación de búsqueda falla.
Puedes buscar una instantánea con la consola, las APIs de Google o la CLI de Google Cloud CLI.
Console
Para buscar una instantánea, sigue estos pasos:
En la consola de Google Cloud, ve a la página Suscripción.
Haz clic en una suscripción.
En la página de detalles de la suscripción, haz clic en Volver a reproducir mensajes.
En Seek, haz clic en To a snapshot.
Selecciona una instantánea adecuada y haz clic en Seek.
gcloud
Para buscar una instantánea, usa el siguiente comando gcloud pubsub subscriptions seek:
gcloud pubsub subscriptions seek SUBSCRIPTION_ID \
--snapshot=SNAPSHOT_ID
Reemplaza lo siguiente:
- SNAPSHOT_ID: El ID de una instantánea El tema de la instantánea debe ser el mismo que el de la suscripción.
- SUBSCRIPTION_ID: Es el ID de la suscripción.
Buscar con filtros
Puedes volver a reproducir mensajes de suscripciones con filtros. Si buscas una marca de tiempo con una suscripción con un filtro, el servicio de Pub/Sub solo vuelve a entregar los mensajes que coincidan con el filtro.
Una instantánea de una suscripción con un filtro contiene los siguientes mensajes:
- Todos los mensajes más nuevos que la instantánea, incluidos los mensajes que no coinciden con el filtro.
- Mensajes no confirmados que son más antiguos que la instantánea.
Si buscas una instantánea mediante una suscripción con un filtro, el servicio de Pub/Sub solo vuelve a entregar los mensajes en la instantánea que coinciden con el filtro de la suscripción que realiza la solicitud de búsqueda.
Para obtener más información sobre los filtros, consulta Filtra mensajes.
Buscar con temas de mensajes no entregados
Si buscas mensajes en una suscripción con un tema de mensajes no entregados, Pub/Sub establece los intentos de entrega como 0. Los mensajes que recibes de estas suscripciones tienen un campo que cuenta la cantidad de intentos de entrega.
Para obtener más información sobre los temas de mensajes no entregados, consulta Reenvío a temas de mensajes no entregados.
Realiza búsquedas con políticas de reintento
Si buscas mensajes en una suscripción con una política de reintento, Pub/Sub restablece el retraso entre lo siguiente:
- El plazo de confirmación de recepción vence o el suscriptor envía una confirmación de recepción negativa.
- Pub/Sub reenvía el mensaje.
Para obtener más información sobre las políticas de reintento, consulta Usa políticas de reintento.
Buscar con la entrega del tipo “exactamente una vez”
Si buscas mensajes en una suscripción con la entrega “exactamente una vez”, Pub/Sub vuelve a enviar los mensajes confirmados con anterioridad que son aptos para la entrega. Fallarán todas las confirmaciones de una entrega realizada antes de la operación de búsqueda. Las operaciones de búsqueda tienen coherencia eventual.
Para obtener más información sobre las políticas de reintentos, consulta La entrega "exactamente una vez".