Notificações do Cloud Pub/Sub para Cloud Storage

Nesta página, você tem uma visão geral das notificações do Cloud Pub/Sub para Cloud Storage. Para saber como configurar e usar o Cloud Pub/Sub Notifications, consulte Como registrar alterações de objetos.

Visão geral

O recurso Cloud Pub/Sub Notifications envia informações sobre alterações em objetos do intervalo para o Cloud Pub/Sub. As informações são adicionadas ao tópico do Cloud Pub/Sub escolhido, no formato de mensagens. Por exemplo, é possível rastrear objetos criados e excluídos no intervalo. Cada notificação contém informações que descrevem o evento que a desencadeou e o objeto que mudou.

É possível enviar notificações para os tópicos do Cloud Pub/Sub em qualquer projeto em que você tenha permissões suficientes. Uma vez recebida pelo tópico do Cloud Pub/Sub, a mensagem pode ser enviada a qualquer número de assinantes do tópico. Para informações sobre como conectar intervalos do Cloud Storage a um tópico do Cloud Pub/Sub, consulte Pré-requisitos.

Outras opções de notificação

Inscrever-se no recurso Cloud Pub/Sub Notifications é uma maneira versátil de desencadear alertas e ações em resposta a mudanças em um intervalo. As seguintes opções também estão disponíveis:

  • Cloud Functions: se você quiser acionar apenas uma função leve e independente em resposta aos eventos, e não quiser gerenciar um tópico do Cloud Pub/Sub, use o Cloud Functions. Esse recurso permite que você execute funções de JavaScript quando um objeto em um intervalo é alterado. Observe que os seus intervalos precisam residir no mesmo projeto que o Cloud Functions. Para uma demonstração de como usar o Cloud Functions com o Cloud Storage, consulte o tutorial associado.

  • Notificação de alteração de objeto: este é um recurso separado e antigo do Cloud Storage para gerar notificações. Ele envia mensagens HTTPS para um aplicativo cliente configurado separadamente. Geralmente, o recurso Cloud Pub/Sub Notifications é mais barato, mais fácil de usar e mais flexível.

Configurações de notificação

Uma configuração de notificação é uma regra que você anexa a um intervalo que especifica:

  • o tópico no Cloud Pub/Sub que recebe notificações;
  • os eventos que desencadeiam uma notificação a ser enviada;
  • as informações contidas nas notificações.

É possível anexar várias configurações de notificação a um intervalo. Até 10 configurações de notificação podem ser definidas para cada evento para acionar uma notificação.

Por exemplo, se você tem uma configuração de notificação que envia notificações de exclusão para um tópico do Cloud Pub/Sub, é possível adicionar uma segunda configuração de notificação ao intervalo que envia notificações de exclusão para outro tópico. No entanto, se você tentar criar mais de 10 configurações de notificação que façam isso, você receberá um erro. Além dessas configurações de notificação, você também pode criar configurações de notificação que enviam notificações para outros eventos, como a criação de objetos, para os tópicos do Cloud Pub/Sub usados pelas notificações de exclusão ou para tópicos diferentes.

Cada configuração de notificação é identificada por um número inteiro. Esse número inteiro é retornado:

  • quando você cria a configuração de notificação;
  • quando você lista as configurações de notificação anexadas a um intervalo;
  • no atributo notificationConfig de cada notificação acionada pela configuração de notificação.

Criar e excluir configurações de notificação incrementa o número de metageração de um intervalo.

Tipos de evento

A lista seguinte contém os tipos de evento atualmente compatíveis com o Cloud Storage:

Tipo de evento Descrição
OBJECT_FINALIZE Enviado quando um novo objeto ou nova geração de um objeto existente tiver sido criada com sucesso no intervalo. Isso inclui copiar ou reescrever um objeto existente. Um upload com falha não desencadeia esse evento.
OBJECT_METADATA_UPDATE Enviado quando os metadados de um objeto existente são alterados.
OBJECT_DELETE Enviado quando um objeto tiver sido excluído permanentemente. Isso inclui objetos que são substituídos ou são excluídos como parte da configuração do ciclo de vida do intervalo. No caso de intervalos com o controle de versão do objeto ativado, esse tipo de evento não é enviado quando um objeto é arquivado (veja OBJECT_ARCHIVE), mesmo que o arquivamento ocorra por meio do método storage.objects.delete.
OBJECT_ARCHIVE Somente enviado quando um intervalo tiver habilitado o controle de versão do objeto. Este evento indica que a versão ativa de um objeto se tornou uma versão arquivada por ter sido arquivada ou substituída pelo upload de um objeto do mesmo nome.

Como substituir objetos

