En este documento, se proporciona una descripción general de una suscripción de extracción, su flujo de trabajo y propiedades asociadas.
En una suscripción de extracción, un cliente suscriptor solicita mensajes al servidor de Pub/Sub.
El modo de extracción puede usar una de las dos APIs de servicio: Pull o StreamingPull. Para ejecutar la API elegida, puedes seleccionar un cliente de alto nivel proporcionado por Google o una biblioteca cliente de bajo nivel generada automáticamente. También puedes elegir entre el procesamiento de mensajes asíncrono y síncrono.
Antes de comenzar
Antes de leer este documento, asegúrate de estar familiarizado con la siguiente información:
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é podrías usar una extracción suscripción.
Flujo de trabajo de suscripciones de extracción
Para 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:
La mayoría de los clientes suscriptores no realizan estas solicitudes de forma directa. En cambio, el los clientes confían en la biblioteca cliente de alto nivel proporcionada por Google Cloud 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 un servicio de biblioteca de gRPC generada. Esta biblioteca realiza solicitudes 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 un suscripción de extracción.
![Flujo de mensajes para una suscripción de extracción](https://cloud.google.com/static/pubsub/images/subscriber_pull.png?authuser=1&hl=es-419)
![Flujo de mensajes de un
Suscripción streamingPull](https://cloud.google.com/static/pubsub/images/subscriber_streamingpull.png?authuser=1&hl=es-419)
Flujo de trabajo de extracción
El flujo de trabajo de extracción es el siguiente y hace referencia a la Figura 1:
- El cliente suscriptor llama explícitamente al método
pull
, que solicita para que se entreguen. Esta solicitud es elPullRequest
, como se muestra en el imagen. El servidor de Pub/Sub responde con cero o más mensajes y de confirmación de recepción. Una respuesta con cero mensajes o con un error no indican necesariamente que no hay mensajes disponibles para recibir. Esta es la
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 devuelto para confirmar que el mensaje se procesan y no deben volver a entregarse.
Para una sola solicitud de extracción de transmisión, un cliente suscriptor puede tener varias respuestas mostradas debido a la conexión abierta. Por el contrario, solo una respuesta es que se muestra 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 la escribes mensajes en tu suscripción. Para obtener más información, consulta propiedades de la suscripción.
APIs del servicio de Pub/Sub
La suscripción de extracción de Pub/Sub puede usar uno de los de las siguientes dos APIs para recuperar mensajes:
- Extracción
- StreamingPull
Usa RPC Acknowledge y ModifyAck inglés unarios cuando recibas mensajes con estas APIs. Las dos APIs de Pub/Sub se describen en el las siguientes pestañas.
API de StreamingPull
Cuando es posible, las bibliotecas cliente de Pub/Sub usan StreamingPull para obtener la máxima capacidad de procesamiento y la latencia más baja. Si bien es posible que nunca uses directamente en la API de StreamingPull, es importante conocer las diferencias 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, 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 muestra un recurso agotado . La biblioteca cliente vuelve a intentar los errores fuera de cuota automáticamente.
Si no se produce un error o la cuota de conexión está disponible nuevamente, el servidor envía mensajes continuamente al cliente conectado.
Si se supera la cuota de capacidad de procesamiento, el servidor deja de enviar mensajes nuevos. Sin embargo, la conexión no se interrumpe. Siempre que sea suficiente capacidad de procesamiento nuevamente disponible, se reanudará la transmisión.
El cliente o el servidor eventualmente cierran la conexión.
La API de StreamingPull mantiene una conexión abierta. El tema de Pub/Sub los servidores cierran de forma recurrente la conexión después de un tiempo para evitar y una conexión fija de larga duración. La biblioteca cliente se vuelve a abrir automáticamente una conexión de StreamingPull.
Los mensajes se envían a la conexión cuando están disponibles. El sistema StreamingPull Así, la API minimiza la latencia y maximiza la capacidad de procesamiento de los mensajes.
Obtén más información acerca de los métodos de RPC de StreamingPull: StreamingPullRequest y StreamingPullResponse.
API de Pull
Esta API es una RPC unaria tradicional que se basa en una solicitud y respuesta un modelo de responsabilidad compartida. Una sola respuesta de extracción corresponde a una sola solicitud de extracción. A continuación, se muestra el flujo de trabajo:
El cliente envía una solicitud al servidor para enviar mensajes. Si se supera la cuota de capacidad de procesamiento, el servidor muestra un recurso. error agotado.
Si no se produce un error o la cuota de capacidad de procesamiento está disponible nuevamente, el servidor respuestas con cero o más mensajes y con ID de confirmación de recepción.
Cuando se usa la API de Pull unaaria, una respuesta sin mensajes o con una no necesariamente indica que no haya mensajes disponibles para recibirlos.
Usar la API de Pull no garantiza una latencia baja ni una alta capacidad de procesamiento de mensajes nuevos. Para lograr una alta capacidad de procesamiento y baja latencia con la API de Pull, debes debe tener varias solicitudes pendientes simultáneas. Se crean solicitudes nuevas cuando las solicitudes anteriores reciben una respuesta. Diseñar una solución de este tipo es propensos a errores y difíciles de mantener. Te recomendamos que uses StreamingPull para estos casos de uso.
Usa la API de Pull en lugar de la API de StreamingPull solo si necesitas un control sobre los siguientes elementos:
- 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 sea un proxy entre Pub/Sub y otro servicio que opera en un entorno más orientada a la tracció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íncrona
El modo de extracción asíncrona separa la recepción de mensajes del procesamiento de mensajes en un cliente suscriptor. Este es el modo predeterminado para la mayoría clientes suscriptores. El modo de extracción asíncrona puede usar la API de StreamingPull o unary Pull API. La extracción asíncrona también puede usar la biblioteca cliente de alto nivel o una biblioteca cliente autogenerada de bajo nivel.
Puedes obtener más información sobre las bibliotecas cliente más adelante en este documento.
Modo de extracción síncrona
En el modo de extracción síncrona, la recepción y el procesamiento de mensajes ocurren secuencia de comandos y no se desacoplan entre sí. Por lo tanto, similar a StreamingPull frente a APIs de extracción unarias y ofertas de 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 con baja latencia y alta la capacidad de procesamiento no son los factores más importantes en comparación con otros y los requisitos de cumplimiento. Por ejemplo, una aplicación puede estar limitada a usar solo el modelo de programación síncrono. O bien, una aplicación con recursos podrían requerir un control más exacto sobre la memoria, la red 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 infraestructura de alto nivel y una de bajo nivel biblioteca cliente.
Biblioteca cliente de alto nivel de Pub/Sub
La biblioteca cliente de alto nivel proporciona opciones para controlar la plazos de confirmación de recepción con la administración de arrendamientos. Estas opciones son es más detallado que cuando configuras los plazos de confirmación con la consola o la CLI a nivel de la suscripción. El cliente de alto nivel también implementa la compatibilidad con funciones como la entrega ordenada, entrega “exactamente una vez” y control de flujo.
Recomendamos usar una extracción asíncrona y la API de StreamingPull con el biblioteca cliente de alto nivel. No todos los idiomas compatibles con Google Cloud también admite la API de Pull 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
Existe una biblioteca cliente de bajo nivel disponible para los casos en los que debas usar el API de extracción directamente. Puedes usar el procesamiento síncrono o asíncrono con la biblioteca cliente de bajo nivel generada automáticamente. Debes codificar de forma manual las funciones entrega ordenada, entrega exactamente una vez, control de flujo y administración de retenciones cuando uses la biblioteca cliente de bajo nivel generada automáticamente.
Puedes usar el modelo de procesamiento síncrono cuando usas el modelo generada automáticamente para todos los idiomas compatibles. Puedes usar la una biblioteca cliente generada automáticamente de bajo nivel y una extracción síncrona en los casos en que usar directamente la API de Pull. Por ejemplo, puedes tener la lógica de aplicación que se basa en este modelo.
Para usar directamente las bibliotecas cliente de bajo nivel generadas automáticamente, consulta Descripción general de las APIs de Pub/Sub.
Muestras de código de la biblioteca cliente
StreamingPull y muestras de código de 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.
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.
Recupera atributos personalizados con la biblioteca cliente de alto nivel
Los siguientes ejemplos muestran 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.
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.
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 los 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.
Ruby
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ódigo de extracción unarias
Aquí hay algunos códigos de muestra atracción y aceptar 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#.
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.
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.
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. A continuación, se incluyen algunas advertencias importantes:
Establecer un valor para
max_messages
en la solicitud no garantiza que se devuelvanmax_messages
, incluso si hay tantos mensajes en la tareas 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 entregar.Una respuesta de extracción que viene con 0 mensajes no debe usarse como indicador que no haya mensajes pendientes. Es posible obtener una respuesta con 0 mensajes y una solicitud posterior que devuelva mensajes.
Para lograr una latencia baja de entrega de mensajes con el modo de extracción unario, esencial para tener muchas solicitudes de extracción pendientes al mismo tiempo. Como aumenta la capacidad de procesamiento del tema, se necesitan más solicitudes de extracción. En general, el modo StreamingPull es preferible para sensibles a la latencia.
Cuotas y límites
Las conexiones de extracción y de 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 gcloud CLI.
Crea o modifica una suscripción con las APIs de REST.
Crea o modifica una suscripción con las APIs de RPC.