Notificações do Pub/Sub

Depois de concluir uma transferência do serviço de transferência do Cloud Storage, é possível iniciar outra tarefa, resolver um erro encontrado durante uma transferência ou registrar uma transferência. O Pub/Sub fornece uma fila que os programas assinam para receber mensagens quando uma transferência é concluída. Isso permite que você reutilize o código e programe as próximas etapas com base no estado de uma transferência.

Para mais informações sobre Pub/Sub, consulte O que é o Cloud Pub/Sub.

Pré-requisitos

Antes de usar esse recurso, faça o seguinte:

  1. Ative a API Pub/Sub para o projeto que recebe as notificações do Pub/Sub.

    Ativar a API

  2. Tenha um tópico do Pub/Sub para onde as notificações serão enviadas.

  3. Consiga o endereço de e-mail da conta de serviço associada ao projeto que contém o bucket do serviço de transferência do Cloud Storage.

    1. Conceda à conta de serviço o papel do IAM roles.pubsub.publisher para o respectivo tópico Pub/Sub.

Como definir configurações de notificação

Para definir configurações de notificação do Pub/Sub do serviço de transferência do Cloud Storage, use a API transferJobs do serviço de transferência do Cloud Storage para criar uma mensagem NotificationConfig. O tópico receberá notificações no canal configurado do Pub/Sub.

Na mensagem NotificationConfig, especifique:

  • o tópico Pub/Sub para onde as notificações serão enviadas;
  • o formato da mensagem, "JSON" ou "NONE";

  • os tipos de evento desejados, correspondentes a TransferOperation.Statuses concluídos:

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

Veja a seguir um exemplo de mensagem NotificationConfig:

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

Substitua:

  • project-id: o ID do projeto do Google Cloud da transferência
  • topic-id: o nome do tópico do Pub/Sub

Para mais informações, consulte a Especificação do Pub Sub REST do serviço de transferência do Cloud Storage.

Formato da notificação

As notificações enviadas ao tópico do Pub/Sub são compostas de duas partes:

  • Atributos: um conjunto de pares de chave-valor que descreve o evento.
  • Payload: uma string de caracteres que contém os metadados do objeto alterado.

Atributos

Os atributos são pares de chave-valor contidos em todas as notificações enviadas pelo serviço de transferência do Cloud Storage ao seu tópico do Pub/Sub. As notificações sempre contêm o seguinte conjunto de pares de chave-valor, independentemente do payload:

Consulte PubsubMessage para mais informações sobre o formato da mensagem do Pub/Sub.

Nome do atributo Exemplo Descrição
eventType TRANSFER_OPERATION_SUCCESS Status de TransferOperation, de NotificationConfig.EventType
payloadFormat "JSON" Formato da mensagem, "JSON" ou "NONE". De NotificationConfig.PayloadFormat.
projectId project-3 ID do projeto host de transferência.
transferJobName transferJobs/123 Nome do job de transferência.
transferOperationName transferOperations/456 Nome da operação de transferência.

Payload

O payload tem os metadados TransferOperation. Ao criar uma configuração de notificação, especifique um tipo de payload para incluir em notificações acionadas por essa configuração. É possível especificar os seguintes tipos de payload:

Tipo de payload Descrição
NONE Não há payload incluída na notificação.
JSON O payload é formatado como uma resposta JSON, no aplicativo/json.

Exemplo de configurações de notificação do Pub/Sub

Notificação apenas para transferências com falha

Para receber apenas mensagens sobre transferências com falha, envie um TransferJob com NotificationConfig que filtre somente por transferências com falha:

// 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"
   },
   ...
}

Substitua:

  • project-id: o ID do projeto do Google Cloud da transferência
  • topic-id: o nome do tópico do Pub/Sub

Notificar sobre todas as transferências concluídas

Para notificar sobre todas as transferências concluídas, independentemente do status, envie um TransferJob com NotificationConfig sem 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"
   },
   ...
}

Substitua:

  • project-id: o ID do projeto do Google Cloud da transferência
  • topic-id: o nome do tópico do Pub/Sub

Como executar ações arbitrárias em uma transferência

Para executar uma ação arbitrária, crie uma notificação do Pub/Sub usando uma função do Cloud com um gatilho do Pub/Sub pareado com uma função do Cloud em segundo plano. Para mais informações, consulte o tutorial do Cloud Pub/Sub.

Exemplos de ações arbitrárias incluem:

Garantias de entrega

O serviço de transferência do Cloud Storage envia notificações para qualquer TransferOperations iniciado depois que você adiciona uma configuração de notificação e garante o envio para o Pub/Sub pelo menos uma vez. O Pub/Sub também oferece a garantia de entregar notificações pelo menos uma vez ao destinatário, o que significa que você talvez receba diversas mensagens, com vários IDs, que representam o mesmo evento do serviço de transferência do Cloud Storage.

Não há garantias de que as notificações serão publicadas na ordem em que o Pub/Sub as recebe.

Se invariavelmente não for possível entregar uma notificação a um tópico do Pub/Sub, o serviço de transferência do Cloud Storage poderá excluí-la depois de sete dias. A falha na entrega poderá ocorrer se o tópico do Pub/Sub não existir mais, o serviço de transferência do Cloud Storage deixar de ter permissão para publicar no tópico ou o projeto a que o tópico pertence ultrapassar a cota de publicação.