Notificações do Pub/Sub para Cloud Storage

Nesta página, você tem uma visão geral do recurso Notificações do Pub/Sub para Cloud Storage. Para saber como configurar e usar Notificações do Pub/Sub, consulte Como publicar mudanças em objetos.

Visão geral

O recurso Notificações do Pub/Sub envia informações sobre mudanças em objetos nos seus intervalos para o Pub/Sub. Essas informações são adicionadas na forma de mensagens a um tópico do Pub/Sub escolhido por você. Por exemplo, é possível rastrear objetos criados e excluídos no seu 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 qualquer tópico do Pub/Sub em qualquer projeto em que você tenha permissões suficientes. Depois de recebida pelo tópico do Pub/Sub, a mensagem resultante pode ser enviada para qualquer quantidade de assinantes do tópico. Consulte os pré-requisitos para mais informações sobre como conectar seus intervalos do Cloud Storage a um tópico do Pub/Sub.

Outras opções de notificação

Assinar as Notificações do Pub/Sub é uma maneira versátil de acionar alertas e ações em resposta às mudanças em um intervalo. Também estão disponíveis as seguintes opções:

  • Cloud Functions: se você quer apenas acionar uma função leve e independente em resposta a eventos, sem ter que gerenciar um tópico do Pub/Sub, use o Cloud Functions. Este recurso permite que você execute funções de JavaScript, Python e Go quando ocorre uma mudança em um objeto no intervalo. Observe que o intervalo deve 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 sobre mudanças em objetos: este é um recurso mais antigo e avulso do Cloud Storage para gerar notificações. Ele envia mensagens HTTPS para um aplicativo cliente configurado separadamente. Geralmente, o uso deste recurso não é recomendado porque as Notificações do Pub/Sub são mais econômicas, fáceis e flexíveis.

Configurações de notificação

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

  • o tópico no Pub/Sub que receberá as notificações;
  • os eventos que acionam o envio de uma notificação;
  • as informações contidas nas notificações.

É possível anexar várias configurações de notificação a um intervalo. Um intervalo pode ter um total de até 100 configurações de notificação. Dentre essas, é possível definir até 10 para que sejam acionadas em um evento específico.

Por exemplo, se você tiver uma configuração que envia notificações de exclusão para um tópico do Pub/Sub, será possível adicionar uma segunda configuração ao intervalo que envie 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, receberá um erro. Além das configurações acima, também é possível criar configurações que enviam notificações em outros eventos, como a criação de objetos, para os mesmos tópicos do Pub/Sub que são 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.

Criar e excluir configurações de notificação aumenta gradualmente 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 ocorre uma mudança nos metadados de um objeto atual.
OBJECT_DELETE Enviado quando um objeto tiver sido excluído permanentemente. Isso inclui objetos que são substituídos ou excluídos como parte da configuração do ciclo de vida do intervalo. No caso dos intervalos em que o recurso de controle de versões de objetos está ativado, este evento não é enviado quando um objeto se torna não atual (consulte OBJECT_ARCHIVE), mesmo se por meio do método storage.objects.delete.
OBJECT_ARCHIVE Enviado somente quando o recurso de controle de versões de objetos está ativado no intervalo. Este evento indica que a versão ativa de um objeto tornou-se uma versão não atual porque foi explicitamente transformada ou porque foi substituída com o upload de um objeto de 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 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

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

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 O número de geração do objeto que substituiu aquele 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 por aquele a que esta notificação pertence. Este atributo só aparece nos eventos OBJECT_FINALIZE no caso de uma substituição.

O uso do par de chave-valor a seguir foi 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
resource projects/_/buckets/foo/objects/bar#123456 O caminho do objeto no Cloud Storage que mudou.

Além dos atributos acima, uma configuração de notificação pode conter até 10 atributos personalizados. Esses atributos personalizados são definidos durante a criação da configuração, usando a sinalização -m no comando gsutil notification ou o objeto custom_attributes no corpo de uma solicitação POST notificationConfigs em JSON.

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
NONE Não há payload incluída na notificação.
JSON_API_V1 O payload será uma string UTF-8 contendo a representação de recursos dos metadados do objeto.

No caso das notificações OBJECT_DELETE, os metadados contidos no payload representam os metadados do objeto como eram antes da exclusão, com uma propriedade timeDeleted extra. 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

Quando você inclui uma configuração de notificação, o Cloud Storage pode levar até 30 segundos para começar a enviar as notificações associadas a essa configuração. Depois que o envio é iniciado, o Cloud Storage oferece a garantia de entregar a notificação pelo menos uma vez para o Pub/Sub. 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 Cloud Storage.

Não há garantias de que as notificações serão publicadas na ordem em que o Pub/Sub as recebe. Se você planeja modificar um objeto do Cloud Storage com base em uma notificação, é recomendável usar os números de geração e metageração desse objeto como condições prévias na solicitação de atualização.

Se invariavelmente não for possível entregar uma notificação a um tópico do Pub/Sub, o 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 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.

A seguir

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

Enviar comentários sobre…

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