Propiedades de suscripción

Las propiedades de suscripción de Pub/Sub son las características de una suscripción. Puedes establecer propiedades de suscripción cuando creas o actualizas una.

En este documento, se describen las diferentes propiedades de suscripción que puedes establecer para una suscripción.

Antes de comenzar

• Obtén más información sobre las suscripciones.

• Comprende el flujo de trabajo de la suscripción que crearás: Extracción, Envío o BigQuery.

Propiedades comunes de las suscripciones

Cuando creas una suscripción, debes especificar varias opciones para configurarla. Algunas de estas propiedades son comunes a todos los tipos de suscripciones y se analizan en las siguientes secciones.

Tiempo de retención de mensajes

La opción Duración de retención de mensajes especifica el tiempo que Pub/Sub retiene mensajes después de la publicación. Después de que transcurre la duración de retención del mensaje, Pub/Sub puede descartar el mensaje independientemente del estado de confirmación del mensaje. Para retener los mensajes confirmados durante el tiempo de retención de mensajes, consulta la página Vuelve a reproducir y descarta mensajes.

Los siguientes son los valores de la opción Duración de la retención de mensajes:

• Valor predeterminado = 7 días
• El valor mínimo es de 10 minutos.
• El valor máximo es de 31 días.

Los mensajes no confirmados pueden deberse a suscripciones inactivas, necesidades de copias de seguridad o procesamiento lento. Si puedes procesar los mensajes en un plazo de 24 horas, no se generarán cargos adicionales. Para evitar cargos nuevos, administra estas situaciones de la siguiente manera:

• Suscripciones inactivas. Borra las suscripciones inactivas para evitar cargos por retención de mensajes de suscripción.

• Almacenamiento en copias de seguridad Si usas la retención de suscripciones como almacenamiento de copias de seguridad, puedes cambiar a otra opción de almacenamiento, como la retención de mensajes de temas o la retención de mensajes reconocidos. La retención de mensajes del tema almacena los mensajes solo una vez a nivel del tema y permanecen disponibles para que todas las suscripciones los consuman cuando sea necesario.

• Demoras en el procesamiento Agrega más suscriptores (si es posible) para procesar los mensajes en un día.

Retener mensajes confirmados

Si especificas la Duración de la retención de mensajes, también puedes especificar si deseas conservar los mensajes confirmados.

La opción Retain acknowledged messages te permite conservar los mensajes confirmados durante el período de retención de mensajes especificado. Esta opción hace que las tarifas de almacenamiento de mensajes aumenten. Para obtener más información, consulta los costos de almacenamiento.

Período de vencimiento

La opción Período de vencimiento te permite extender el período de vencimiento de tu suscripción.

Las suscripciones sin actividad del suscriptor ni cambios en las propiedades de la suscripción vencen. Si Pub/Sub detecta actividad de suscriptores o si actualizas alguna de las propiedades de la suscripción, se reiniciará el reloj de eliminación de suscripciones. Entre los ejemplos de actividades del suscriptor, se incluyen las conexiones abiertas, las extracciones activas o las inserciones exitosas.

Si especificas el período de vencimiento, el valor debe ser, al menos, igual que la duración de retención de mensajes especificada en la opción Duración de retención de mensajes.

Los siguientes son los valores para la opción Período de vencimiento:

• El valor predeterminado es de 31 días.
• El valor mínimo es 1 día.

Para evitar que una suscripción venza, establece el período de vencimiento en never expire.

Fecha límite de confirmación

La opción Plazo de confirmación especifica el plazo inicial después del cual se vuelve a enviar un mensaje no confirmado. Puedes extender el plazo de confirmación de cada mensaje enviando solicitudes posteriores de ModifyAckDeadline.

Los siguientes son los valores para la opción Fecha límite de confirmación:

• Valor predeterminado = 10 segundos
• Valor mínimo = 10 segundos
• El valor máximo es de 600 segundos.

