Notificaciones de Pub/Sub para Cloud Storage

Configuración

En esta página, se proporciona una descripción general de las notificaciones de Pub/Sub para Cloud Storage.

Descripción general

Las notificaciones de Pub/Sub envían información a Pub/Sub sobre los cambios en los objetos de los depósitos y, luego, la información se agrega a un tema de Pub/Sub que elijas en forma de mensajes. Por ejemplo, puedes hacer un seguimiento de los objetos que se crean y borran en el bucket. Cada notificación contiene información que describe el evento que la activó y el objeto que cambió.

Puedes enviar notificaciones a cualquier tema de Pub/Sub en cualquier proyecto para el que tengas los permisos requeridos. Una vez que el tema de Pub/Sub recibe una notificación, los suscriptores del tema pueden recibir el mensaje asociado. Consulta los Requisitos previos para obtener información sobre cómo conectar tus buckets de Cloud Storage con un tema de Pub/Sub.

Otras opciones de notificación

Suscribirse a las notificaciones de Pub/Sub es una forma versátil de activar alertas y acciones en respuesta a los cambios en un bucket. También están disponibles las siguientes opciones:

  • Cloud Functions: Si solo deseas activar una función autónoma y ligera en respuesta a los eventos y no quieres administrar un tema de Pub/Sub, usa Cloud Functions. Cloud Functions te permite ejecutar funciones de C#, Go, Java, Node.js, Python, PHP y Ruby cuando cambia un objeto de tu bucket. Ten en cuenta que tu bucket debe residir en el mismo proyecto que Cloud Functions. Consulta el instructivo asociado para ver una demostración del uso de Cloud Functions con Cloud Storage.

  • Notificación de cambio de objeto: esta es una característica aparte más antigua dentro de Cloud Storage para generar notificaciones. Esta función envía mensajes HTTPS a una aplicación cliente que debes configurar por separado. En general, esta función no se recomienda, porque las notificaciones de Pub/Sub son más económicas, fáciles de usar y flexibles.

Configuraciones de notificación

Una configuración de notificación es una regla que se adjunta a un bucket y especifica lo siguiente:

  • El tema de Cloud Pub/Sub que recibe notificaciones
  • Los eventos que activan el envío de una notificación
  • La información que contienen las notificaciones

Puedes adjuntar múltiples configuraciones de notificación a un bucket. Un bucket puede tener un total de hasta 100 configuraciones de notificación y hasta 10 configuraciones de notificación establecidas con el fin de activarse para un evento específico.

Por ejemplo, si tienes una configuración de notificaciones que envía notificaciones de eliminación a un tema de Pub/Sub, puedes agregar una segunda configuración de notificaciones al bucket que envía notificaciones de eliminación a otro tema. Sin embargo, si intentas crear más de 10 configuraciones de notificaciones que hagan esto, recibirás un error. También puedes crear configuraciones de notificaciones que envíen notificaciones para otros eventos, como la creación de objetos, ya sea a los temas de Pub/Sub que usan las notificaciones de eliminación o a temas distintos.

Cada configuración de notificaciones se identifica mediante un número entero. Este número entero se muestra en los siguientes casos:

  • Cuando creas la configuración de notificaciones
  • Cuando se enumeran las configuraciones de notificaciones adjuntas a un bucket
  • En el atributo notificationConfig de cada notificación activada por la configuración de notificaciones

Crear y borrar configuraciones de notificación aumenta el número de metageneración de un depósito.

Tipos de eventos

La siguiente es una lista de los tipos de eventos que admite Cloud Storage:

Tipo de evento Descripción
OBJECT_FINALIZE Se envía cuando un nuevo objeto (o una nueva generación de un objeto existente) se crea con éxito en el bucket. Incluye la copia o la reescritura de un objeto existente. Una carga con errores no activa este evento.
OBJECT_METADATA_UPDATE Se envía cuando cambian los metadatos de un objeto existente.
OBJECT_DELETE Se envía cuando un objeto se borra de forma permanente. Incluye los objetos que se reemplazan o se borran según la configuración del ciclo de vida del bucket. Esto no incluye los objetos que se vuelven no actuales (consulta OBJECT_ARCHIVE) o las cargas multiparte anuladas.
OBJECT_ARCHIVE Solo se envía cuando un depósito tiene habilitado el control de versiones de objetos. Este evento señala que la versión publicada de un objeto se convirtió en una versión no actual, ya sea porque se la convirtió en no actual de forma explícita o porque se reemplazó cuando se subió un objeto con el mismo nombre.

Para otros eventos de Cloud Storage, como las operaciones de bucket o la lectura de objetos, puedes habilitar el tipo de registro de auditoría apropiado en los Registros de auditoría de Cloud y enrutar los registros de auditoría a Pub/Sub mediante un filtro.

Reemplaza objetos

