Migrar das notificações de mudança de objeto para as notificações do Pub/Sub

Este guia é para usuários do recurso Notificações de mudança de objeto descontinuado do Cloud Storage. As notificações do Pub/Sub para o Cloud Storage são a ferramenta recomendada para gerar notificações que rastreiam mudanças em objetos nos buckets do Cloud Storage. As notificações do Pub/Sub oferecem mais velocidade, flexibilidade, facilidade de configuração e economia. Este guia explica as diferenças entre as notificações de mudança de objeto e as notificações do Pub/Sub para o Cloud Storage e fornece etapas de migração das notificações de mudança de objeto para as notificações do Pub/Sub.

Visão geral das notificações de alteração de objetos

As notificações de alteração de objeto são um mecanismo legado do Cloud Storage para notificar um aplicativo sobre mudanças em objetos dentro de um bucket. Quando uma notificação de mudança de objeto é configurada, o Cloud Storage envia solicitações HTTP POST (webhooks) para um URL de aplicativo especificado sempre que um objeto é adicionado, atualizado ou excluído. As notificações de mudança de objeto são estabelecidas enviando uma solicitação watchAll ao Cloud Storage usando a API JSON, bibliotecas de cliente ou o comando watchbucket de notificação do gsutil. Não há um mecanismo pull, e você precisa ter um nome de domínio acessível publicamente com suporte de um servidor HTTP para receber as mensagens do webhook. Recomendamos usar as notificações do Pub/Sub para o Cloud Storage em novas implementações devido à confiabilidade, escalonabilidade e flexibilidade.

Para mais informações, consulte Notificação de mudança de objeto.

Visão geral das notificações do Pub/Sub

As notificações do Pub/Sub para o Cloud Storage oferecem uma maneira moderna, escalonável e confiável de acionar ações em resposta a mudanças nos seus buckets do Cloud Storage enviando informações de eventos para um tópico do Pub/Sub. O Pub/Sub oferece entrega de mensagens por push como solicitações POST HTTP feitas para webhooks. Quando objetos são criados, atualizados ou excluídos, o Cloud Storage publica mensagens que contêm metadados de objetos em um tópico especificado do Pub/Sub, que pode ser consumido por vários assinantes, como funções do Cloud Run, pipelines de dados ou microsserviços. Isso permite arquiteturas flexíveis e orientadas por eventos com entrega pelo menos uma vez e recursos robustos de tratamento de erros.

Para mais informações, consulte Notificações do Pub/Sub para o Cloud Storage.

Comparar notificações de alteração de objeto com notificações do Pub/Sub

A tabela a seguir compara as notificações de mudança de objeto com os recursos de notificações do Pub/Sub:

Recurso Notificações de alteração de objetos Notificações do Pub/Sub
Purpose Notifica um aplicativo diretamente por solicitações HTTP POST (webhooks) quando os objetos em um bucket mudam. Envia informações sobre mudanças em objetos nos buckets do Cloud Storage para um tópico do Pub/Sub.
Mecanismo de exibição POST HTTP direto (webhook) para um URL de aplicativo especificado. As mensagens publicadas em um tópico do Pub/Sub podem ser consumidas por vários assinantes, como funções do Cloud Run, outros aplicativos e pipelines de dados.
Confiabilidade Tenta fazer a entrega de forma confiável, mas a pontualidade não é garantida. As notificações podem atrasar indefinidamente. Oferece entrega pelo menos uma vez, o que significa que as mensagens podem ser entregues várias vezes, mas não são perdidas. O Pub/Sub processa a persistência e as novas tentativas de mensagens.
Escalonabilidade Menos escalonável, já que depende de webhooks diretos que o aplicativo precisa processar. Altamente escalonável e projetado para processamento de eventos em larga escala.
Flexibilidade Limitado à integração direta de webhook. Altamente flexível. As mensagens do Pub/Sub podem acionar funções do Cloud Run, alimentar pipelines de dados (Dataflow) e ser consumidas por outros microsserviços.
Filtro Nenhum Opções de filtragem robustas disponíveis no nível da assinatura do Pub/Sub, permitindo que os assinantes recebam apenas mensagens que atendam a critérios específicos.
Segurança Exige que o endpoint do aplicativo esteja acessível publicamente (HTTPS). O Pub/Sub oferece o IAM para controle de acesso refinado a tópicos e assinaturas. O Pub/Sub ajuda na entrega segura de mensagens, seja puxando notificações diretamente ou enviando-as para um endpoint público.
Complexidade Pode ser mais simples de configurar para casos de uso básicos, mas o gerenciamento da entrega confiável e do escalonamento pode se tornar complexo. Exige o entendimento dos conceitos do Pub/Sub (tópicos, assinaturas), mas oferece uma solução mais robusta e gerenciável para arquiteturas orientadas a eventos.
Status da suspensão de uso Obsoleto. Recomendamos usar notificações do Pub/Sub para novas implementações. Ativo. Esse é o método principal e em desenvolvimento ativo para notificações do Cloud Storage.
Uso recomendado Não recomendado para novos projetos. Principalmente para integrações legadas menos complexas que não podem ser migradas. Altamente recomendado para criar arquiteturas robustas, escalonáveis e orientadas a eventos que reagem a mudanças no Cloud Storage.