En algunos casos, las bibliotecas cliente de Pub/Sub pueden controlar la frecuencia de entrega y modificar de forma dinámica el plazo de confirmación. Si lo haces, es posible que el mensaje se vuelva a enviar antes de la fecha límite de confirmación que estableciste. Para anular este comportamiento, usa minDurationPerAckExtension y maxDurationPerAckExtension. Para obtener más información sobre el uso de estos valores, consulta Compatibilidad con la entrega exactamente una vez en las bibliotecas cliente.

Transformaciones de mensaje único (SMT)

Los SMT permiten realizar modificaciones ligeras en los atributos y los datos de los mensajes directamente en Pub/Sub. Esta función permite limpiar, filtrar o convertir el formato de los datos antes de que los mensajes se entreguen a un cliente suscriptor.

Para obtener más información, consulta Descripción general de los SMT y Crea una suscripción con SMT.

Filtro de suscripción

Usa la opción Subscription filter para especificar una cadena con una expresión de filtrado. Si una suscripción tiene un filtro, la suscripción solo entrega los mensajes que coinciden con él. El servicio de Pub/Sub confirma automáticamente los mensajes que no coinciden con el filtro.

• Puedes filtrar los mensajes según sus atributos, pero no según los datos que contienen.

• Si no se especifica, la suscripción no filtra los mensajes y los suscriptores los reciben todos.

• Los filtros no se pueden cambiar ni quitar después de que los aplicas.

Cuando recibes mensajes de una suscripción con un filtro, no generas tarifas de salida para los mensajes que Pub/Sub confirma de forma automática. Se cobran tarifas por la entrega de mensajes y el almacenamiento relacionado con las búsquedas para estos mensajes.

Para obtener más información, consulta Cómo filtrar mensajes de una suscripción.

Ordenamiento de mensajes

Cuando una suscripción tiene habilitado el ordenamiento de mensajes, los clientes suscriptores reciben los mensajes publicados en la misma región con la misma clave de ordenamiento en el orden en que el servicio los recibió.

Cuando se usa la entrega ordenada, las confirmaciones de recepción de los mensajes posteriores no se procesan hasta que se procesan las de los mensajes anteriores.

Los publicadores deben enviar mensajes con una clave de ordenamiento para que Pub/Sub pueda entregar los mensajes en orden.

Si no se establece, es posible que Pub/Sub no entregue los mensajes en orden, incluso si tienen una clave de ordenamiento.

Tema de mensajes no entregados

Cuando no se puede entregar un mensaje después de una cantidad establecida de intentos de entrega o un suscriptor no puede confirmar el mensaje, puedes configurar un tema de mensajes no entregados en el que se puedan volver a publicar estos mensajes.

Si estableces un tema de mensajes no entregados, también puedes especificar la cantidad máxima de intentos de entrega. A continuación, se indican los valores para la cantidad máxima de intentos de entrega del tema de mensajes no entregados:

• El valor predeterminado es de 5 intentos de entrega.
• Valor mínimo = 5 intentos de entrega
• El valor máximo es de 100 intentos de entrega.

Si el tema de mensajes no entregados está en un proyecto diferente al de la suscripción, también debes especificar el ID del proyecto con el tema de mensajes no entregados.

Para obtener más información, consulta Reenvío a temas de mensajes no entregados.

Política de reintentos

Si vence el plazo de confirmación o un suscriptor responde con una confirmación de recepción negativa, Pub/Sub puede volver a enviar el mensaje. Este intento de reenvío se conoce como la política de reintentos de la suscripción.

De forma predeterminada, la política de reintentos de una suscripción se establece para usar Reintentar de inmediato. Con esta opción, Pub/Sub reenvía el mensaje cuando vence el plazo de confirmación de recepción o un suscriptor responde con una confirmación de recepción negativa.

También puedes establecer el valor en Reintentar después de un retraso de retirada exponencial. En este caso, debes especificar los valores de retirada máximos y mínimos.

