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

Configuração

Esta página fornece uma vista geral das notificações do Pub/Sub para o Cloud Storage.

Vista geral

As notificações do Pub/Sub enviam informações sobre alterações a objetos nos seus contentores para o Pub/Sub, onde as informações são adicionadas a um tópico do Pub/Sub à sua escolha sob a forma de mensagens. Por exemplo, pode monitorizar objetos criados e eliminados no seu contentor. Cada notificação contém informações que descrevem o evento que a acionou e o objeto que foi alterado.

Pode enviar notificações para qualquer tópico do Pub/Sub em qualquer projeto para o qual tenha autorizações suficientes. Depois de recebida pelo tópico do Pub/Sub, os subscritores do tópico podem receber a mensagem associada. Consulte a secção Pré-requisitos para ver informações sobre como associar os seus contentores do Cloud Storage a um tópico do Pub/Sub.

Configurações de notificações

Uma configuração de notificação é uma regra que associa a um contentor que especifica:

  • O tópico no Pub/Sub que recebe notificações.
  • Os eventos que acionam o envio de uma notificação.
  • As informações contidas nas notificações.

Pode anexar várias configurações de notificação a um contentor. Um contentor pode ter até 100 configurações de notificações no total e até 10 configurações de notificações definidas para serem acionadas para um evento específico.

Por exemplo, se tiver uma configuração de notificação que envie notificações de eliminação para um tópico do Pub/Sub, pode adicionar uma segunda configuração de notificação ao contentor que envie notificações de eliminação para outro tópico. No entanto, se tentar criar mais de 10 configurações de notificações que o façam, recebe um erro. Além destas configurações de notificações, também pode criar configurações de notificações que enviam notificações para outros eventos, como a criação de objetos, para tópicos do Pub/Sub usados pelas notificações de eliminação ou para tópicos diferentes.

Cada configuração de notificação é identificada por um número inteiro. É devolvido este número inteiro:

  • Quando cria a configuração de notificação.
  • Quando lista as configurações de notificação anexadas a um contentor.
  • No atributo notificationConfig de cada notificação acionada pela configuração de notificação.

A criação e a eliminação de configurações de notificações incrementam o número de metageração de um contentor.

Tipos de eventos

Segue-se uma lista dos tipos de eventos suportados pelo Cloud Storage:

Tipo de evento Descrição
OBJECT_FINALIZE Enviado quando um novo objeto (ou uma nova geração de um objeto existente) é criado com êxito no contentor. Isto inclui copiar, reescrever ou restaurar um objeto existente. Um carregamento com falha não aciona este evento.
OBJECT_METADATA_UPDATE Enviado quando os metadados de um objeto existente são alterados.
OBJECT_DELETE Enviado quando um objeto é eliminado permanentemente. Isto inclui objetos que são substituídos ou eliminados como parte da configuração do ciclo de vida do contentor. Isto não inclui objetos que se tornam não atuais (consulte OBJECT_ARCHIVE) ou carregamentos multipartes anulados.
OBJECT_ARCHIVE Enviado apenas quando um contentor tiver a criação de versões de objetos ativada. Este evento indica que a versão em direto de um objeto tornou-se uma versão não atual, quer porque foi explicitamente tornada não atual, quer porque foi substituída pelo carregamento de um objeto com o mesmo nome.

Para outros eventos do Cloud Storage, como operações de contentores ou leituras de objetos, pode ativar o tipo de registo de auditoria adequado nos registos de auditoria na nuvem e encaminhar os registos de auditoria para o Pub/Sub através de um filtro.

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 indica 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 indica o número de geração do novo objeto.

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 chave:valor contidos em todas as notificações enviadas pelo Cloud Storage 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:

Nome do atributo Exemplo Descrição
notificationConfig projects/_/buckets/foo/notificationConfigs/3 Um identificador da configuração de notificação que acionou esta notificação.
eventType OBJECT_FINALIZE O tipo de evento que acabou de ocorrer. Consulte Tipos de eventos para ver uma lista de valores possíveis.
payloadFormat JSON_API_V1 O formato da payload do objeto. Consulte Payload para ver uma lista de valores possíveis.
bucketId foo O nome do contentor que contém o objeto alterado.
objectId bar O nome do objeto alterado.
objectGeneration 123456 O número de geração do objeto alterado.
eventTime 2021-01-15T01:30:15.01Z A hora em que o evento ocorreu, expressa no formato RFC 3339.

Por vezes, as notificações contêm o seguinte conjunto de pares chave:valor, independentemente da carga útil da notificação:

Nome do atributo Exemplo Descrição
overwrittenByGeneration 107458 O número de geração do objeto que substituiu o objeto ao qual esta notificação se refere. Este atributo só aparece em 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 ao qual esta notificação se refere. Este atributo só aparece em 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. Os atributos personalizados são definidos quando cria uma configuração de notificação, usando o --custom-attributes num comando gcloud storage ou o objeto custom_attributes no corpo de um pedido JSON POST notificationConfigs.

Payload

A carga útil é uma string que contém os metadados do objeto alterado. 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 carga útil:

Tipo de payload Descrição
NENHUM Não está incluído nenhum payload na notificação.
JSON_API_V1 A payload é uma string UTF-8 que contém a representação do recurso dos metadados do objeto.

Para notificações OBJECT_DELETE, os metadados contidos na carga útil representam os metadados do objeto tal como estavam antes da eliminação, juntamente com uma propriedade timeDeleted adicional. Para todas as outras notificações, os metadados incluídos na carga útil representam os metadados do objeto após a ocorrência da alteração.

Por exemplo, suponhamos que tem uma configuração de notificação que acompanha eventos OBJECT_METADATA_UPDATE. Se um utilizador alterar a contentTypepropriedade de um objeto de binary/octet-stream para video/mp4, é enviada uma notificação OBJECT_METADATA_UPDATE, e os metadados na carga útil incluem "contentType":"video/mp4".

Garantias de entrega

Quando adiciona uma configuração de notificação, o Cloud Storage pode demorar até 30 segundos a começar a enviar notificações associadas à mesma. Uma vez iniciada, o Cloud Storage garante a entrega, pelo menos, uma vez ao Pub/Sub. 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 Cloud Storage.

Não é garantido que as notificações sejam publicadas na ordem em que o Pub/Sub as recebe. Se planeia modificar o objeto do Cloud Storage com base numa notificação, recomendamos que use os números de geração e metageração do objeto como pré-condições no seu pedido de atualização.

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

O que se segue?