Por que migrar para as notificações do Pub/Sub?

Migrar das notificações legadas de mudança de objeto para o Pub/Sub para notificações do Cloud Storage é uma etapa importante para um gerenciamento de eventos robusto. O Pub/Sub é recomendado para arquiteturas orientadas a eventos no Trusted Cloud, oferecendo vantagens técnicas e operacionais significativas em relação às notificações de mudança de objeto.

Confira abaixo as vantagens de migrar para as notificações do Pub/Sub:

  • Entrega confiável: o Pub/Sub entrega cada mensagem publicada pelo menos uma vez para cada assinatura, validando que os eventos chegam aos seus consumidores. A entrega confiável minimiza a perda de dados e melhora a confiabilidade dos fluxos de trabalho em comparação com o modelo de entrega menos robusto das notificações de mudança de objeto.
  • Escalonabilidade: projetadas para alta capacidade, as notificações do Pub/Sub podem processar grandes volumes de eventos automaticamente. Com as notificações do Pub/Sub, é possível eliminar os gargalos de performance que você pode encontrar com as notificações de mudança de objeto à medida que seus dados ou a frequência de eventos aumentam.
  • Integração com serviços do Trusted Cloud : o Pub/Sub se integra perfeitamente a vários serviços do Trusted Cloud , oferecendo flexibilidade para criar fluxos de trabalho automatizados usando funções do Cloud Run, Cloud Run, Dataflow e observabilidade aprimorada com o Cloud Logging e o Cloud Monitoring.
  • Controle granular: com o Pub/Sub, é possível filtrar mensagens no nível da assinatura. Isso permite que os consumidores recebam apenas eventos relevantes, reduzindo o processamento e o tráfego de rede desnecessários.
  • Suporte a plataformas: as notificações do Pub/Sub são o serviço de mensagens compatível. A migração ajuda você a usar uma tecnologia que recebe melhorias contínuas, atualizações de segurança e documentação abrangente, ao contrário das notificações de mudança de objeto descontinuadas.

Etapas da migração

As notificações de mudança de objeto e do Pub/Sub para o Cloud Storage podem enviar mensagens duplicadas ocasionalmente. Portanto, o código de consumo precisa ser projetado para processar mensagens duplicadas com segurança.

Para migrar das notificações de mudança de objeto para as notificações do Pub/Sub, siga estas etapas:

  1. Comece a usar as notificações do Pub/Sub para o Cloud Storage além da configuração atual de notificações de mudança de objeto. Para informações sobre como configurar notificações do Pub/Sub, consulte Configurar notificações do Pub/Sub para Cloud Storage.

  2. Teste e verifique se o fluxo de trabalho de processamento de notificações do Pub/Sub do aplicativo está funcionando corretamente. Para informações sobre como monitorar uma assinatura do Pub/Sub, consulte Monitorar assinaturas no Pub/Sub.

  3. Interrompe o processamento de mensagens recebidas de um canal de notificações de alteração de objeto. Para interromper um canal de notificações, faça uma solicitação de interrupção.

Considerações sobre a assinatura por push do Pub/Sub