A continuación, se incluyen algunas pautas para establecer los valores de retirada máximos y mínimos:

• Si estableces el valor máximo para la duración de la retirada, el valor predeterminado para la duración mínima de la retirada es de 10 segundos.

• Si estableces el valor mínimo para la duración de retirada, el valor predeterminado para la duración máxima de retirada es de 600 segundos.

• La duración de retirada más larga que puedes especificar es de 600 segundos.

Política de reintentos y mensajes por lotes

Si los mensajes están en un lote, Pub/Sub inicia la retirada exponencial cuando ocurre una de las siguientes situaciones:

• El suscriptor envía una confirmación negativa para cada mensaje en el lote.

• El plazo de confirmación de recepción vence.

Política de reintentos y suscripción push

Si recibes mensajes de una suscripción de envío, Pub/Sub podría volver a entregar mensajes después de la retirada de envío en lugar de la duración de retirada exponencial. Cuando la retirada de envío es más larga que la duración de la retirada exponencial, Pub/Sub vuelve a entregar los mensajes no confirmados después de la retirada de envío.

Propiedades de la suscripción de extracción

Cuando configuras una suscripción de extracción, puedes especificar las siguientes propiedades.

Entrega “exactamente una vez”

Entrega “exactamente una vez”. Si se configura, Pub/Sub cumple con las garantías de entrega exactamente una vez. Si no se especifica, la suscripción admite la entrega al menos una vez para cada mensaje.

Propiedades de suscripción de envío

Cuando configuras una suscripción de envío, puedes especificar las siguientes propiedades.

Extremos

URL del extremo (obligatoria) Una dirección HTTPS de acceso público. El servidor para el extremo de envío debe tener un certificado SSL válido firmado por una autoridad certificada. El servicio de Pub/Sub entrega mensajes a los extremos de envío desde la misma Google Cloud región en la que el servicio de Pub/Sub almacena los mensajes. El servicio de Pub/Sub entrega mensajes de la misma Google Cloud región según el criterio del mejor esfuerzo.

• Si los suscriptores usan un firewall, no pueden recibir solicitudes de envío. Para recibir solicitudes de envío, debes desactivar el firewall y verificar el token web JSON (JWT) que se usa en la solicitud. Si un suscriptor tiene un firewall, es posible que recibas un error 403 permission denied.

• Pub/Sub ya no requiere títulos de propiedad para los dominios de URL de suscripción de envío. Si tu dominio recibe solicitudes POST inesperadas de Pub/Sub, puedes informar sospechas de abuso.

Autenticación

Habilita la autenticación. Cuando está habilitada, los mensajes que Pub/Sub entrega al extremo de envío incluyen un encabezado de autorización para permitir que el extremo autentique la solicitud. Los mecanismos de autenticación y autorización automáticos están disponibles para los extremos del entorno estándar de App Engine y Cloud Run Functions alojados en el mismo proyecto que la suscripción.

La configuración de autenticación para una suscripción push autenticada consta de una cuenta de servicio administrada por el usuario y los parámetros de público que se especifican en una llamada create, patch o ModifyPushConfig. También debes otorgar un rol específico a una cuenta de servicio, como se explica en la siguiente sección.

• Público: Es una cadena única que no distingue mayúsculas de minúsculas y que el webhook usa para validar el público objetivo de este token en particular.

• Cuenta de servicio: Pub/Sub crea automáticamente una cuenta de servicio para ti con el formato service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com.

Requisitos previos para habilitar la autenticación

La cuenta de servicio administrada por el usuario es la cuenta de servicio asociada con la suscripción de envío. Esta cuenta se usa como el reclamo email del token web JSON (JWT) generado. A continuación, se incluye una lista de requisitos para la cuenta de servicio:

• Esta cuenta de servicio administrada por el usuario debe estar en el mismo proyecto que la suscripción push.

