Notificaciones de Pub/Sub para Cloud Storage

Configuración

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

Información general

Las notificaciones de Pub/Sub envían información sobre los cambios realizados en los objetos de tus segmentos a Pub/Sub, donde se añade a un tema de Pub/Sub que elijas en forma de mensajes. Por ejemplo, puedes monitorizar los objetos que se crean y eliminan en tu segmento. Cada notificación contiene información que describe tanto el evento que la ha activado como el objeto que ha cambiado.

Puedes enviar notificaciones a cualquier tema de Pub/Sub de cualquier proyecto para el que tengas permisos suficientes. Una vez que el tema de Pub/Sub lo recibe, los suscriptores del tema pueden recibir el mensaje asociado. Consulta los requisitos previos para obtener información sobre cómo conectar tus segmentos de Cloud Storage a 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 contenedor. También están disponibles las siguientes opciones:

  • Cloud Run Functions: si solo quieres activar una función ligera e independiente en respuesta a eventos y no quieres gestionar un tema de Pub/Sub, usa Cloud Run Functions. Las funciones de Cloud Run te permiten ejecutar funciones de C#, Go, Java, Node.js, Python, PHP y Ruby cuando cambia un objeto de tu contenedor. Ten en cuenta que tu segmento debe estar en el mismo proyecto que las funciones de Cloud Run. Consulta el tutorial asociado para ver una demostración de cómo usar funciones de Cloud Run con Cloud Storage.

Configuraciones de notificaciones

Una configuración de notificaciones es una regla que asocias a un contenedor y que especifica lo siguiente:

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

Puede adjuntar varias configuraciones de notificaciones a un segmento. Un segmento puede tener un máximo de 100 configuraciones de notificaciones y hasta 10 configuraciones de notificaciones que se activen con un evento concreto.

Por ejemplo, si tiene una configuración de notificación que envía notificaciones de eliminación a un tema de Pub/Sub, puede añadir una segunda configuración de notificación al segmento que envíe 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. Además de estas configuraciones de notificaciones, también puedes crear configuraciones de notificaciones que envíen notificaciones de otros eventos, como la creación de objetos, a temas de Pub/Sub utilizados por las notificaciones de eliminación o a temas diferentes.

Cada configuración de notificaciones se identifica con un número entero. Se devuelve este número entero:

  • Cuando creas la configuración de la notificación.
  • Cuando enumeras las configuraciones de notificación asociadas a un contenedor.
  • En el atributo notificationConfig de cada notificación activada por la configuración de notificaciones.

Al crear y eliminar configuraciones de notificaciones, se incrementa el número de metageneración de un contenedor.

Tipos de eventos

A continuación, se muestra una lista de los tipos de eventos admitidos por Cloud Storage:

Tipo de evento Descripción
OBJECT_FINALIZE Se envía cuando se crea correctamente un objeto o una generación de un objeto ya disponible en el segmento. También se envía si el objeto se copia, se reescribe o se restaura. Este evento no se activa si la subida no llega a completarse.
OBJECT_METADATA_UPDATE Se envía cuando cambian los metadatos de un objeto.
OBJECT_DELETE Se envía cuando un objeto se ha eliminado de forma permanente, ya sea porque se ha sustituido o se ha eliminado a consecuencia de la configuración del ciclo de vida del segmento. No se incluyen los objetos que dejan de estar vigentes (consulta OBJECT_ARCHIVE) ni las subidas multiparte canceladas.
OBJECT_ARCHIVE Solo se envía cuando un segmento ha habilitado la gestión de versiones de objetos. Indica que la versión activa de un objeto se ha convertido en una versión no actual, ya sea porque se ha convertido explícitamente en una versión no actual o porque se ha sustituido al cargar un objeto con el mismo nombre.

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

Sustituir objetos

Si sustituyes un objeto por otro con el mismo nombre, se activarán dos eventos independientes: OBJECT_FINALIZE para la nueva versión del objeto y OBJECT_ARCHIVE o OBJECT_DELETE para el objeto sustituido. El evento OBJECT_FINALIZE contiene un atributo adicional, overwroteGeneration, que proporciona el número de generación del objeto que se ha sustituido. El evento OBJECT_ARCHIVE o OBJECT_DELETE contiene 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 Pub/Sub constan de dos partes:

  • Atributos: un conjunto de pares clave/valor que describen el evento.
  • Carga útil: cadena que contiene los metadatos del objeto modificado.

Atributos

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

Nombre de atributo Ejemplo Descripción
notificationConfig projects/_/buckets/foo/notificationConfigs/3 Identificador de la configuración de notificaciones que ha activado esta notificación.
eventType OBJECT_FINALIZE El tipo de evento que acaba de producirse Consulta Tipos de eventos para ver una lista de los valores posibles.
payloadFormat JSON_API_V1 El formato de la carga útil del objeto. Consulta Carga útil para ver una lista de los valores posibles.
bucketId foo Nombre del segmento que contiene el objeto modificado.
objectId bar Nombre del objeto modificado.
objectGeneration 123456 Número de generación del objeto modificado.
eventTime 2021-01-15T01:30:15.01Z La hora en la que se produjo el evento, expresada en formato RFC 3339.

En ocasiones, las notificaciones contienen el siguiente conjunto de pares clave-valor, independientemente de la carga útil de la notificación:

Nombre de atributo Ejemplo Descripción
overwrittenByGeneration 107458 Número de generación del objeto que ha sustituido al objeto al que hace referencia esta notificación. Este atributo solo aparece en los eventos OBJECT_ARCHIVE o OBJECT_DELETE en caso de sustitución.
overwroteGeneration 352947 Número de generación del objeto que se ha sustituido por el objeto al que hace referencia esta notificación. Este atributo solo aparece en los eventos OBJECT_FINALIZE en caso de sustitución.

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

Carga útil

La carga útil es una cadena que contiene los metadatos del objeto modificado. Cuando creas una configuración de notificación, especificas un tipo de carga útil que se incluirá en las notificaciones activadas por esa configuración. Puede especificar los siguientes tipos de carga útil:

Tipo de carga útil Descripción
NONE No se incluye ninguna carga útil en la notificación.
JSON_API_V1 La carga útil será una cadena UTF-8 que contenga la representación de recurso de los metadatos del objeto.

En el caso de las notificaciones OBJECT_DELETE, los metadatos incluidos en la carga útil representan los metadatos del objeto tal como estaban antes de la eliminación, junto con una propiedad timeDeleted adicional. En el resto de las notificaciones, los metadatos incluidos en la carga útil representan los metadatos del objeto después de que se produzca el cambio.

Por ejemplo, supongamos que tiene una configuración de notificaciones que monitoriza 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 de la carga útil incluyen "contentType":"video/mp4".

Garantías de entrega

Cuando añades una configuración de notificaciones, Cloud Storage puede tardar hasta 30 segundos en empezar a enviar las notificaciones asociadas. Una vez iniciada, Cloud Storage garantiza al menos una entrega a Pub/Sub. Pub/Sub también ofrece al menos una entrega al destinatario, lo que significa que puedes recibir varios mensajes, con varios IDs, que representan el mismo evento de Cloud Storage.

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

Si una notificación no se puede enviar de forma constante a un tema de Pub/Sub, Cloud Storage puede eliminarla al cabo de 7 días. Los errores de entrega pueden producirse 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 propietario del tema supera su cuota de publicación.

Siguientes pasos