Notificações do Pub/Sub

Depois de concluir uma transferência do Serviço de Transferência de Armazenamento, pode querer iniciar outra tarefa, resolver um erro encontrado durante uma transferência ou registar que ocorreu uma transferência. O Pub/Sub fornece uma fila à qual os seus programas subscrevem para receber mensagens quando uma transferência é concluída. Isto permite-lhe reutilizar código e programar os passos seguintes com base no estado de uma transferência.

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

Pré-requisitos

Antes de poder utilizar esta funcionalidade, faça o seguinte:

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

    Ative a API

  2. Ter um tópico do Pub/Sub existente para o qual quer enviar notificações.

  3. Obtenha o endereço de email da conta de serviço associada ao projeto que contém o seu contentor do Storage Transfer Service.

    1. Conceda à conta de serviço a função do IAM roles.pubsub.publisher para o tópico do Pub/Sub pretendido.

Configurar definições de notificação

Para configurar as definições de notificação do Pub/Sub do serviço de transferência de armazenamento, use a API transferJobs do serviço de transferência de armazenamento para criar uma mensagem NotificationConfig. O tópico vai receber notificações no canal Pub/Sub configurado.

Especifique o seguinte na sua mensagem NotificationConfig:

  • O tópico do Pub/Sub para o qual enviar notificações
  • O formato da mensagem, "JSON" ou "NONE"

  • Os tipos de eventos desejados, correspondentes a eventos concluídos TransferOperation.Statuses:

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

Segue-se um exemplo de uma mensagem NotificationConfig:

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

Substitua o seguinte:

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

Para mais informações, consulte a especificação REST do Pub/Sub do serviço de transferência de armazenamento.

Formato de notificação

As notificações enviadas para o tópico Pub/Sub são compostas por duas partes:

  • Atributos: um conjunto de pares chave:valor que descrevem o evento.
  • Payload: uma string 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 Storage Transfer Service para o seu tópico do Pub/Sub. As notificações contêm sempre o seguinte conjunto de pares de chave:valor, independentemente da carga útil da notificação:

Consulte PubsubMessage para mais informações acerca do formato de mensagem do Pub/Sub.

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

Payload

O payload contém os metadados TransferOperation. Quando cria uma configuração de notificação, especifica um tipo de payload a incluir nas notificações acionadas por essa configuração. Pode especificar os seguintes tipos de payload:

Tipo de payload Descrição
NENHUM Não está incluído nenhum payload na notificação.
JSON O payload está formatado como uma resposta JSON, em application/json.

Exemplos de configurações de notificações do Pub/Sub

Notificar apenas transferências com falhas

Para receber mensagens apenas para transferências com falhas, envie um TransferJob com um NotificationConfig que filtre apenas transferências com falhas:

// 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 o seguinte:

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

Notificar todas as transferências concluídas

Para receber notificações sobre todas as transferências concluídas, independentemente do estado, envie um TransferJob com um 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 o seguinte:

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

Realizar ações arbitrárias numa transferência

Para realizar uma ação arbitrária, crie uma notificação do Pub/Sub usando uma função do Cloud com um acionador do Pub/Sub associada a 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:

Garantias de entrega

O serviço de transferência de armazenamento envia notificações para qualquer transferência TransferOperationsiniciada depois de adicionar uma configuração de notificação e garante a entrega ao Pub/Sub, pelo menos, uma vez. O Pub/Sub também oferece uma entrega, pelo menos, uma vez ao destinatário, o que significa que pode receber várias mensagens, com vários IDs, que representam o mesmo evento do serviço de transferência de armazenamento.

Não é garantido que as notificações sejam publicadas na ordem em que o Pub/Sub as recebe.

Se não for possível entregar uma notificação de forma consistente a um tópico do Pub/Sub, o serviço de transferência de armazenamento pode eliminar a notificação após 7 dias. A falha de entrega pode ocorrer quando o tópico do Pub/Sub já não existe, quando o serviço de transferência de armazenamento já não tem autorização para publicar no tópico ou quando o projeto proprietário do tópico excede a respetiva quota de publicação.