En esta página, se explica cómo recibir y confirmar mensajes con el método “exactamente una vez” semántica. Solo el tipo de suscripción de extracción admite la entrega de tipo "exactamente una vez", incluidos los suscriptores que usan la API de StreamingPull.
Envía y exporta suscripciones no admiten la entrega “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 posterior, Java v1.120.11 o una posterior, PHP v1.39.0 o una posterior, C# v3.2.0 o una posterior, C++ v2.1.0, Go v1.25.1 o una posterior, Node v3.2.0 o una posterior y Ruby v2.12.1 o una posterior.
Entrega “exactamente una vez”
Pub/Sub admite entregas “exactamente una vez” dentro de una región de la nube, basada en Pub/Sub única ID de mensaje.
Cuando la función está habilitada, Pub/Sub proporciona lo siguiente:
No se vuelve a entregar el mensaje una vez que se confirma correctamente el mensaje.
No se realiza ninguna reinstalación mientras un mensaje esté pendiente. Un mensaje se considera pendiente hasta que venza el plazo de confirmación o hasta que el mensaje se confirmar.
En caso de varias entregas válidas, debido al plazo de confirmación el vencimiento o el reconocimiento negativo iniciado por el cliente, solo la última se puede usar el ID de confirmación de recepción del mensaje. Todas las solicitudes con falla un ID de confirmación anterior.
Republicación en comparación con duplicado
Es importante entender la diferencia entre lo esperado e inesperado entregas nuevas.
Un reintento de la publicación puede producirse debido a respuestas negativas iniciadas por el cliente la confirmación de un mensaje o cuando el cliente no extiende la confirmación la fecha límite del mensaje antes de que caduque el plazo de confirmación. Reintentos de entrega se consideran válidas y el sistema funciona según lo previsto.
Para solucionar problemas relacionados con las nuevas publicaciones, consulta Cómo administrar duplicados.
Un duplicado ocurre cuando un mensaje se vuelve a enviar después de una confirmación correcta. o antes de que venza el plazo de confirmación.
Un mensaje que se vuelve a entregar conserva el mismo ID de mensaje entre los intentos de reintento de entrega.
Las suscripciones que tienen habilitada la opción de entrega exactamente una vez no reciben datos duplicados entregas.
Asistencia para la entrega “exactamente una vez” en bibliotecas cliente
Las bibliotecas cliente compatibles tienen una interfaz para la confirmación con respuesta (ejemplo: Go). Puedes usar esta interfaz para comprobar si la solicitud de confirmación se realizó correctamente. Si la solicitud de acuse de recibo se realiza correctamente, se garantiza que los clientes no recibirán una nueva entrega. Si la solicitud de acuse de recibo falla, los clientes pueden esperar una nueva entrega.
Los clientes también pueden usar las bibliotecas cliente compatibles sin el de confirmación de recepción. Sin embargo, en esos casos, Las fallas de confirmación de recepción pueden provocar que los mensajes se vuelvan a entregar en silencio.
Las bibliotecas cliente admitidas tienen interfaces para establecer el tiempo mínimo de extensión del arrendamiento (por ejemplo, Go). Debes establecer un número alto para la extensión de retención mínima. para evitar que caduquen los reconocimientos relacionados con la red. El valor máximo está configurado en 600 segundos.
Los valores y el rango predeterminados para las variables relacionadas con la entrega “exactamente una vez” y los nombres de las variables pueden diferir entre las bibliotecas cliente. Para Por ejemplo, en la biblioteca cliente de Java, las siguientes variables controlan entrega “exactamente una vez”.
Variable | Descripción | Valor |
---|---|---|
setEnableExactlyOnceDelivery |
Habilita o inhabilita la entrega “exactamente una vez”. | verdadero o falso Predeterminado=false |
minDurationPerAckExtension |
El tiempo mínimo en segundos que se debe usar para extender el plazo límite de confirmación de la modificación. | Rango: De 0 a 600. Valor predeterminado: Ninguno |
maxDurationPerAckExtension |
Es el tiempo máximo en segundos que se usará para extender el plazo de confirmación de la modificación. | Rango=0 a 600 Predeterminado=ninguno |
En el caso de la entrega exactamente una vez, se agrega modifyAckDeadline
o acknowledgment
.
la solicitud a Pub/Sub falla cuando el ID de confirmación ya venció. De tal forma
el servicio considera que el ID de confirmación vencido no es válido, ya que un
o una entrega más reciente
podrían estar en tránsito. Se diseñó para exactamente una vez
la entrega de software. Luego, verás que las solicitudes acknowledgment
y ModifyAckDeadline
muestran un
Respuesta de INVALID_ARGUMENT
. Cuando se inhabilita la entrega “exactamente una vez”, estas
Las solicitudes muestran OK
en los casos de IDs de confirmación vencidos.
Para garantizar que las solicitudes de acknowledgment
y ModifyAckDeadline
tengan IDs de acuse de recibo válidos, considera establecer el valor de minDurationPerAckExtension
en un número alto.
Consideraciones regionales
La garantía de entrega exactamente una vez solo se aplica cuando los suscriptores se conectan al en la misma región. Si tu aplicación suscriptora está distribuida en en múltiples regiones, puede dar lugar a una entrega de mensajes duplicada, incluso cuando está habilitada la entrega “exactamente una vez”. Los publicadores pueden enviar mensajes a cualquier región exactamente cuando se mantiene la garantía.
Cuando ejecutas tu aplicación en Google Cloud, esta se conecta de forma predeterminada al extremo de Pub/Sub en la misma región. Por lo tanto, en general, ejecutar tu aplicación en una sola región de Google Cloud garantiza que estés interactuando con una sola región.
Cuando ejecutas tu aplicación de suscriptor fuera de Google Cloud o en varias regiones, puedes asegurarte de conectarte a una sola región con un extremo de ubicación cuando configures Pub/Sub cliente. Todos los extremos de ubicación para el punto de Pub/Sub a una sola ubicación regiones. Para obtener más información sobre los extremos de ubicación, consulta Extremos de Pub/Sub. Si quieres obtener una lista de todos los extremos de ubicación de Pub/Sub, consulta Lista de extremos de ubicación.
Crea suscripciones con la 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 Entrega exactamente 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 elemento
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 la
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 este 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.
Ruby
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 exactamente una vez
Las siguientes son algunas muestras de código para suscribirte con la entrega del tipo “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 el Guía de inicio rápido de Pub/Sub con bibliotecas cliente. Para obtener más información, consulta la API de Go de Pub/Sub documentación de referencia.
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 el Guía de inicio rápido de Pub/Sub con bibliotecas cliente. Para obtener más información, consulta la API de Java de Pub/Sub documentación de referencia.
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 el Guía de inicio rápido de Pub/Sub con bibliotecas cliente. Para obtener más información, consulta la API de Node.js de Pub/Sub documentación de referencia.
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 el 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 PHP de Pub/Sub.
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 el Guía de inicio rápido de Pub/Sub con bibliotecas cliente. Para obtener más información, consulta la API de Python de Pub/Sub documentación de referencia.
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 encontrarás en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Para obtener más información, consulta la API de Ruby de Pub/Sub documentación de referencia.
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 el Guía de inicio rápido de Pub/Sub con bibliotecas cliente. Para obtener más información, consulta la API de C++ de Pub/Sub documentación de referencia.
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 el Guía de inicio rápido de Pub/Sub con bibliotecas cliente. Para obtener más información, consulta la API de C# de Pub/Sub documentación de referencia.
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 este ejemplo, sigue las instrucciones de configuración de Node.js que se encuentran en el Guía de inicio rápido de Pub/Sub con bibliotecas cliente. Para obtener más información, consulta la API de Pub/Sub para Node.js documentación de referencia.
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 las suscripciones de entrega “exactamente una vez”
El
subscription/exactly_once_warning_count
registra la cantidad de eventos que
puede dar lugar a posibles reintentos de entregas (válidas o duplicadas). Esta métrica cuenta la
veces Pub/Sub no puede procesar las solicitudes asociadas con
IDs de confirmación de recepción (solicitud ModifyAckDeadline
o acknowledgment
). Los motivos
de la falla podría estar basada en el servidor o en el cliente. Por ejemplo, si la persistencia
para mantener la información de entrega
“exactamente una vez” no está disponible,
sería un evento basado en el servidor. Si el cliente intenta confirmar la recepción de un mensaje con
un ID de confirmación no válido, sería un evento basado en el cliente.
Comprende la métrica
subscription/exactly_once_warning_count
captura eventos que podrían o no tener.
pueden generar nuevas entregas y pueden ser ruidosos
según el comportamiento del cliente. Para
ejemplo: solicitudes repetidas acknowledgment
o ModifyAckDeadline
con no válidas
los IDs de confirmación aumentan la métrica repetidamente.
Las siguientes métricas también son útiles para comprender el comportamiento del cliente:
subscription/expired_ack_deadlines_count
muestra la cantidad de vencimientos del ID de confirmación. Confirmación Los vencimientos de los IDs pueden provocar fallas paraModifyAckDeadline
y Solicitudesacknowledgment
.service.serviceruntime.googleapis.com/api/request_count
La métrica se puede usar para capturar fallas deModifyAckDeadline
oacknowledgment
. en los casos en que las solicitudes llegan a Google Cloud, pero no llegar a Pub/Sub. Hay fallas en las que esta métrica captura, 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 reintentar la solicitud automáticamente.
Cuotas
Las suscripciones de entrega “exactamente una vez” están sujetas a una cuota adicional y los requisitos de cumplimiento. Estas cuotas se aplican en los siguientes casos:
- Cantidad de mensajes consumidos de suscripciones con entrega exactamente una vez habilitado por región.
- Cantidad de mensajes confirmados o cuyo plazo se extiende al usar suscripciones con la entrega “exactamente una vez” habilitada por región.
Para obtener más información sobre estas cuotas, consulta la tabla en la Cuotas.
Entrega “exactamente una vez” y suscripciones ordenadas
Pub/Sub admite la entrega exactamente una vez con la entrega ordenada.
Cuando se usan pedidos con entrega “exactamente una vez”, Pub/Sub espera los reconocimientos estén en orden. Si los acuses de recibo están fuera de orden, el servicio falla las solicitudes con errores temporales. Si el plazo de confirmación vence antes de que se reciba una confirmación en orden para la entrega, el cliente recibirá una reimpresión del mensaje. Debido a esto, cuando usas el ordenamiento con entrega de exactamente una vez, la capacidad de procesamiento del cliente se limita a un orden de mil mensajes por segundo.
Entregas y suscripciones de envío “exactamente una vez”
Pub/Sub admite entregas del tipo “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 exitosa. Sin embargo, los clientes no sabes si la suscripción a Pub/Sub recibió la respuesta y procesarlo. Esto es diferente de las suscripciones de extracción, en las que la confirmación los clientes y la suscripción a Pub/Sub responde si la solicitud se procesó correctamente. Por este motivo, la semántica de entrega de exactamente una vez no se alinea bien con las suscripciones push.
Qué debes saber
Si no se especifica la fecha límite de confirmación en el momento de CreateSubscription, Las suscripciones habilitadas para la entrega “exactamente una vez” tendrán una confirmación de recepción predeterminada plazo de 60 segundos.
Los plazos de acuse de recibo predeterminados más largos son beneficiosos para evitar la reenvío causado por eventos de red. Las bibliotecas cliente compatibles no usan fecha límite predeterminada de confirmación de la suscripción.
Las suscripciones de entrega “exactamente una vez” son significativamente más altas latencia de publicación y suscripción en comparación con las suscripciones normales.
Si necesitas una capacidad de procesamiento alta, tus clientes de entrega exactamente una vez también deben usar la extracción de transmisión.
Es posible que una suscripción reciba varias copias del mismo mensaje debido a duplicados del lado de la publicación, incluso con la entrega de exactamente una vez habilitada. Los duplicados orientados a la publicación pueden deberse a varios reintentos de publicación únicos por parte del publicación de contenido o el servicio de Pub/Sub. Si el cliente publica varias publicaciones únicas, en los reintentos, se producen reintentos en las entregas con IDs de mensaje diferentes. Cuando el servicio de Pub/Sub realiza varias publicaciones únicas, para responder a una solicitud de publicación de un cliente, se vuelven a enviar los mensajes con los mismos IDs de mensaje.
Puedes reintentar los errores en
subscription/exactly_once_warning_count
y las bibliotecas cliente compatibles los reintentan automáticamente. Sin embargo, las fallas relacionadas con IDs de confirmación no válidos no pueden se debe reintentar.