En este documento, se proporciona una descripción general de una suscripción de extracción, su flujo de trabajo y las propiedades asociadas.
En una suscripción de extracción, un cliente suscriptor solicita mensajes del servidor de Pub/Sub.
El modo pull puede usar una de las dos APIs de servicio: Pull o StreamingPull. Para ejecutar la API elegida, puedes seleccionar una biblioteca cliente de alto nivel proporcionada por Google o una biblioteca cliente de bajo nivel generada automáticamente. También puedes elegir entre el procesamiento de mensajes síncrono y asíncrono.
Antes de comenzar
Antes de leer este documento, asegúrate de estar familiarizado con lo siguiente:
Cómo funciona Pub/Sub y los diferentes términos de Pub/Sub
Los diferentes tipos de suscripciones que admite Pub/Sub y por qué es posible que desees usar una suscripción de extracción.
Flujo de trabajo de la suscripción de extracción
En el caso de una suscripción de extracción, tu cliente suscriptor inicia solicitudes a un servidor de Pub/Sub para recuperar mensajes. El cliente suscriptor usa una de las siguientes APIs:
- API de
Pull
REST - API de
PullRequest
de RPC - API de
StreamingPullRequest
de REST - API de
StreamingPullRequest
de RPC
La mayoría de los clientes suscriptores no realizan estas solicitudes directamente. En cambio, los clientes dependen de la biblioteca cliente de alto nivel proporcionada por Google Cloud que realiza solicitudes de extracción de transmisión de forma interna y entrega mensajes de forma asíncrona. Para un cliente suscriptor que necesita un mayor control sobre cómo se extraen los mensajes, Pub/Sub usa una biblioteca de gRPC de bajo nivel que se genera automáticamente. Esta biblioteca realiza solicitudes de extracción de extracción o de transmisión directamente. Estas solicitudes pueden ser síncronas o asíncronas.
En las siguientes dos imágenes, se muestra el flujo de trabajo entre un cliente suscriptor y una suscripción de extracción.
Flujo de trabajo de extracción
El flujo de trabajo de extracción es el siguiente, que indica la Figura 1:
- El cliente suscriptor llama de manera explícita al método
pull
, que solicita mensajes para su entrega. Esta solicitud es elPullRequest
, como se muestra en la imagen. El servidor de Pub/Sub responde con cero o más mensajes y los IDs de confirmación. Una respuesta con cero mensajes o con un error no necesariamente indica que no hay mensajes disponibles para recibir. Esta respuesta es el
PullResponse
, como se muestra en la imagen.El cliente suscriptor llama de manera explícita al método
acknowledge
. El cliente usa el ID de confirmación de recepción que se muestra para confirmar que el mensaje se procesó y que no es necesario volver a entregarlo.
Para una sola solicitud de extracción de transmisión, un cliente suscriptor puede mostrar varias respuestas debido a la conexión abierta. Por el contrario, solo se muestra una respuesta para cada solicitud de extracción.
Propiedades de una suscripción de extracción
Las propiedades que configuras para una suscripción de extracción determinan cómo se escriben los mensajes en la suscripción. Para obtener más información, consulta las propiedades de suscripción.
APIs del servicio de Pub/Sub
La suscripción de extracción de Pub/Sub puede usar una de las siguientes dos APIs para recuperar mensajes:
- Extracción
- StreamingPull
Usa las RPC de confirmación unaria y de ModifyAck requisitos cuando recibas mensajes mediante estas APIs. Las dos APIs de Pub/Sub se describen en las siguientes pestañas.
API de StreamingPull
Siempre que sea posible, las bibliotecas cliente de Pub/Sub usan StreamingPull para obtener la capacidad de procesamiento máxima y la latencia más baja. Aunque es posible que nunca uses la API de StreamingPull directamente, es importante que sepas en qué se diferencia de la API de Pull.
La API de StreamingPull se basa en una conexión bidireccional persistente para recibir varios mensajes a medida que estén disponibles. A continuación, se detalla el flujo de trabajo:
El cliente envía una solicitud al servidor para establecer una conexión. Si se supera la cuota de conexión, el servidor mostrará un error de recurso agotado. La biblioteca cliente vuelve a intentar los errores por falta de cuota automáticamente.
Si no se produce ningún error o si la cuota de conexión vuelve a estar disponible, el servidor envía mensajes de forma continua al cliente conectado.
Cuando se supera la cuota de capacidad de procesamiento, el servidor deja de enviar mensajes. Sin embargo, la conexión no se interrumpe. Cuando vuelva a tener suficiente cuota de capacidad de procesamiento disponible, se reanudará la transmisión.
El cliente o el servidor cierran la conexión finalmente.
La API de StreamingPull mantiene una conexión abierta. Los servidores de Pub/Sub cierran la conexión de forma recurrente después de un período para evitar una conexión persistente de larga duración. La biblioteca cliente vuelve a abrir de forma automática una conexión de StreamingPull.
Los mensajes se envían a la conexión cuando están disponibles. Por lo tanto, la API de StreamingPull minimiza la latencia y maximiza la capacidad de procesamiento de los mensajes.
Obtén más información sobre los métodos de REST de StreamingPull: StreamingPullRequest y StreamingPullResponse.
Obtén más información sobre los métodos de RPC de StreamingPull: StreamingPullRequest y StreamingPullResponse.
API de Pull
Esta API es una RPC unaria tradicional que se basa en un modelo de solicitud y respuesta. Una sola respuesta de extracción corresponde a una sola solicitud de extracción. El flujo de trabajo es el siguiente:
El cliente envía una solicitud al servidor para enviar mensajes. Si se supera la cuota de capacidad de procesamiento, el servidor mostrará un error de recurso agotado.
Si no se produce ningún error o si la cuota de capacidad de procesamiento vuelve a estar disponible, el servidor responde con cero o más mensajes y los IDs de confirmación.
Cuando se usa la API de extracción unaria, una respuesta con cero mensajes o con un error no necesariamente indica que no hay mensajes disponibles para recibir.
El uso de la API de extracción no garantiza una latencia baja ni una alta capacidad de procesamiento de mensajes. Para lograr una capacidad de procesamiento alta y una latencia baja con la API de extracción, debes tener varias solicitudes pendientes simultáneas. Las solicitudes nuevas se crean cuando las solicitudes anteriores reciben una respuesta. Diseñar una solución de este tipo es propenso a errores y es difícil de mantener. Te recomendamos que uses la API de StreamingPull para esos casos prácticos.
Usa la API de extracción en lugar de la API de StreamingPull solo si se requiere un control estricto sobre lo siguiente:
- La cantidad de mensajes que puede procesar el cliente suscriptor
- La memoria y los recursos del cliente
También puedes usar esta API cuando tu suscriptor es un proxy entre Pub/Sub y otro servicio que opera de una manera más orientada a la extracción.
Obtén más información sobre los métodos de REST de extracción: Método: projects.subscriptions.pull.
Obtén más información sobre los métodos de RPC de extracción: PullRequest y PullResponse.
Tipos de modos de procesamiento de mensajes
Elige uno de los siguientes modos de extracción para tus clientes suscriptores.
Modo de extracción asíncrono
El modo de extracción asíncrono separa la recepción de mensajes del procesamiento de mensajes en un cliente suscriptor. Este modo es el predeterminado para la mayoría de los clientes suscriptores. El modo de extracción asíncrono puede usar la API de StreamingPull o la API de Pull unaria. La extracción asíncrona también puede usar la biblioteca cliente de alto nivel o la biblioteca cliente de bajo nivel generada automáticamente.
Puedes obtener más información sobre las bibliotecas cliente más adelante en este documento.
Modo de extracción síncrono
En el modo de extracción síncrona, la recepción y el procesamiento de mensajes ocurren en secuencia y no se separan entre sí. Por lo tanto, al igual que con las APIs de StreamingPull en comparación con las APIs de Pull unarias, el procesamiento asíncrono ofrece una latencia más baja y una capacidad de procesamiento más alta que el procesamiento síncrono.
Usa el modo de extracción síncrona solo para aplicaciones en las que la latencia baja y la capacidad de procesamiento alta no son los factores más importantes en comparación con otros requisitos. Por ejemplo, una aplicación podría estar limitada a usar solo el modelo de programación síncrono. O bien, una aplicación con restricciones de recursos puede requerir un control más exacto sobre la memoria, la red o la CPU. En esos casos, usa el modo síncrono con la API de extracción unaria.
Bibliotecas cliente de Pub/Sub
Pub/Sub ofrece una biblioteca cliente de alto nivel y una de bajo nivel generada automáticamente.
Biblioteca cliente de Pub/Sub de alto nivel
La biblioteca cliente de alto nivel proporciona opciones para controlar los plazos de confirmación de recepción mediante la administración de la asignación de tiempo. Estas opciones son más detalladas que cuando configuras los plazos de confirmación de recepción mediante la consola o la CLI a nivel de suscripción. La biblioteca cliente de alto nivel también implementa compatibilidad con funciones como la entrega ordenada, la entrega “exactamente una vez” y el control de flujo.
Recomendamos usar una extracción asíncrona y la API de StreamingPull con la biblioteca cliente de alto nivel. No todos los lenguajes compatibles con Google Cloud también admiten la API de extracción en la biblioteca cliente de alto nivel.
Para usar bibliotecas cliente de alto nivel, consulta Bibliotecas cliente de Pub/Sub.
Biblioteca cliente de Pub/Sub generada automáticamente de bajo nivel
Hay una biblioteca cliente de bajo nivel disponible para casos en los que debes usar la API de extracción directamente. Puedes usar el procesamiento síncrono o asíncrono con la biblioteca cliente de bajo nivel generada de forma automática. Cuando uses la biblioteca cliente de bajo nivel generada automáticamente, debes codificar de forma manual las funciones, como la entrega ordenada, la entrega “exactamente una vez”, el control de flujo y la administración de arrendamientos.
Puedes usar el modelo de procesamiento síncrono cuando usas la biblioteca cliente de bajo nivel generada de forma automática para todos los lenguajes compatibles. Podrías usar la biblioteca cliente de bajo nivel generada automáticamente y la extracción síncrona en casos en los que usar directamente la API de extracción tenga sentido. Por ejemplo, es posible que tengas una lógica de aplicación existente que se basa en este modelo.
Para usar directamente las bibliotecas cliente de bajo nivel generadas de forma automática, consulta la Descripción general de las APIs de Pub/Sub.
Muestras de código de la biblioteca cliente
StreamingPull y muestras de código de la biblioteca cliente de alto nivel
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.
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.
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.
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.
Recupera atributos personalizados con la biblioteca cliente de alto nivel
En los siguientes ejemplos, se muestra cómo extraer mensajes de forma asíncrona y recuperar los atributos personalizados de los metadatos.
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.
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.
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.
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.
Soluciona errores con la biblioteca cliente de alto nivel
En los siguientes ejemplos, se muestra cómo manejar los errores que surgen cuando se suscriben a mensajes.
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.
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.
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.
Rita
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.
Muestras de códigos de extracción unarias
Este es un código de muestra para pull y confirmar una cantidad fija de mensajes.
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++.
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#.
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.
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.
PHP
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.
Protocolo
Solicitud:
POST https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription:pull
{
"returnImmediately": "false",
"maxMessages": "1"
}
Respuesta:
200 OK
{
"receivedMessages": [{
"ackId": "dQNNHlAbEGEIBERNK0EPKVgUWQYyODM2LwgRHFEZDDsLRk1SK...",
"message": {
"data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
"messageId": "19917247034"
}
}]
}
Solicitud:
POST https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription:acknowledge
{
"ackIds": [
"dQNNHlAbEGEIBERNK0EPKVgUWQYyODM2LwgRHFEZDDsLRk1SK..."
]
}
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.
Pub/Sub entrega una lista de mensajes. Si la lista tiene varios mensajes, Pub/Sub los ordena con la misma clave de ordenamiento. Las siguientes son algunas advertencias importantes:
Establecer un valor para
max_messages
en la solicitud no garantiza que se muestrenmax_messages
, incluso si hay muchos mensajes pendientes. Es posible que la API de extracción de Pub/Sub muestre menos demax_messages
para reducir la latencia de entrega de los mensajes que están disponibles para entregarse.Una respuesta de extracción que tiene 0 mensajes no se debe usar como indicador de que no hay mensajes en las tareas pendientes. Es posible obtener una respuesta con 0 mensajes y una solicitud posterior que muestre mensajes.
Para lograr una latencia de entrega de mensajes baja con el modo de extracción unario, es esencial tener muchas solicitudes de extracción pendientes al mismo tiempo. A medida que aumenta la capacidad de procesamiento del tema, se necesitan más solicitudes de extracción. En general, el modo StreamingPull es preferible para aplicaciones sensibles a la latencia.
Cuotas y límites
Las conexiones Pull y StreamingPull están sujetas a cuotas y límites. Para obtener más información, consulta Cuotas y límites de Pub/Sub.
¿Qué sigue?
Crea una suscripción de extracción para tu tema.
Crea o modifica una suscripción con la gcloud CLI.
Crea o modifica una suscripción con las APIs de REST.
Crea o modifica una suscripción con las APIs de RPC.