• La principal que crea o modifica la suscripción de envío debe tener el permiso iam.serviceAccounts.actAs en la cuenta de servicio administrada por el usuario para adjuntar la cuenta de servicio a la suscripción de envío. Para obtener más información, consulta Conecta cuentas de servicio a recursos.

• Permisos requeridos: A esta cuenta de servicio se le debe otorgar el permiso iam.serviceAccounts.getOpenIdToken (incluido en el rol roles/iam.serviceAccountTokenCreator) para permitir que Pub/Sub cree tokens de JWT para que la cuenta de servicio especificada autentique las solicitudes push.

Separación de la carga útil

La opción Habilitar la separación de la carga útil quita todos los metadatos de los mensajes de Pub/Sub, excepto los datos del mensaje. Con el desempaquetado de la carga útil, los datos del mensaje se entregan directamente como el cuerpo HTTP.

También puedes habilitar la opción Escribir metadatos. La opción Escribir metadatos agrega los metadatos del mensaje que se quitaron anteriormente al encabezado de la solicitud.

Propiedades de BigQuery

Cuando seleccionas el tipo de entrega de suscripción Escribir en BigQuery, puedes especificar las siguientes propiedades adicionales.

Usar el esquema de tema

Esta opción permite que Pub/Sub use el esquema del tema de Pub/Sub al que se adjunta la suscripción. Además, Pub/Sub escribe los campos de los mensajes en las columnas correspondientes de la tabla de BigQuery.

Cuando uses esta opción, recuerda verificar los siguientes requisitos adicionales:

• Los campos del esquema del tema y del esquema de BigQuery deben tener los mismos nombres, y sus tipos deben ser compatibles entre sí.

• Cualquier campo opcional en el esquema del tema también debe ser opcional en el esquema de BigQuery.

• Los campos obligatorios en el esquema del tema no tienen que ser obligatorios en el esquema de BigQuery.

• Si hay campos de BigQuery que no están presentes en el esquema del tema, estos campos de BigQuery deben estar en el modo NULLABLE.

• Si el esquema del tema tiene campos adicionales que no están presentes en el esquema de BigQuery y estos campos se pueden descartar, selecciona la opción Descartar campos desconocidos.

• Solo puedes seleccionar una de las propiedades de suscripción, Usar esquema de tema o Usar esquema de tabla.

Si no seleccionas la opción Usar el esquema de tema o Usar el esquema de tabla, asegúrate de que la tabla de BigQuery tenga una columna llamada data del tipo BYTES, STRING o JSON. Pub/Sub escribe el mensaje en esta columna de BigQuery.

Es posible que no veas los cambios en el esquema de temas de Pub/Sub o en el esquema de la tabla de BigQuery aplicarse de inmediato con los mensajes escritos en la tabla de BigQuery. Por ejemplo, si la opción Descartar campos desconocidos está habilitada y un campo está presente en el esquema de Pub/Sub, pero no en el esquema de BigQuery, es posible que los mensajes escritos en la tabla de BigQuery sigan sin contener el campo después de agregarlo al esquema de BigQuery. Finalmente, los esquemas se sincronizan y los mensajes posteriores incluyen el campo.

Cuando usas la opción Usar esquema de tema para tu suscripción a BigQuery, también puedes aprovechar la captura de datos modificados (CDC) de BigQuery. La CDC actualiza tus tablas de BigQuery procesando y aplicando cambios a las filas existentes.

Para obtener más información sobre esta función, consulta Transmite actualizaciones de tablas con captura de datos modificados.

Para obtener información sobre cómo usar esta función con las suscripciones de BigQuery, consulta Captura de datos modificados de BigQuery.

Usar el esquema de tabla

Esta opción permite que Pub/Sub use el esquema de la tabla de BigQuery para escribir los campos de un mensaje JSON en las columnas correspondientes. Cuando uses esta opción, recuerda verificar los siguientes requisitos adicionales:

• Los nombres de cada columna de la tabla de BigQuery solo deben contener letras (a-z, A-Z), números (0-9) o guiones bajos (_).

• Los mensajes publicados deben estar en formato JSON.

• Se admiten las siguientes conversiones de JSON:

  Tipo de JSON	Tipo de datos de BigQuery
  string	NUMERIC, BIGNUMERIC, DATE, TIME, DATETIME o TIMESTAMP
  number	NUMERIC, BIGNUMERIC, DATE, TIME, DATETIME o TIMESTAMP

  • Cuando se usan conversiones de number a DATE, DATETIME, TIME o TIMESTAMP, el número debe cumplir con las representaciones admitidas.
  • Cuando se usa la conversión de number a NUMERIC o BIGNUMERIC, la precisión y el rango de valores se limitan a los que acepta el estándar IEEE 754 para la aritmética de punto flotante. Si necesitas una alta precisión o un rango de valores más amplio, usa las conversiones de string a NUMERIC o BIGNUMERIC en su lugar.
  • Cuando se usan conversiones de string a NUMERIC o BIGNUMERIC, Pub/Sub supone que la cadena es un número legible por humanos (p.ej., "123.124"). Si falla el procesamiento de la cadena como un número legible por humanos, Pub/Sub trata la cadena como bytes codificados con BigDecimalByteStringEncoder.

• Si el tema de la suscripción tiene un esquema asociado, la propiedad de codificación del mensaje debe establecerse en JSON.

• Si hay campos de BigQuery que no están presentes en los mensajes, estos campos deben estar en el modo NULLABLE.

• Si los mensajes tienen campos adicionales que no están presentes en el esquema de BigQuery y estos campos se pueden descartar, selecciona la opción Descartar campos desconocidos.

• Solo puedes seleccionar una de las propiedades de suscripción, Usar esquema de tema o Usar esquema de tabla.

Si no seleccionas la opción Usar el esquema de tema o Usar el esquema de tabla, asegúrate de que la tabla de BigQuery tenga una columna llamada data del tipo BYTES, STRING o JSON. Pub/Sub escribe el mensaje en esta columna de BigQuery.

Es posible que no veas los cambios en el esquema de la tabla de BigQuery aplicarse de inmediato con los mensajes escritos en la tabla de BigQuery. Por ejemplo, si la opción Descartar campos desconocidos está habilitada y hay un campo presente en los mensajes, pero no en el esquema de BigQuery, es posible que los mensajes escritos en la tabla de BigQuery sigan sin contener el campo después de agregarlo al esquema de BigQuery. Con el tiempo, el esquema se sincroniza y los mensajes posteriores incluyen el campo.

Cuando usas la opción Usar esquema de tabla para tu suscripción a BigQuery, también puedes aprovechar la captura de datos modificados (CDC) de BigQuery. La CDC actualiza tus tablas de BigQuery procesando y aplicando cambios a las filas existentes.

Para obtener más información sobre esta función, consulta Transmite actualizaciones de tablas con captura de datos modificados.

Para obtener información sobre cómo usar esta función con las suscripciones de BigQuery, consulta Captura de datos modificados de BigQuery.

Quitar campos desconocidos

Esta opción se usa con las opciones Usar el esquema de tema o Usar el esquema de tabla. Cuando se habilita, esta opción permite que Pub/Sub descarte cualquier campo que esté presente en el esquema o mensaje del tema, pero no en el esquema de BigQuery. Los campos que no forman parte del esquema de BigQuery se descartan cuando se escribe el mensaje en la tabla de BigQuery.

Si no se configura la opción Descartar campos desconocidos, los mensajes con campos adicionales no se escriben en BigQuery y permanecen en las tareas pendientes de la suscripción, a menos que configures un tema de mensajes no entregados.

