Notificações do Pub/Sub para Cloud Storage

Configuração

Nesta página, você tem uma visão geral do recurso Notificações do Pub/Sub para Cloud Storage.

Visão geral

As notificações do Pub/Sub enviam informações sobre mudanças em objetos nos seus buckets 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 bucket. 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 de Pub/Sub em qualquer projeto que tenha permissões suficientes. Depois de recebida pelo tópico do Pub/Sub, os assinantes do tópico podem receber a mensagem associada. Consulte os pré-requisitos para mais informações sobre como conectar os buckets 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 bucket. 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. O Cloud Functions permite executar funções C#, Go, Java, Node.js, Python, PHP e Ruby quando um objeto no bucket é alterado. Para isso, o bucket 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 bucket 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 bucket. Um bucket 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 bucket 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 bucket;
  • 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 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 bucket. Isso inclui copiar ou regravar 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 excluídos como parte da configuração do ciclo de vida do bucket. Isso não inclui objetos que se tornam não atuais (consulte OBJECT_ARCHIVE) ou uploads de várias partes cancelados.
OBJECT_ARCHIVE Somente enviado quando um bucket 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 não atual porque foi explicitamente transformada ou porque foi substituída pelo upload de um objeto do mesmo nome.

Para outros eventos do Cloud Storage, como operações de bucket ou leituras de objetos, é possível ativar o tipo de registro de auditoria apropriado nos registros de auditoria do Cloud e roteá-los para o Pub/Sub usando um filtro.

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 contém 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 contém 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 bucket que contém o objeto alterado.
objectId bar Nome do objeto alterado.
objectGeneration 123456 Número de geração do objeto alterado.
eventTime 2021-01-15T01:30:15.01Z O horário em que o evento ocorreu expressado no formato RFC 3339.

À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.

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 --custom-attributes no comando gcloud storage 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