En este documento, se describe cómo configurar la exportación automática de mensajes de Pub/Sub Lite a Pub/Sub.
Estas son algunas situaciones en las que podrías usar esta función:
- Interoperar entre las cargas de trabajo que usan una combinación de Pub/Sub Lite y Pub/Sub
- Migra una carga de trabajo de Pub/Sub Lite a Pub/Sub.
- Usar funciones avanzadas de Pub/Sub, como las suscripciones de envío y el filtrado, de una aplicación existente basada en Pub/Sub Lite.
- Consolidar múltiples canalizaciones de datos
Descripción general
Para exportar mensajes de Pub/Sub Lite a Pub/Sub, debes crear un tipo especial de suscripción llamada suscripción de exportación. Una suscripción de exportación recibe mensajes de un tema Lite, los convierte en mensajes de Pub/Sub y los envía a un tema de Pub/Sub de destino.
Un tema Lite puede tener una combinación de suscripciones de exportación y de suscripciones estándar. Los dos tipos de suscripción son idénticos en términos de uso de cuota y capacidad de procesamiento de reserva. Una suscripción de exportación consume la capacidad de procesamiento de la suscripción Lite y se cobra por la capacidad de procesamiento de publicación de Pub/Sub.
Una suscripción de exportación conecta un tema Lite a un solo tema de Pub/Sub. Sin embargo, un tema Lite puede tener varias suscripciones de exportación que se conectan a diferentes temas de Pub/Sub (arquitectura de fan-out). También puedes exportar varios temas de Lite al mismo tema de Pub/Sub (arquitectura de fan-in).
Autenticación
Una suscripción de exportación accede a los recursos de Pub/Sub Lite y Pub/Sub. Para crear una suscripción de exportación, necesitas los siguientes permisos:
pubsublite.subscriptions.create
. Las siguientes funciones predefinidas contienen este permiso:roles/pubsublite.admin
roles/pubsublite.editor
Consulta Control de acceso para Pub/Sub Lite.
pubsub.topics.get
. Las siguientes funciones predefinidas contienen este permiso:roles/pubsub.admin
roles/pubsub.editor
roles/pubsub.viewer
Consulta Control de acceso para Pub/Sub.
Agentes de servicio
Una suscripción de exportación publica en un tema de Pub/Sub en tu nombre. Para ello, utiliza una cuenta de servicio administrada por Google.
Cuando creas la primera suscripción de exportación en un proyecto, se crea automáticamente un agente de servicio de Pub/Sub Lite administrado por Google. Si creas suscripciones de exportación adicionales en el mismo proyecto, estas usan el mismo agente de servicio. El agente de servicio tiene el siguiente esquema de nombres: service-<your_project_number>@gcp-sa-pubsublite.iam.gserviceaccount.com
.
El agente de servicio se crea con permisos para publicar en todos los temas de Pub/Sub y Pub/Sub Lite dentro del mismo proyecto que la suscripción de exportación. Si tu tema de Pub/Sub de destino está en un proyecto diferente que la suscripción de exportación, debes otorgar permisos adicionales al agente de servicio; para ello, agrega la función de Publicador de Pub/Sub (roles/pubsub.publisher
). Puedes otorgar permisos para un proyecto completo o un tema individual. Recomendamos otorgar permisos a nivel del tema, de acuerdo con el principio de privilegio mínimo.
Para obtener más información, consulta
Controla el acceso a través de la consola de Google Cloud.
También puedes usar el comando gcloud projects add-iam-policy-binding
para agregar roles de IAM:
gcloud pubsub topics add-iam-policy-binding TOPIC_NAME \ --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsublite.iam.gserviceaccount.com --role=roles/pubsub.publisher
Reemplaza lo siguiente:
- TOPIC_NAME: Es el nombre del tema de Pub/Sub de destino para agregar la vinculación de política de IAM.
- PROJECT_NUMBER: Es el número del proyecto de la suscripción a la exportación de Pub/Sub Lite.
Crea una suscripción de exportación
Puedes crear una suscripción de exportación Lite con la consola de Google Cloud, Google Cloud CLI o la API de Pub/Sub Lite.
La suscripción de exportación Lite debe estar en el mismo proyecto y la misma ubicación que el tema de Lite al que está vinculada. Para crear el tema Lite, consulta Cómo crear y administrar temas Lite.
Si adjuntas una suscripción de exportación a un tema Lite, asegúrate de que todos los mensajes publicados en ese tema sean compatibles con Pub/Sub. Para obtener más información, consulta Compatibilidad con mensajes.
Una vez creada, no puedes cambiar una suscripción de exportación a una suscripción estándar, ni viceversa.
Console
Ve a la página Suscripciones de Lite.
Haz clic en Crear suscripción Lite.
Ingresa un ID de suscripción Lite.
Selecciona un tema de Lite para recibir mensajes.
Selecciona Enviar mensajes de inmediato o Enviar mensajes después de almacenarlos.
Elige un tipo de Compensación inicial.
Selecciona Exportar al tema de Pub/Sub.
En la lista Tema de destino, elige un tema de Pub/Sub para recibir los mensajes de Lite exportados.
Opcional. Especifica un tema de mensajes no entregados.
- Selecciona la casilla de verificación Habilitar mensajes no entregados.
- Selecciona un tema Lite para usar como tema de mensajes no entregados o haz clic en Create Lite para crear uno nuevo. El tema de mensajes no entregados debe estar en la misma ubicación (zona o región) y el mismo proyecto que la suscripción de exportación.
Haz clic en Crear.
gcloud
Para crear una suscripción de exportación, usa el comando gcloud pubsub lite-subscriptions create
:
gcloud pubsub lite-subscriptions create SUBSCRIPTION_ID \ --location=LOCATION \ --topic=TOPIC_ID \ --export-pubsub-topic=PUBSUB_TOPIC_NAME \ --export-dead-letter-topic=DEAD_LETTER_TOPIC_ID \ --export-desired-state=DESIRED_STATE
Reemplaza lo siguiente:
- SUBSCRIPTION_ID: Es el ID de la suscripción Lite que se creará.
- LOCATION: Es la ubicación de la suscripción Lite.
- TOPIC_ID: Es el ID del tema de Lite que se conectará a la suscripción de Lite.
- PUBSUB_TOPIC_NAME: Es el nombre del tema de Pub/Sub al que se exportará. Especifica el nombre completo si el tema está en un proyecto diferente:
projects/my-project-id/topics/my-topic-id
. - DEAD_LETTER_TOPIC_ID: Opcional Es el ID de un tema Lite que se usará como tema de mensajes no entregados. El tema de mensajes no entregados debe estar en la misma ubicación (zona o región) y el mismo proyecto que la suscripción a la exportación.
- DESIRED_STATE: Opcional Es el estado inicial de la suscripción.
Se admiten los siguientes valores:
active
: La suscripción exporta mensajes de Lite a Pub/Sub. (predeterminado)paused
: Se suspendió la exportación de mensajes Lite.
Si la solicitud es exitosa, la línea de comandos muestra una confirmación:
Created [SUBSCRIPTION_ID].
Protocolo
Para crear una suscripción de exportación Lite, envía una solicitud POST
como la
siguiente:
POST https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID Authorization: Bearer $(gcloud auth print-access-token)
Reemplaza lo siguiente:
- REGION: Es la región en la que se almacenará la suscripción Lite.
- PROJECT_NUMBER: Es el número del proyecto en el que se creará la suscripción Lite.
- LOCATION: Es el nombre de una ubicación que admite Pub/Sub Lite.
- SUBSCRIPTION_ID: Es el ID de la suscripción Lite.
Especifica los siguientes campos en el cuerpo de la solicitud:
{ "topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID", "deliveryConfig": { "deliveryRequirement": "DELIVERY_REQUIREMENT", }, "exportConfig": { "desiredState": "DESIRED_STATE", "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID", "pubsubConfig": { "topic": "PUBSUB_TOPIC_NAME" } } }
Reemplaza lo siguiente:
- DELIVERY_REQUIREMENT: Es el requisito de entrega, que puede ser
DELIVER_AFTER_STORED
oDELIVER_IMMEDIATELY
. - DESIRED_STATE: Es el estado inicial de la suscripción. Se admiten los siguientes valores:
ACTIVE
: La suscripción exporta mensajes de Lite a Pub/Sub.PAUSED
: Se suspendió la exportación de mensajes Lite.
- DEAD_LETTER_TOPIC_ID: Es el ID de un tema de Lite existente que se usará como un tema de mensajes no entregados. El tema debe estar en la misma ubicación (zona o región) y el mismo proyecto que la suscripción a la exportación en sí.
- PUBSUB_TOPIC_NAME: Es el nombre del tema de Pub/Sub al que se exportará. Formato de ejemplo:
projects/my-project-id/topics/my-topic-id
.
Si la solicitud es exitosa, la respuesta es la suscripción Lite en formato JSON:
{ "deliveryConfig": { "deliveryRequirement": "DELIVERY_REQUIREMENT", }, "exportConfig": { "desiredState": "DESIRED_STATE", "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID", "pubsubConfig": { "topic": "PUBSUB_TOPIC_NAME" }, "name": "projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID", "topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID", }
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 ejecutar esta muestra, sigue las instrucciones de configuración de Java en las bibliotecas cliente de Pub/Sub Lite.
Python
Antes de ejecutar esta muestra, sigue las instrucciones de configuración de Python en las bibliotecas cliente de Pub/Sub Lite.
Actualiza una suscripción de exportación
Puedes actualizar las suscripciones Lite con la consola de Google Cloud, Google Cloud CLI o la API de Pub/Sub Lite. La configuración nueva puede tardar hasta 30 segundos en aplicarse.
Console
Ve a la página Suscripciones de Lite.
Haz clic en el ID de suscripción Lite.
En la página Detalles de la suscripción Lite, haz clic en Editar.
gCloud
Para actualizar una suscripción Lite, usa el comando gcloud pubsub lite-subscriptions update
:
gcloud pubsub lite-subscriptions update SUBSCRIPTION_ID \ --location=LOCATION \ --delivery-requirement=DELIVERY_REQUIREMENT \ --export-pubsub-topic=PUBSUB_TOPIC_NAME \ --export-dead-letter-topic=DEAD_LETTER_TOPIC_ID \ --export-desired-state=DESIRED_STATE
Reemplaza lo siguiente:
- SUBSCRIPTION_ID: Es el ID de la suscripción Lite.
- LOCATION: Es la ubicación de la suscripción Lite.
- DELIVERY_REQUIREMENT: Opcional El requisito de entrega, que puede ser
deliver-after-stored
odeliver-immediately
- PUBSUB_TOPIC_NAME: Opcional El nombre del tema de Pub/Sub al que se realizará la exportación. Especifica el nombre completo si el tema está en un proyecto diferente:
projects/my-project-id/topics/my-topic-id
. - DEAD_LETTER_TOPIC_ID: Es el ID de un tema de Lite existente que se usará como un tema de mensajes no entregados. El tema debe estar en la misma ubicación (zona o región) y el mismo proyecto que la suscripción a la exportación en sí.
- DESIRED_STATE: Opcional Estado deseado de la suscripción.
Se admiten los siguientes valores:
active
: La suscripción exporta mensajes de Lite a Pub/Sub. (predeterminado)paused
: Se suspendió la exportación de mensajes Lite.
Si la solicitud es exitosa, la línea de comandos muestra el tema de Lite:
Updated subscription [SUBSCRIPTION_ID]. deliveryConfig: deliveryRequirement: DELIVERY_REQUIREMENT exportConfig: currentState: DESIRED_STATE deadLetterTopic: projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID desiredState: DESIRED_STATE pubsubConfig: topic: PUBSUB_TOPIC_NAME name: projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID topic: projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID
Protocolo
Para actualizar una suscripción Lite, envía una solicitud PATCH
como la siguiente:
PATCH https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID?updateMask=deliveryConfig.deliveryRequirement,exportConfig Authorization: Bearer $(gcloud auth print-access-token)
Reemplaza lo siguiente:
- REGION: Es la región en la que se creó la suscripción Lite.
- PROJECT_NUMBER: Es el número del proyecto en el que se creó la suscripción Lite.
- LOCATION: Es la ubicación en la que se creó la suscripción a Lite.
- SUBSCRIPTION_ID: Es el ID de la suscripción Lite.
Especifica los siguientes campos en el cuerpo de la solicitud:
{ "deliveryConfig": { "deliveryRequirement": "DELIVERY_REQUIREMENT", }, "exportConfig": { "desiredState": "DESIRED_STATE", "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID", "pubsubConfig": { "topic": "PUBSUB_TOPIC_NAME" } } }
Reemplaza lo siguiente:
- DELIVERY_REQUIREMENT: Es el requisito de entrega, que puede ser
DELIVER_AFTER_STORED
oDELIVER_IMMEDIATELY
. - DESIRED_STATE: Es el estado deseado para la suscripción. Se admiten los siguientes valores:
ACTIVE
: La suscripción exporta mensajes de Lite a Pub/Sub.PAUSED
: Se suspendió la exportación de mensajes Lite.
- DEAD_LETTER_TOPIC_ID: Es el ID de un tema de Lite existente que se usará como un tema de mensajes no entregados. El tema debe estar en la misma ubicación (zona o región) y el mismo proyecto que la suscripción a la exportación en sí.
- PUBSUB_TOPIC_NAME: Es el nombre del tema de Pub/Sub de destino. Formato de ejemplo:
projects/my-project-id/topics/my-topic-id
.
Si la solicitud es exitosa, la respuesta es la suscripción Lite en formato JSON:
{ "deliveryConfig": { "deliveryRequirement": "DELIVERY_REQUIREMENT", }, "exportConfig": { "desiredState": "DESIRED_STATE", "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID", "pubsubConfig": { "topic": "PUBSUB_TOPIC_NAME" } }, "name": "projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID", "topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID", }
Cómo pausar o iniciar una exportación de suscripción
La exportación de suscripciones tiene una configuración llamada estado deseado, que tiene uno de dos valores:
- Activa: La suscripción exporta mensajes de Lite a Pub/Sub.
- Detenida: Se suspendió la exportación de mensajes Lite.
Sigue estos pasos para cambiar el estado deseado en la consola de Google Cloud:
Ve a la página Suscripciones de Lite.
Haz clic en el ID de suscripción Lite.
En la página Detalles de suscripción lite, haz clic en Pausar o Iniciar.
También puedes actualizar el estado deseado con Google Cloud CLI o la API Lite de Pub/Sub. Consulta Cómo actualizar una suscripción de exportación.
prácticas recomendadas
En esta sección, se describen algunas prácticas recomendadas para usar suscripciones de exportación.
Reservas
Recomendamos usar una suscripción de exportación con una reserva, en lugar de configurar explícitamente la capacidad de procesamiento de la suscripción.
Compatibilidad de los mensajes
Si un mensaje de Pub/Sub Lite no es compatible con Pub/Sub, la suscripción de exportación no publicará el mensaje en Pub/Sub. En su lugar, coloca el mensaje en el tema de mensajes no entregados, si se asignó uno. Si no se asignó ningún tema de mensajes no entregados, los mensajes incompatibles simplemente se descartan.
Cuando publiques mensajes en el tema de Lite, ten en cuenta los siguientes problemas de compatibilidad:
Claves. Las claves de Pub/Sub Lite tienen el tipo
bytes
, mientras que las claves de ordenamiento de Pub/Sub son del tipostring
. Para ser compatible, la clave de Pub/Sub Lite debe contener solo caracteres UTF-8.Atributos: Los atributos de mensaje tienen los siguientes requisitos:
- Para ser compatibles, todos los atributos de mensajes de Pub/Sub Lite deben tener un solo valor. Pub/Sub Lite admite atributos de mensajes con varios valores, pero Pub/Sub solo admite atributos de valor único.
- Los atributos de mensaje no deben exceder los límites de mensajes de Pub/Sub, incluidos los atributos máximos por mensaje y el tamaño máximo de la clave y el valor por atributo.
Tema de mensajes no entregados
Para retener y administrar mensajes incompatibles, te recomendamos que uses un tema de mensajes no entregados. Puedes asignar un tema de mensajes no entregados cuando creas la suscripción de exportación o puedes actualizar una suscripción de exportación existente para usar un tema de mensajes no entregados. Si la suscripción recibe un mensaje que no es compatible con Pub/Sub, publica el mensaje en el tema de mensajes no entregados.
Un tema de mensajes no entregados es un tema normal de Pub/Sub Lite. Debe estar en la misma ubicación y el mismo proyecto que la suscripción de exportación, y debe ser un tema diferente del tema de origen.
Por lo general, los tema de mensajes no entregados tienen un uso de capacidad de procesamiento bajo. Por lo tanto, recomendamos asignar una reserva al tema de mensajes no entregados, en lugar de asignar la capacidad de procesamiento al tema.
Errores de entrega
Una suscripción de exportación intenta entregar todos los mensajes compatibles al tema de Pub/Sub de destino. Si falla la entrega de mensajes, se suspende la suscripción de exportación. Para encontrar la categoría del error, verifica la métrica subscription/export_status
. Los siguientes valores indican un error:
PERMISSION_DENIED
: No tienes permisos suficientes para exportar mensajes.NOT_FOUND
: No se encontraron uno o más recursos; por ejemplo, el tema de destino no existe.
Si quieres obtener más información para solucionar problemas, consulta Cómo solucionar problemas relacionados con la exportación de suscripciones.
Después de resolver el error, la suscripción de exportación se reinicia de forma automática debido a reintentos periódicos.
Precios
Se te cobra por los recursos de Pub/Sub Lite y Pub/Sub que consume la suscripción de exportación. En particular, se te cobra por la capacidad de procesamiento y el almacenamiento asignados a la suscripción en la suscripción a Pub/Sub Lite, que se configuran para el tema de Pub/Sub Lite. También se te cobra por publicar en el tema de Pub/Sub de destino. Consulta los precios de Pub/Sub.
No se aplican cargos adicionales por usar la función de exportación y no hay diferencia de precios entre las suscripciones a exportación de Pub/Sub Lite y las suscripciones estándar.
Soluciona problemas relacionados con la exportación de suscripciones
En esta sección, se describen algunas sugerencias para solucionar problemas relacionados con la exportación de suscripciones.
Se pausó la suscripción de exportación
Si se pausa la suscripción, no se exportarán mensajes.
Para detectar este problema, haz lo siguiente:
Consola de Google Cloud: Consulta los detalles de la suscripción. Si la suscripción está detenida, los valores de Estado deseado y Estado actual son
Paused
.Métricas: La métrica
subscription/export_status
esPAUSED
.
Para resolver este problema, inicia la suscripción.
Se borró el tema de destino o de tema de mensajes no entregados
Si borras el tema de Pub/Sub adjunto a una suscripción de exportación o borras el tema de mensajes no entregados, se producirá un error.
Para detectar este problema, haz lo siguiente:
Consola de Google Cloud: Consulta los detalles de la suscripción. Si se borró el tema, el Estado actual es
Not found
.Métricas: La métrica
subscription/export_status
. Si se borró el tema, el valor esNOT_FOUND
.
Para resolver este problema, verifica el tema de Pub/Sub de destino y el tema de mensajes no entregados (si se configuró uno).
Si se borró el Pub/Sub de destino, vuelve a crear el tema con el mismo nombre. La suscripción de exportación reanuda la publicación, suponiendo que los permisos no cambiaron.
Si se borró el tema de mensajes no entregados, crea uno nuevo y actualiza la suscripción de exportación para hacer referencia a él.
Mensajes incompatibles
Si los mensajes no son compatibles con Pub/Sub, no se exportarán.
Para detectar este problema, haz lo siguiente:
- Métricas: La métrica
subscription/unexportable_message_count
muestra el recuento de mensajes incompatibles que no se pudieron exportar.
Para resolver este problema, usa un tema de mensajes no entregados para conservar los mensajes incompatibles. Examina los mensajes para determinar la causa y, luego, transfórmalos y vuelve a publicarlos si es necesario. Consulta Compatibilidad con mensajes.
La exportación está limitada
Para detectar este problema, haz lo siguiente:
- Métricas: La métrica
subscription/flow_control_status
muestra un motivo de control de flujo deNO_CLIENT_TOKENS
, que indica que se alcanzó el límite por partición de bytes o mensajes pendientes. Hasta que se resuelva el problema, aumentará la cantidad de tareas pendientes para las suscripciones de exportación asociadas.
Este error tiene varias causas raíz posibles. La mayoría de las causas posibles ocurren en el backend, pero verifica lo siguiente:
- Asegúrate de publicar mensajes Lite que compartan la misma clave a una velocidad inferior a 1 MiB/s por clave. La suscripción de exportación escribe las claves de mensajes Lite como claves de ordenamiento de Pub/Sub, y Pub/Sub tiene un límite de 1 MiB/s para cada clave de ordenamiento. Exceder este límite puede causar una limitación.
Usuario no autorizado para realizar esta acción
El agente de servicio de Pub/Sub Lite debe tener permisos para publicar en el tema de Pub/Sub de destino.
Para detectar este problema, haz lo siguiente:
Consola de Google Cloud: Consulta los detalles de la suscripción. Si hay errores de permisos, el Estado actual es
Permission denied
.Métricas: La métrica
subscription/export_status
esPERMISSON_DENIED
.
Por ejemplo, las siguientes situaciones pueden causar este error:
- Al agente de servicio de Pub/Sub Lite le falta el permiso o la función correctos para publicar mensajes en el tema de Pub/Sub de destino en un proyecto diferente.
- Se quitó el agente de servicio de la política de IAM del proyecto superior de la suscripción de exportación.
- Aún se está configurando el agente de servicio de Pub/Sub Lite. Cuando creas la primera suscripción de exportación en un proyecto, se crea automáticamente un agente de servicio. El error de permiso debería resolverse automáticamente en 10 minutos.
Para resolver el problema, verifica si se le otorgó el permiso o la función correctos al agente de servicio. Consulta Agentes de servicio.
¿Qué sigue?
Elige entre Pub/Sub o Pub/Sub Lite.