En esta página, se explica cómo recibir y confirmar mensajes mediante la semántica del tipo “exactamente una vez”. Solo el tipo de suscripción de extracción admite la entrega del tipo “exactamente una vez”, incluidos los suscriptores que usan la API de StreamingPull.
Las suscripciones de envío y exportación no admiten la entrega del tipo “exactamente una vez”.
Versiones recomendadas de la biblioteca cliente
- Para obtener el mejor rendimiento, usa la versión más reciente de la biblioteca cliente, Python v2.13.6 o una versión posterior, Java v1.120.11 o posterior, PHP v1.39.0 o superior, C# v3.2.0 o superior, C++ v2.1.0, Go v1.0.0 o posterior
Entrega “exactamente una vez”
Pub/Sub admite la entrega de tipo “exactamente una vez”, dentro de una región de la nube, según un ID de mensaje único definido por Pub/Sub.
Cuando se habilita la función, Pub/Sub proporciona lo siguiente:
No se vuelve a enviar el mensaje después de que se confirma correctamente la recepción del mensaje.
No se vuelve a enviar un mensaje mientras está pendiente. Se considera que un mensaje está pendiente hasta que vence el plazo de confirmación de recepción o se confirma el mensaje.
En el caso de varias entregas válidas, debido al vencimiento del plazo de confirmación o a una confirmación negativa iniciada por el cliente, solo se puede usar el ID de confirmación más reciente para confirmar el mensaje. Todas las solicitudes con un ID de confirmación anterior fallan.
Comparación entre reintentos y duplicados
Es importante comprender la diferencia entre los reintentos de entregas esperados y los inesperados.
Un reintento de entrega puede ocurrir debido a una confirmación negativa de un mensaje iniciada por el cliente o cuando este no extiende el plazo de confirmación de recepción del mensaje antes de que venza el plazo de confirmación. Los reintentos se consideran válidos y el sistema funciona según lo previsto.
Para solucionar problemas de reintentos de entregas, consulta Trabaja con duplicados y fuerza reintentos.
Un duplicado se produce cuando un mensaje se vuelve a enviar después de una confirmación exitosa o antes del vencimiento del plazo de confirmación.
Un mensaje que se vuelve a entregar conserva el mismo ID de mensaje entre los intentos de volver a entregarlos.
Las suscripciones con la entrega “exactamente una vez” habilitada no reciben entregas duplicadas.
Asistencia de entrega “exactamente una vez” en bibliotecas cliente
Las bibliotecas cliente compatibles tienen una interfaz para la confirmación de recepción con respuesta (por ejemplo: Go). Puedes usar esta interfaz para verificar si la solicitud de confirmación se realizó correctamente. Si la solicitud de confirmación se realiza correctamente, se garantiza que los clientes no recibirán una nueva entrega. Si la solicitud de confirmación falla, los clientes pueden esperar una nueva entrega.
Los clientes también pueden usar las bibliotecas cliente compatibles sin la interfaz de confirmación. Sin embargo, en esos casos, las fallas de confirmación de recepción pueden generar una nueva entrega silenciosa de los mensajes.
Las bibliotecas cliente compatibles tienen interfaces para configurar el tiempo mínimo de asignación de tiempo de extensión (por ejemplo: Go). Debes establecer el valor de la extensión de asignación mínima en un número alto para evitar que se venzan las confirmaciones de recepción relacionadas con la red. El valor máximo se establece en 600 segundos.
Los valores y el rango predeterminados de las variables relacionadas con la entrega “exactamente una vez” y los nombres de las variables pueden diferir entre las bibliotecas cliente. Por ejemplo, en la biblioteca cliente de Java, las siguientes variables controlan la entrega "exactamente una vez".
Variable | Descripción | Valor |
---|---|---|
setEnableExactlyOnceDelivery |
Habilita o inhabilita la entrega del tipo “exactamente una vez”. | verdadero o falso Predeterminada=false |
minDurationPerAckExtension |
El tiempo mínimo en segundos que se usa para extender el plazo de confirmación de la modificación. | Rango=0 a 600 Predeterminado=ninguno |
maxDurationPerAckExtension |
El tiempo máximo en segundos que se usa para extender el plazo de confirmación de la modificación. | Rango=0 a 600 Predeterminado=ninguno |
En el caso de una entrega “exactamente una vez”, la solicitud modifyAckDeadline
o acknowledgment
a Pub/Sub falla cuando el ID de confirmación ya venció. En esos casos, el servicio considera que el ID de confirmación vencido no es válido, ya que es posible que una entrega más reciente ya esté en tránsito. Esto se diseñó para la entrega “exactamente una vez”. Luego, verás que las solicitudes acknowledgment
y ModifyAckDeadline
muestran una respuesta INVALID_ARGUMENT
. Cuando se inhabilita la entrega “exactamente una vez”, estas solicitudes muestran OK
en casos de IDs de confirmación vencidos.
Para asegurarte de que las solicitudes acknowledgment
y ModifyAckDeadline
tengan IDs de confirmación válidos, considera establecer un valor de minDurationPerAckExtension
en un número alto.
Crea suscripciones con entrega “exactamente una vez”
Puedes crear una suscripción con entrega “exactamente una vez” mediante la consola de Google Cloud, Google Cloud CLI, la biblioteca cliente o la API de Pub/Sub.
Suscripción de extracción
Console
Para crear una suscripción de extracción con entrega “exactamente una vez”, sigue estos pasos:
En la consola de Google Cloud, ve a la página Suscripciones.
Haz clic en Crear suscripción.
Ingresa el ID de suscripción.
Elige o crea un tema desde el menú desplegable.
La suscripción recibe mensajes del tema.
En la sección Publicación exacta una vez, selecciona Habilitar la entrega exactamente una vez.
Haz clic en Crear.
gcloud
Para crear una suscripción de extracción con entrega del tipo “exactamente una vez”, usa el comando gcloud pubsub subscriptions create
con la marca --enable-exactly-once-delivery
:
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --enable-exactly-once-delivery
Reemplaza lo siguiente:
- SUBSCRIPTION_ID: Es el ID de la suscripción que se creará.
- TOPIC_ID: Es el ID del tema para adjuntar a la suscripción.
REST
Para crear una suscripción con entrega “exactamente una vez”, usa el método projects.subscriptions.create
.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID Authorization: Bearer $(gcloud auth print-access-token)
Reemplaza lo siguiente:
- PROJECT_ID: Es el ID del proyecto para crear la suscripción.
- SUBSCRIPTION_ID: Es el ID de la suscripción que se creará.
Para crear una suscripción de extracción con entrega del tipo “exactamente una vez”, especifica lo siguiente en el cuerpo de la solicitud:
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "enableExactlyOnceDelivery": true, }
Reemplaza lo siguiente:
- PROJECT_ID: el ID del proyecto con el tema
- TOPIC_ID: Es el ID del tema para adjuntar a la suscripción.
C++
Antes de probar esta muestra, sigue las instrucciones de configuración de C++ en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para C++.
C#
Antes de probar esta muestra, sigue las instrucciones de configuración de C# en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para C#.
Go
Antes de probar esta muestra, sigue las instrucciones de configuración de Go en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Go.
Java
Antes de probar esta muestra, sigue las instrucciones de configuración de Java en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Java.
Python
Antes de probar esta muestra, sigue las instrucciones de configuración de Python en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Python.
Node.js
Antes de probar esta muestra, sigue las instrucciones de configuración de Node.js en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Node.js.
Node.js
Antes de probar esta muestra, sigue las instrucciones de configuración de Node.js en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Node.js.
Rita
Antes de probar esta muestra, sigue las instrucciones de configuración de Ruby en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Ruby.
PHP
Antes de probar esta muestra, sigue las instrucciones de configuración de PHP en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para PHP.
Suscríbete con la entrega de mensajes del tipo “exactamente una vez”
A continuación, se incluyen algunos ejemplos de código para suscribirse con la entrega “exactamente una vez” mediante la biblioteca cliente.
Suscripción de extracción
Go
Antes de probar esta muestra, sigue las instrucciones de configuración de Go que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub Go.
Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Antes de probar esta muestra, sigue las instrucciones de configuración de Java que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub Java.
Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Antes de probar esta muestra, sigue las instrucciones de configuración de Node.js que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub Node.js.
Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
PHP
Antes de probar esta muestra, sigue las instrucciones de configuración de PHP que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub PHP.
Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Antes de probar esta muestra, sigue las instrucciones de configuración de Python que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub Python.
Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Ruby
Antes de probar esta muestra, sigue las instrucciones de configuración de Ruby que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub Ruby.
Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
C++
Antes de probar esta muestra, sigue las instrucciones de configuración de C++ que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub C++.
Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
C#
Antes de probar esta muestra, sigue las instrucciones de configuración de C# que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub C#.
Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js (TypeScript)
Antes de probar esta muestra, sigue las instrucciones de configuración de Node.js que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Node.js.
Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Supervisa suscripciones de entrega “exactamente una vez”
La métrica subscription/exactly_once_warning_count
registra la cantidad de eventos que pueden generar posibles reintentos (válidos o duplicados). Esta métrica cuenta las veces que Pub/Sub no puede procesar las solicitudes asociadas con los IDs de confirmación (solicitud ModifyAckDeadline
o acknowledgment
). Los motivos del error pueden ser el servidor o el cliente. Por ejemplo, si la capa de persistencia que se usa para mantener la información de entrega del tipo “exactamente una vez” no está disponible, sería un evento basado en el servidor. Si el cliente intenta confirmar un mensaje con un ID de confirmación no válido, sería un evento basado en el cliente.
Información sobre la métrica
subscription/exactly_once_warning_count
captura eventos que podrían o no generar entregas reales y que pueden ser ruidosos según el comportamiento del cliente. Por ejemplo: las solicitudes acknowledgment
o ModifyAckDeadline
repetidas con IDs de confirmación no válidos aumentan la métrica de forma repetida.
Las siguientes métricas también son útiles para comprender el comportamiento del cliente:
La métrica
subscription/expired_ack_deadlines_count
muestra la cantidad de vencimientos de los IDs de confirmación. Los vencimientos de los IDs de confirmación pueden generar fallas en las solicitudesModifyAckDeadline
yacknowledgment
.La métrica
service.serviceruntime.googleapis.com/api/request_count
se puede usar para capturar fallas de solicitudesModifyAckDeadline
oacknowledgment
en casos en los que las solicitudes lleguen a Google Cloud, pero no a Pub/Sub. Hay fallas que esta métrica no capturará, por ejemplo, cuando los clientes se desconectan de Google Cloud.
En la mayoría de los casos de eventos de falla que se pueden reintentar, las bibliotecas cliente compatibles reintentan la solicitud automáticamente.
Cuotas
Las suscripciones de entrega de tipo “exactamente una vez” están sujetas a requisitos de cuota adicionales. La cuota se aplica a las siguientes ubicaciones:
- Cantidad de mensajes consumidos desde suscripciones con entrega “exactamente una vez” habilitada por región.
- Cantidad de mensajes confirmados o cuya fecha límite se extiende cuando se usan suscripciones con la entrega “exactamente una vez” habilitada por región.
Para obtener más información sobre estas cuotas, consulta la tabla del tema Cuotas.
Entrega “exactamente una vez” y pedidos de suscripciones
Pub/Sub admite entregas del tipo “exactamente una vez” con la entrega ordenada.
Cuando se usa la función de pedidos con entrega “exactamente una vez”, Pub/Sub espera que las confirmaciones estén en orden. Si las confirmaciones están desordenadas, el servicio falla en las solicitudes y se generan errores temporales. Si la fecha límite de confirmación de la entrega vence antes de una confirmación de entrega en orden, el cliente recibirá una nueva entrega del mensaje. Debido a esto, cuando usas la ordenación con entrega “exactamente una vez”, la capacidad de procesamiento del cliente se limita a un orden de miles de mensajes por segundo.
Entregas del tipo “exactamente una vez” y suscripciones de envío
Pub/Sub admite la entrega “exactamente una vez” solo con suscripciones de extracción.
Los clientes que consumen mensajes de las suscripciones de envío confirman los mensajes respondiendo a las solicitudes de envío con una respuesta correcta. Sin embargo, los clientes no saben si la suscripción a Pub/Sub recibió la respuesta y la procesó. Esto es diferente de las suscripciones de extracción, en las que los clientes inician las solicitudes de confirmación de recepción y la suscripción a Pub/Sub responde si la solicitud se procesó correctamente. Por este motivo, la semántica de entrega de tipo “exactamente una vez” no se alinea bien con las suscripciones de envío.
Qué debes saber
Si no se especifica la fecha límite de confirmación en el momento de CreateSubscription, las suscripciones que tengan habilitada la entrega del tipo “exactamente una vez” tendrán un plazo de confirmación predeterminado de 60 segundos.
Los plazos predeterminados de confirmación de recepción más largos son beneficiosos para evitar el reintento de entregas causados por eventos de red. Las bibliotecas cliente compatibles no usan el plazo predeterminado de confirmación de la suscripción.
Las suscripciones de entrega “exactamente una vez” tienen una latencia de publicación para suscribirse significativamente más alta en comparación con las suscripciones normales.
Si necesitas una capacidad de procesamiento alta, tus clientes de entrega del tipo “exactamente una vez” también deben usar la extracción de transmisión.
Una suscripción puede recibir varias copias del mismo mensaje debido a la publicación de duplicados, incluso con la entrega “exactamente una vez” habilitada. Los duplicados del lado de la publicación pueden deberse a varios reintentos de publicación únicos por parte del cliente de publicación o el servicio de Pub/Sub. Varias publicaciones únicas del cliente de publicación entre reintentos generan reintentos con diferentes IDs de mensajes. Varias publicaciones únicas por parte del servicio de Pub/Sub, para responder a una solicitud de publicación de un cliente, generan nuevos envíos con los mismos IDs de mensaje.
Puedes reintentar las fallas en
subscription/exactly_once_warning_count
, y las bibliotecas cliente compatibles lo hacen automáticamente. Sin embargo, no se pueden reintentar las fallas relacionadas con los IDs de confirmación no válidos.