Embora as assinaturas de pull do Pub/Sub ofereçam mais flexibilidade e controle, as assinaturas de push do Pub/Sub são muito parecidas com as mensagens de notificação de alteração de objeto. Como resultado, as assinaturas por push se tornam um caminho de migração mais rápido para usuários atuais de notificações de mudança de objeto. Para uma comparação detalhada das assinaturas de push e pull, consulte Escolher um tipo de assinatura.

Se você planeja usar a assinatura por push e reutilizar o código de processamento de notificações, considere as diferenças entre os formatos de solicitação por push de notificações de mudança de objeto e do Pub/Sub e as interpretações de código de resposta. As diferenças são descritas nas seções a seguir.

Formato da solicitação de push

Esta seção descreve as diferenças de formato das solicitações push entre as notificações de mudança de objeto e as notificações do Pub/Sub.

  • Notificações de mudança de objeto: uma notificação de mudança de objeto é entregue como uma solicitação HTTP POST para o URL do aplicativo, no seguinte formato:

    POST /ApplicationUrlPath
Accept: * / *
Content-Length: 1097
Content-Type: application/json; charset="utf-8"
Host: ApplicationUrlHost
X-Goog-Channel-Id: ChannelId
X-Goog-Channel-Token: ClientToken
X-Goog-Resource-Id: ResourceId
X-Goog-Resource-State: ResourceState
X-Goog-Resource-Uri: https://storage.googleapis.com/storage/v1/b/BucketName/o?alt=json

{
"kind": "storage#object",
"id": "BucketName/ObjectName",
"selfLink": "https://www.googleapis.com/storage/v1/b/BucketName/o/ObjectName",
"name": "ObjectName",
"bucket": "BucketName",
"generation": "1367014943964000",
"metageneration": "1",
"contentType": "application/octet-stream",
"updated": "2013-04-26T22:22:23.832Z",
"size": "10",
"md5Hash": "xHZY0QLVuYng2gnOQD90Yw==",
"mediaLink": "https://content-storage.googleapis.com/storage/v1/b/BucketName/o/ObjectName?generation=1367014943964000&alt=media",
"owner": {
  "entity": "user-jeffersonloveshiking@gmail.com"
},
"crc32c": "C7+82w==",
"etag": "COD2jMGv6bYCEAE="
}

  • Notificações do Pub/Sub: quando configurada para entrega por push, uma notificação do Pub/Sub é entregue como uma solicitação HTTP POST. O campo data contém o payload do evento do Cloud Storage codificado em base64. Quando o campo de dados é decodificado, ele corresponde ao corpo da mensagem de notificações de mudança de objeto.

    POST /YourSpecifiedURL
Accept: * / *
Content-Length: 1097
Content-Type: application/json; charset="utf-8"
Host: ApplicationUrlHost
{
  "deliveryAttempt": 5,
  "message":
    {"attributes":
      {"notificationConfig":"projects/_/buckets/foo/notificationConfigs/3",
        "eventType": "OBJECT_FINALIZE",
        "payloadFormat": "JSON_API_V1",
        "bucketId": "foo",
        "objectId": "bar",
        "objectGeneration": 123456,
        "eventTime": "2021-01-15T01:30:15.01Z"
      },
    "data": "ewogImtpbm",
    "messageId": "2070443601311540",
    "message_id": "2070443601311540",
    "orderingKey": "key",
    "publishTime": "2021-02-26T19:13:55.749Z",
    "publish_time": "2021-02-26T19:13:55.749Z"
    },
  "subscription": "projects/myproject/subscriptions/mysubscription"
}

Código de resposta

A tabela a seguir descreve as diferenças de interpretação do código de resposta entre as notificações de mudança de objeto e as notificações do Pub/Sub:

Recurso Código de resposta Interpretação Ação
Notificações de alteração de objeto
102, 200, 201, 202, 204 Sucesso Mensagem processada
500, 502, 503, 504 Falha ao processar Tente de novo mais tarde
Tempos limite, falhas de conexão, nenhuma resposta Falha ao processar Tente de novo mais tarde
Qualquer outro código HTTP. Por exemplo, 404. Falha permanente Não repetir mensagem
Notificações do Pub/Sub
102, 200, 201, 202, 204 Sucesso Mensagem confirmada
Todos os outros códigos de resposta, tempos limite e falhas de conexão Falha Tente de novo mais tarde

A seguir