El parámetro de configuración Descartar campos desconocidos no afecta los campos que no están definidos en el esquema de tema de Pub/Sub ni en el esquema de tabla de BigQuery. En este caso, se entrega un mensaje de Pub/Sub válido a la suscripción. Sin embargo, como BigQuery no tiene columnas definidas para estos campos adicionales, se descartan durante el proceso de escritura de BigQuery. Para evitar este comportamiento, asegúrate de que todos los campos incluidos en el mensaje de Pub/Sub también estén incluidos en el esquema de la tabla de BigQuery.

El comportamiento en relación con los campos adicionales también puede depender del tipo de esquema específico (Avro, búfer de protocolo) y la codificación (JSON, binaria) que se usen. Para obtener información sobre cómo estos factores afectan el manejo de campos adicionales, consulta la documentación de tu tipo de esquema y codificación específicos.

Escribir metadatos

Esta opción permite que Pub/Sub escriba los metadatos de cada mensaje en columnas adicionales de la tabla de BigQuery. De lo contrario, los metadatos no se escriben en la tabla de BigQuery.

Si seleccionas la opción Escribir metadatos, asegúrate de que la tabla de BigQuery tenga los campos que se describen en la siguiente tabla.

Si no seleccionas la opción Escribir metadatos, la tabla de BigQuery de destino solo requiere el campo data, a menos que use_topic_schema sea verdadero. Si seleccionas las opciones Escribir metadatos y Usar esquema del tema, el esquema del tema no debe contener ningún campo con nombres que coincidan con los de los parámetros de metadatos. Esta limitación incluye las versiones en camel case de estos parámetros en snake case.

Parámetros
subscription_name	STRING Es el nombre de una suscripción.
message_id	STRING ID de un mensaje
publish_time	TIMESTAMP Es la fecha y hora de publicación de un mensaje.
data	BYTES, STRING o JSON Es el cuerpo del mensaje. El campo data es obligatorio para todas las tablas de BigQuery de destino que no seleccionan Usar esquema de tema o Usar esquema de tabla. Si el campo es de tipo JSON, el cuerpo del mensaje debe ser un formato JSON válido.
attributes	STRING o JSON Es un objeto JSON que contiene todos los atributos del mensaje. También contiene campos adicionales que forman parte del mensaje de Pub/Sub, incluida la clave de orden, si está presente.

Propiedades de Cloud Storage

Cuando seleccionas un tipo de entrega de suscripción como Escribir en Cloud Storage, puedes especificar las siguientes propiedades adicionales.

Nombre del bucket

Ya debe existir un bucket de Cloud Storage antes de que crees una suscripción de Cloud Storage.

Los mensajes se envían en lotes y se almacenan en el bucket de Cloud Storage. Un solo lote o archivo se almacena como un objeto en el bucket.

El bucket de Cloud Storage debe tener inhabilitada la opción Pagos del solicitante.

Para crear un bucket de Cloud Storage, consulta Crea buckets.

Prefijo, sufijo y fecha y hora del nombre de archivo

Los archivos de salida de Cloud Storage que genera la suscripción a Cloud Storage se almacenan como objetos en el bucket de Cloud Storage. El nombre del objeto almacenado en el bucket de Cloud Storage tiene el siguiente formato: <file-prefix><UTC-date-time>_<uuid><file-suffix>.

En la siguiente lista, se incluyen detalles sobre el formato del archivo y los campos que puedes personalizar:

• <file-prefix> es el prefijo del nombre de archivo personalizado. Este paso es opcional,

• <UTC-date-time> es una cadena personalizable que se genera automáticamente en función de la hora en que se crea el objeto.

• <uuid> es una cadena aleatoria generada automáticamente para el objeto.

• <file-suffix> es el sufijo del nombre de archivo personalizado. Este paso es opcional, El sufijo del nombre de archivo no puede terminar en "/".

