Notificaciones de Cloud Pub/Sub para Cloud Storage

En esta página, se proporciona una descripción general de las notificaciones de Cloud Pub/Sub para Cloud Storage. Para obtener información sobre cómo configurar y usar las notificaciones de Cloud Pub/Sub, consulta Registra cambios en los objetos.

Descripción general

Las notificaciones de Cloud Pub/Sub envían información sobre los cambios en los objetos de tus depósitos a Cloud Pub/Sub, en el que la información se agrega a un tema de Cloud Pub/Sub que elijas en forma de mensajes. Por ejemplo, puedes hacer un seguimiento de los objetos que se crean y borran en tu depósito. 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 Cloud Pub/Sub en cualquier proyecto para el que tengas los permisos requeridos. Una vez que el tema de Cloud Pub/Sub recibe una notificación, el mensaje resultante se puede enviar a cualquier número de suscriptores del tema. Consulta los Requisitos previos para obtener información sobre cómo conectar tus depósitos de Cloud Storage con un tema de Cloud Pub/Sub.

Otras opciones de notificación

Suscribirse a las notificaciones de Cloud Pub/Sub es una forma versátil de activar alertas y acciones en respuesta a los cambios en un depósito. 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 Cloud Pub/Sub, usa Cloud Functions. Cloud Functions te permite ejecutar funciones de JavaScript cuando se modifica un objeto en tu depósito. Ten en cuenta que tus depósitos deben 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 característica envía mensajes HTTPS a una aplicación cliente que debes configurar por separado. En general, las notificaciones de Cloud Pub/Sub son más baratas, fáciles de usar y flexibles.

Configuraciones de notificación

Una configuración de notificación es una regla que se adjunta a un depósito 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 depósito. Para cada evento, se pueden establecer hasta 10 configuraciones de notificación a fin de que una notificación se active.

Por ejemplo, si tienes una configuración de notificaciones que envía notificaciones de eliminación a un tema de Cloud Pub/Sub, puedes agregar una segunda configuración de notificaciones al depósito 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 Cloud 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 depósito
  • En el atributo notificationConfig de cada notificación que activa la configuración de notificaciones

Crear y borrar configuraciones de notificaciones 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 en la actualidad:

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 depósito. Incluye la copia y 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 sobrescriben o que se borran según la configuración del ciclo de vida del depósito. En el caso de los depósitos que tienen habilitado el control de versiones de objetos, esto no se envía cuando se archiva un objeto (consulta OBJECT_ARCHIVE), incluso si el archivado se produce mediante el método storage.objects.delete.
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 archivada, ya sea porque se la archivó o porque se reemplazó cuando se subió un objeto con el mismo nombre.

Reemplaza objetos

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

Formato de las notificaciones

Las notificaciones enviadas al tema de Cloud 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 Cloud 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 depósito que contiene el objeto modificado.
objectId bar El nombre del objeto modificado.
objectGeneration 123456 El número de generación del objeto modificado.

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 u 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.

El siguiente par clave-valor está obsoleto. No aparece en las suscripciones nuevas y no aparecerá en ninguna suscripción después del 1 de junio de 2018:

Nombre del atributo Ejemplo Descripción
recurso projects/_/buckets/foo/objects/bar#123456 La ruta de acceso al objeto de Cloud Storage modificado.

Además de los atributos anteriores, las notificaciones pueden contener atributos personalizados. Estos atributos se definen cuando se crea una configuración de notificaciones con la marca -m en un comando gsutil notification o el objeto custom_attributes en el cuerpo de una solicitud 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 contenidos en la carga útil representan los metadatos del objeto tal como eran antes de borrarlo, junto con una propiedad timeDeleted adicional. 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 Cloud Pub/Sub. Cloud 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. En la actualidad no hay un ANS para el tiempo de entrega, pero las notificaciones, por lo general, se envían en segundos. En raras ocasiones las notificaciones podrían demorarse bastante más.

No se garantiza que las notificaciones se publiquen en el orden en que Cloud 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 Cloud Pub/Sub, Cloud Storage podría borrarla después de 7 días. El error en la entrega puede ocurrir cuando el tema de Cloud 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.

Pasos siguientes

¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

¿Necesitas ayuda? Visita nuestra página de asistencia.