Notificaciones de Pub/Sub

Una vez que hayas completado una transferencia del servicio de transferencia de Storage, puede que quieras iniciar otra tarea, gestionar un error que se haya producido durante una transferencia o registrar que se ha producido una transferencia. Pub/Sub proporciona una cola a la que se suscriben tus programas para recibir mensajes cuando se completa una transferencia. De esta forma, puedes reutilizar el código y programar los pasos siguientes en función del estado de una transferencia.

Para obtener más información sobre Pub/Sub, consulta ¿Qué es Cloud Pub/Sub?

Requisitos previos

Para poder usar esta función, haz lo siguiente:

1. Habilite la API Pub/Sub en el proyecto que recibe las notificaciones de Pub/Sub.

   Habilitar la API

2. Tener un tema de Pub/Sub al que quieras enviar notificaciones.

3. Obtén la dirección de correo de la cuenta de servicio asociada al proyecto que contiene tu cubo de Storage Transfer Service.

   1. Concede a la cuenta de servicio el rol de gestión de identidades y accesos roles.pubsub.publisher del tema de Pub/Sub que quieras.

Configurar los ajustes de notificaciones

Para configurar los ajustes de notificaciones de Pub/Sub del Servicio de transferencia de Storage, debes usar la API transferJobs del Servicio de transferencia de Storage para crear un mensaje NotificationConfig. El tema recibirá notificaciones en el canal de Pub/Sub configurado.

Especifica lo siguiente en tu mensaje NotificationConfig:

• Tema de Pub/Sub al que se enviarán las notificaciones.
• El formato del mensaje, "JSON" o "NONE"

• Los tipos de eventos que quieras, correspondientes a completado TransferOperation.Statuses:

  • "TRANSFER_OPERATION_SUCCESS"
  • "TRANSFER_OPERATION_FAILED"
  • "TRANSFER_OPERATION_ABORTED"

A continuación, se muestra un ejemplo de mensaje NotificationConfig:

{
   ...
   "notificationConfig": {
     "pubsubTopic": "projects/project-id/topics/topic-id",
     "eventTypes": ["TRANSFER_OPERATION_SUCCESS"],
     "payloadFormat": "JSON"
   },
   ...
}

Haz los cambios siguientes:

• project-id: el ID de proyecto de la transferencia Google Cloud
• topic-id: el nombre del tema de Pub/Sub

Para obtener más información, consulta la especificación REST de Pub/Sub del Servicio de transferencia de Storage.

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 el Servicio de transferencia de 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:

Consulta PubsubMessage para obtener más información sobre el formato de los mensajes de Pub/Sub.

Carga útil

La carga útil contiene los metadatos TransferOperation. Cuando creas una configuración de notificaciones, 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:

Ejemplos de configuraciones de notificaciones de Pub/Sub

Notificaciones solo de transferencias fallidas

Para recibir mensajes solo de las transferencias fallidas, envía una TransferJob con un NotificationConfig que filtre solo las transferencias fallidas:

// REST JSON format:
//   https://cloud.google.com/storage-transfer/docs/create-manage-transfer-program
{
   ...
   "notificationConfig": {
     "pubsubTopic": "projects/project-id/topics/topic-id",
     "eventTypes": ["TRANSFER_OPERATION_FAILED"],
     "payloadFormat: "JSON"
   },
   ...
}

Haz los cambios siguientes:

• project-id: el ID de proyecto de la transferencia Google Cloud
• topic-id: el nombre del tema de Pub/Sub

Notificar todas las transferencias completadas

Para recibir notificaciones de todas las transferencias completadas, independientemente de su estado, envíe una TransferJob con un NotificationConfig sin filtros EventType:

// REST JSON format:
//   https://cloud.google.com/storage-transfer/docs/create-manage-transfer-program
{
   ...
   "notificationConfig": {
     "pubsubTopic": "projects/project-id/topics/topic-id",
     "payloadFormat: "JSON"
   },
   ...
}

Haz los cambios siguientes:

• project-id: el ID de proyecto de la transferencia Google Cloud
• topic-id: el nombre del tema de Pub/Sub

Realizar acciones arbitrarias en una transferencia

Para realizar una acción arbitraria, crea una notificación de Pub/Sub mediante una función de Cloud con un activador de Pub/Sub emparejada con una función de Cloud en segundo plano. Para obtener más información, consulta el tutorial de Cloud Pub/Sub.

Entre los ejemplos de acciones arbitrarias se incluyen los siguientes:

• Enviar un correo
• Iniciar una tarea de Dataflow
• Registrar metadatos en Cloud SQL
• Metadatos de grabación en Spanner

Garantías de entrega

El Servicio de transferencia de Storage envía notificaciones de cualquier TransferOperations que se inicie después de que añadas una configuración de notificaciones y garantiza que Pub/Sub recibirá las notificaciones al menos una vez. Pub/Sub también ofrece la entrega al menos una vez al destinatario, lo que significa que puedes recibir varios mensajes con varios IDs que representan el mismo evento de Storage Transfer Service.

No se garantiza que las notificaciones se publiquen en el orden en que las recibe Pub/Sub.

Si una notificación no se puede enviar a un tema de Pub/Sub de forma constante, el Servicio de transferencia de 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 el servicio de transferencia de Storage ya no tiene permiso para publicar en el tema o cuando el proyecto propietario del tema supera su cuota de publicación.