• Puedes cambiar el prefijo y el sufijo del nombre de archivo:

  • Por ejemplo, si el valor del prefijo del nombre de archivo es prod_ y el valor del sufijo del nombre de archivo es _archive, un nombre de objeto de muestra es prod_2023-09-25T04:10:00+00:00_uN1QuE_archive.

  • Si no especificas el prefijo y el sufijo del nombre de archivo, el nombre del objeto almacenado en el bucket de Cloud Storage tendrá el siguiente formato: <UTC-date-time>_<uuid>.

  • Los requisitos para nombrar objetos de Cloud Storage también se aplican al prefijo y al sufijo del nombre de archivo. Para obtener más información, consulta Acerca de los objetos de Cloud Storage.

• Puedes cambiar la forma en que se muestran la fecha y la hora en el nombre del archivo:

  • Se requieren comparadores de fecha y hora que puedes usar solo una vez: año (YYYY o YY), mes (MM), día (DD), hora (hh), minuto (mm) y segundo (ss). Por ejemplo, YY-YYYY o MMM no son válidos.

  • Coincidencias opcionales que puedes usar solo una vez: separador de fecha y hora (T) y compensación de zona horaria (Z o +00:00).

  • Elementos opcionales que puedes usar varias veces: guion (-), guion bajo (_), dos puntos (:) y barra diagonal (/).

  • Por ejemplo, si el valor del formato de fecha y hora del nombre de archivo es YYYY-MM-DD/hh_mm_ssZ, un nombre de objeto de muestra es prod_2023-09-25/04_10_00Z_uNiQuE_archive.

  • Si el formato de fecha y hora del nombre de archivo termina con un carácter que no es un comparador, ese carácter reemplazará el separador entre <UTC-date-time> y <uuid>. Por ejemplo, si el valor del formato de fecha y hora del nombre de archivo es YYYY-MM-DDThh_mm_ss-, un nombre de objeto de muestra es prod_2023-09-25T04_10_00-uNiQuE_archive.

Procesamiento de archivos por lotes

Las suscripciones a Cloud Storage te permiten decidir cuándo quieres crear un archivo de salida nuevo que se almacene como un objeto en el bucket de Cloud Storage. Pub/Sub escribe un archivo de salida cuando se cumple una de las condiciones de procesamiento por lotes especificadas. A continuación, se indican las condiciones de procesamiento por lotes de Cloud Storage:

• Es la duración máxima del lote de almacenamiento. Este parámetro de configuración es obligatorio. La suscripción de Cloud Storage escribe un nuevo archivo de salida si se supera el valor especificado de duración máxima. Si no especificas el valor, se aplica un valor predeterminado de 5 minutos. Los siguientes son los valores aplicables para la duración máxima:

  • El valor mínimo es 1 minuto.
  • Valor predeterminado = 5 minutos
  • Valor máximo = 10 minutos

• Cantidad máxima de bytes por lote de almacenamiento. Este es un parámetro de configuración opcional. La suscripción de Cloud Storage escribe un nuevo archivo de salida si se supera el valor especificado de bytes máximos. Los siguientes son los valores aplicables para los bytes máximos:

  • Valor mínimo = 1 KB
  • El valor máximo es 10 GiB.

• Cantidad máxima de mensajes por lote de almacenamiento. Este es un parámetro de configuración opcional. La suscripción de Cloud Storage escribe un nuevo archivo de salida si se supera la cantidad especificada de mensajes máximos. Estos son los valores aplicables para la cantidad máxima de mensajes:

  • Valor mínimo = 1,000

Por ejemplo, puedes configurar la duración máxima en 6 minutos y los bytes máximos en 2 GB. Si, en el minuto 4, el archivo de salida alcanza un tamaño de 2 GB, Pub/Sub finaliza el archivo anterior y comienza a escribir en uno nuevo.

Una suscripción a Cloud Storage puede escribir en varios archivos de un bucket de Cloud Storage de forma simultánea. Si configuraste tu suscripción para que se cree un archivo nuevo cada 6 minutos, es posible que observes que se crean varios archivos de Cloud Storage cada 6 minutos.

