Notificaciones de Pub/Sub

Después de completar una transferencia del Servicio de transferencia de almacenamiento, es posible que desees iniciar otra tarea, manejar un error encontrado durante una transferencia o registrar que se produjo una transferencia. Pub/Sub proporciona una cola a la que sus programas se suscriben para recibir mensajes cuando se completa una transferencia. Esto te permite reutilizar el código y programar los siguientes pasos 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

Antes de poder usar esta función, haz lo siguiente:

Habilita la API de Pub/Sub para el proyecto que recibe notificaciones de Pub/Sub.

Habilitar la API
Elige un tema de Pub/Sub existente al que deseas enviar notificaciones.
Obtén la dirección de correo electrónico de la cuenta de servicio asociada con el proyecto que contiene el bucket del Servicio de transferencia de almacenamiento.
1. Otorga a la cuenta de servicio la función de IAM roles.pubsub.publisher del tema de Pub/Sub deseado.
Nota: Puede haber una demora de varios segundos entre la asignación de la función y su aplicación a tu cuenta de servicio. Si otorgas este permiso de forma programática, espera 30 segundos antes de configurar el Servicio de transferencia de almacenamiento.

Establece la configuración de notificaciones

Para establecer la configuración de notificaciones de Pub/Sub del Servicio de transferencia de almacenamiento, usa la API transferJobs del Servicio de transferencia de almacenamiento, para crear el mensaje NotificationConfig. El tema recibirá notificaciones en el canal de Pub/Sub configurado.

Especifica lo siguiente en tu mensaje NotificationConfig:

El tema de Pub/Sub al que se enviarán notificaciones
El formato del mensaje como "JSON" o "NONE"
Los tipos de eventos deseados, correspondientes a TransferOperation.Statuses completada:
- "TRANSFER_OPERATION_SUCCESS"
- "TRANSFER_OPERATION_FAILED"
- "TRANSFER_OPERATION_ABORTED"

El siguiente es un mensaje de ejemplo NotificationConfig:

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

Reemplaza lo siguiente:

project-id: Es el ID del proyecto de Google Cloud de la transferencia.
topic-id: Es 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 almacenamiento.

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 envía el Servicio de transferencia de almacenamiento 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:

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

Nombre del atributo	Ejemplo	Descripción
`eventType`	`TRANSFER_OPERATION_SUCCESS`	Estado de `TransferOperation`, de `NotificationConfig.EventType`
`payloadFormat`	`"JSON"`	Formato del mensaje, ya sea como `"JSON"` o `"NONE"`, desde `NotificationConfig.PayloadFormat`.
`projectId`	`project-3`	ID del proyecto de host de transferencia
`transferJobName`	`transferJobs/123`	Nombre del trabajo de transferencia
`transferOperationName`	`transferOperations/456`	Nombre de la operación de transferencia

Carga útil

La carga útil contiene los metadatos TransferOperation. 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	La carga útil tiene el mismo formato que una respuesta JSON, en application/json.

Ejemplos de configuración de notificaciones de Pub/Sub

Notifica solo las transferencias fallidas

Para recibir mensajes solo de transferencias fallidas, envía un 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"
   },
   ...
}

Reemplaza lo siguiente:

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

Notifica todas las transferencias completadas

Para notificar todas las transferencias completadas, independientemente de su estado, envía un 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"
   },
   ...
}

Reemplaza lo siguiente:

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

Realiza 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 vinculada a una función de nube en segundo plano. Para obtener más información, consulta el Instructivo de Cloud Pub/Sub.

Entre los ejemplos de acciones arbitrarias se incluyen los siguientes:

Garantías de entrega

El Servicio de transferencia de almacenamiento envía notificaciones para cualquier TransferOperations iniciada después de agregar una configuración de notificación, y garantiza al menos una vez la entrega a Pub/Sub. Pub/Sub también ofrece entrega al menos una vez al destinatario, lo que significa que podrías recibir varios mensajes, con varios ID, que representan el mismo evento del Servicio de transferencia de almacenamiento.

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

Si una notificación sigue sin poder entregarse a un tema de Pub/Sub de forma coherente, el Servicio de transferencia de almacenamiento 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 el Servicio de transferencia de almacenamiento ya no tiene permiso para publicar en el tema o cuando el proyecto que posee el tema supera su cuota de publicación.