Reemplazar un objeto existente por uno nuevo con el mismo nombre activa dos eventos separados: OBJECT_FINALIZE para la versión nueva del objeto y OBJECT_ARCHIVE o OBJECT_DELETE para el objeto que se reemplazó. El evento OBJECT_FINALIZE contiene un atributo adicional overwroteGeneration, que proporciona el número de generación del objeto que se reemplazó. Los eventos OBJECT_ARCHIVE o OBJECT_DELETE contienen un atributo adicional overwrittenByGeneration, que proporciona el número de generación del objeto nuevo.

Formato de las notificaciones

Las notificaciones enviadas al tema de Pub/Sub constan de dos partes:

  • Atributos: Un conjunto de pares clave-valor que describen el evento
  • Carga útil: Una string que contiene los metadatos del objeto modificado

Atributos

Los atributos son pares clave-valor contenidos en todas las notificaciones que Cloud Storage envía a tu tema de Pub/Sub. Las notificaciones siempre contienen el siguiente conjunto de pares clave-valor, sin importar la carga útil de la notificación:

Nombre del atributo Ejemplo Descripción
notificationConfig projects/_/buckets/foo/notificationConfigs/3 Un identificador para la configuración de notificación que activó esta notificación.
eventType OBJECT_FINALIZE El tipo de evento que acaba de ocurrir. Consulta Tipos de eventos para obtener una lista de valores posibles.
payloadFormat JSON_API_V1 El formato de la carga útil del objeto. Consulta Carga útil para obtener una lista de valores posibles.
bucketId foo El nombre del bucket que contiene el objeto modificado.
objectId bar El nombre del objeto modificado.
objectGeneration 123456 El número de generación del objeto modificado.
eventTime 2021-01-15T01:30:15.01Z La hora en que ocurrió el evento, expresada en formato RFC 3339.

Las notificaciones a veces contienen el siguiente conjunto de pares clave-valor, sin importar la carga útil de la notificación:

Nombre del atributo Ejemplo Descripción
overwrittenByGeneration 107458 El número de generación del objeto nuevo que reemplazó al que activó esta notificación. Este atributo solo aparece en los eventos OBJECT_ARCHIVE o OBJECT_DELETE en caso de reemplazo.
overwroteGeneration 352947 El número de generación del objeto que se reemplazó por el que activó esta notificación. Este atributo solo aparece en los eventos OBJECT_FINALIZE en caso de reemplazo.

Además de los atributos anteriores, una configuración de notificación puede contener hasta 10 atributos personalizados. Los atributos personalizados se definen cuando creas una configuración de notificación, con el comando --custom-attributes en un comando gcloud storage o el objeto custom_attributes en el cuerpo de una solicitud de JSON POST notificationConfigs.

Carga útil

La carga útil es una string que contiene los metadatos del objeto modificado. Cuando creas una configuración de notificaciones, debes especificar un tipo de carga útil para incluirla en las notificaciones que activa esa configuración. Puedes especificar los siguientes tipos de carga útil:

Tipo de carga útil Descripción
NINGUNO No se incluye ninguna carga útil en la notificación.
JSON_API_V1 La carga útil será una string UTF-8 que contendrá la representación de recursos de los metadatos del objeto.

Para las notificaciones OBJECT_DELETE, los metadatos que contiene la carga útil representan los metadatos del objeto como estaban antes de la eliminación, junto con una propiedad adicional timeDeleted. Para todas las demás notificaciones, los metadatos incluidos en la carga útil representan los metadatos del objeto después de la modificación.

Por ejemplo, supongamos que tienes una configuración de notificaciones que realiza un seguimiento de los eventos OBJECT_METADATA_UPDATE. Si un usuario cambia la propiedad contentType de un objeto de binary/octet-stream a video/mp4, se envía una notificación OBJECT_METADATA_UPDATE y los metadatos en la carga útil incluyen "contentType":"video/mp4".

Garantías de entrega

Cuando agregas una configuración de notificaciones, Cloud Storage puede tardar hasta 30 segundos en comenzar a enviar las notificaciones asociadas. Una vez que comienza, Cloud Storage garantiza la entrega al menos una vez a Pub/Sub. Pub/Sub también ofrece entrega al menos una vez al destinatario, lo que significa que podrías recibir múltiples mensajes, con múltiples ID, que representan el mismo evento de Cloud Storage.

No se garantiza que las notificaciones se publiquen en el orden en que Pub/Sub las recibe. Si planeas modificar el objeto de Cloud Storage en función de una notificación, se recomienda que uses los números de generación y metageneración del objeto como condiciones previas en tu solicitud de actualización.

Si una notificación sigue sin poder entregarse a un tema de Pub/Sub de forma coherente, Cloud Storage podría borrarla después de 7 días. El error en la entrega puede ocurrir cuando el tema de Pub/Sub ya no existe, cuando Cloud Storage ya no tiene permiso para publicar en el tema o cuando el proyecto que posee el tema supera su cuota de publicación.

¿Qué sigue?