En algunas situaciones, es posible que Pub/Sub comience a escribir en un archivo nuevo antes de la hora configurada por las condiciones de procesamiento por lotes de archivos. Un archivo también puede superar el valor de Max bytes si la suscripción recibe mensajes más grandes que ese valor.

Formato de archivo

Cuando creas una suscripción a Cloud Storage, puedes especificar el formato de los archivos de salida que se almacenarán en un bucket de Cloud Storage como Texto o Avro.

• Texto: Los mensajes se almacenan como texto sin formato. Un carácter de salto de línea separa un mensaje del mensaje anterior en el archivo. Solo se almacenan las cargas útiles de los mensajes, no los atributos ni otros metadatos.

• Avro: Los mensajes se almacenan en formato binario de Apache Avro. Cuando seleccionas Avro, puedes habilitar las siguientes propiedades adicionales:

  • Escribir metadatos: Esta opción te permite almacenar los metadatos del mensaje junto con el mensaje. Los metadatos, como los campos subscription_name, message_id, publish_time y attributes, se escriben en los campos de nivel superior del objeto Avro de salida, mientras que todas las demás propiedades del mensaje que no son datos (por ejemplo, un ordering_key, si está presente) se agregan como entradas en el mapa attributes.

    Si la opción Escribir metadatos está inhabilitada, solo se escribirá la carga útil del mensaje en el objeto Avro de salida. Este es el esquema de Avro para los mensajes de salida con los metadatos de escritura inhabilitados:

    {
      "type": "record",
      "namespace": "com.google.pubsub",
      "name": "PubsubMessage",
      "fields": [
        { "name": "data", "type": "bytes" }
      ]
    }
    

    Este es el esquema de Avro para los mensajes de salida con los metadatos de escritura habilitados:

    {
      "type": "record",
      "namespace": "com.google.pubsub",
      "name": "PubsubMessageWithMetadata",
      "fields": [
        { "name": "subscription_name", "type": "string" },
        { "name": "message_id", "type": "string"  },
        { "name": "publish_time", "type": {
            "type": "long",
            "logicalType": "timestamp-micros"
          }
        },
        { "name": "attributes", "type": { "type": "map", "values": "string" } },
        { "name": "data", "type": "bytes" }
      ]
    }
    

  • Usar el esquema de tema: Esta opción permite que Pub/Sub use el esquema del tema de Pub/Sub al que se adjunta la suscripción cuando escribe archivos Avro.

    Cuando uses esta opción, recuerda verificar los siguientes requisitos adicionales:

    • El esquema del tema debe estar en formato Apache Avro.

    • Si se habilitan use topic schema y write metadata, el esquema de tema debe tener un objeto Record en su raíz. Pub/Sub expandirá la lista de campos del registro para incluir los campos de metadatos. Como resultado, el registro no puede contener ningún campo con el mismo nombre que los campos de metadatos (subscription_name, message_id, publish_time o attributes).

Cuenta de servicio

Tienes las siguientes opciones para escribir mensajes en una tabla de BigQuery o un bucket de Cloud Storage:

• Configura una cuenta de servicio personalizada para que solo los usuarios que tengan el permiso iam.serviceAccounts.actAs en la cuenta de servicio puedan crear una suscripción que escriba en la tabla o el bucket. Un ejemplo de rol que incluye el permiso iam.serviceAccounts.actAs es el rol de usuario de cuenta de servicio (roles/iam.serviceAccountUser).

• Usa el agente de servicio de Pub/Sub predeterminado que permite que cualquier usuario con la capacidad de crear suscripciones en el proyecto cree una suscripción que escriba en la tabla o el bucket. El agente de servicio de Pub/Sub es el parámetro de configuración predeterminado cuando no especificas una cuenta de servicio personalizada.

¿Qué sigue?

• Crea una suscripción de extracción.
• Crea una suscripción de envío.
• Crea una suscripción a BigQuery.
• Crea una suscripción a Cloud Storage.