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
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.
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 depósito del Servicio de transferencia de almacenamiento.
- Otorga a la cuenta de servicio la función de IAM
roles.pubsub.publisher
del tema de Pub/Sub deseado.
- Otorga a la cuenta de servicio la función de IAM
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:
- Envía un correo electrónico
- Inicia un trabajo de flujo de datos.
- Graba metadatos en Cloud SQL.
- Registra metadatos en Spanner
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.