A substituição de um objeto existente por um novo com o mesmo nome aciona dois eventos separados: OBJECT_FINALIZE para a nova versão do objeto e OBJECT_ARCHIVE ou OBJECT_DELETE para o objeto substituído. O evento OBJECT_FINALIZE conterá um atributo adicional overwroteGeneration, que fornece o número de geração do objeto que foi substituído. O evento OBJECT_ARCHIVE ou OBJECT_DELETE conterá um atributo adicional overwrittenByGeneration que fornece o número de geração do novo objeto.

Formato de notificação

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

  • Atributos: um conjunto de pares de chave-valor que descrevem 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 Cloud Storage para o tópico do Cloud Pub/Sub. As notificações sempre contêm o seguinte conjunto de pares de chave-valor, independentemente da payload da notificação:

Nome do atributo Exemplo Descrição
notificationConfig projects/_/buckets/foo/notificationConfigs/3 Identificador para a configuração de notificação que desencadeou esta notificação.
eventType OBJECT_FINALIZE Tipo de evento que acabou de ocorrer. Para uma lista de valores possíveis, consulte Tipos de evento.
payloadFormat JSON_API_V1 Formato da payload do objeto. Para uma lista de valores possíveis, consulte Payload.
bucketId foo Nome do intervalo que contém o objeto alterado.
objectId bar Nome do objeto alterado.
objectGeneration 123456 Número de geração do objeto alterado.

Às vezes, as notificações contêm o seguinte conjunto de pares de chave-valor, independentemente da payload da notificação:

Nome do atributo Exemplo Descrição
overwrittenByGeneration 107458 Número da geração do objeto que substituiu o objeto a que esta notificação pertence. Este atributo só aparece nos eventos OBJECT_ARCHIVE ou OBJECT_DELETE no caso de uma substituição.
overwroteGeneration 352947 O número de geração do objeto que foi substituído pelo objeto a que esta notificação pertence. Este atributo só aparece nos eventos OBJECT_FINALIZE no caso de uma substituição.

O seguinte par de chave-valor teve o uso suspenso. Ele não é mostrado para novas inscrições e não aparecerá em nenhuma inscrição após 1º de junho de 2018:

Nome do atributo Exemplo Descrição
recurso projects/_/buckets/foo/objects/bar#123456 Caminho do objeto do Cloud Storage que mudou.

Além dos atributos acima, as notificações podem conter atributos personalizados. Eles são definidos ao ser criada uma configuração de notificação com a sinalização -m em um comando gsutil notification ou com o objeto custom_attributes no corpo de uma solicitação JSON POST notificationConfigs.

Payload

Payload é uma string de caracteres que contém os metadados do objeto alterado. Ao criar uma configuração de notificação, você especifica 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
NENHUM Não há payload incluída na notificação.
JSON_API_V1 A payload será uma string UTF-8 contendo a representação de recursos dos metadados do objeto.

Para as notificações OBJECT_DELETE, os metadados contidos na payload representam os metadados do objeto como eram antes da exclusão, juntamente com uma propriedade adicional de timeDeleted. Para todas as outras notificações, os metadados incluídos na payload representam os metadados do objeto após a alteração ocorrer.

Por exemplo, digamos que você tenha uma configuração de notificação que rastreia eventos OBJECT_METADATA_UPDATE. Se um usuário alterar a propriedade contentType de um objeto, de binary/octet-stream para video/mp4, uma notificação OBJECT_METADATA_UPDATE será enviada e os metadados na payload incluirão "contentType":"video/mp4".

Garantias de entrega

Depois da adição de uma configuração e notificação, as notificações associadas a ela podem demorar até 30 segundos para começar a serem enviadas pelo Cloud Storage. Uma vez iniciado, o Cloud Storage garante uma entrega pelo menos uma vez ao Cloud Pub/Sub. O Cloud Pub/Sub também oferece uma entrega de pelo menos uma vez ao destinatário. Isto significa que há possibilidade de você receber várias mensagens, com vários códigos, representando o mesmo evento do Cloud Storage. Atualmente, não há SLA para o tempo de entrega, mas normalmente as notificações são entregues em segundos. Em raras circunstâncias, as notificações podem ter atraso significativo.

Não é garantido que as notificações sejam publicadas na ordem em que o Cloud Pub/Sub as recebe. Se você planeja modificar o objeto do Cloud Storage com base em uma notificação, é recomendado usar os números de geração e metageração do objeto como condições prévias da solicitação de atualização.

Se a entrega de uma notificação a um tópico do Cloud Pub/Sub falhar de maneira consistente, o Cloud Storage poderá excluir a notificação após sete dias. A falha na entrega pode ocorrer quando o tópico do Cloud Pub/Sub não existe, quando o Cloud Storage não tem mais permissão para publicar o tópico ou quando o projeto que possui o tópico excedeu a cota de publicação.

Próximas etapas

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.