Notificações do Pub/Sub

• Conclua o codelab de configuração de API para configurar um projeto do Google Cloud e criar uma conta de serviço para chamar a API Cloud Channel.

• Recomendamos usar o Partner Sales Console de teste para este codelab.

• Conheça os conceitos do Pub/Sub.

Visão geral

A API Cloud Channel usa o Pub/Sub para enviar notificações sobre vários eventos de cliente e de direito.

Isso é útil principalmente para:

• Refletir as mudanças feitas diretamente no Partner Sales Console nos seus próprios sistemas (por exemplo, alguém da equipe de suporte cancelando um direito do Google Workspace).
• Detecte eventos críticos acionados pelos seus clientes revendidos. Por exemplo:
  • Um cliente do Google Workspace aceitando os Termos de Serviço.
  • Cliente do Google Workspace verificando o domínio.
  • Um cliente do Google Workspace adicionando usuários com um direito flexível.
  • Um cliente do Google Workspace que está sendo transferido.

A configuração do Pub/Sub consiste nas seguintes três etapas:

1. Ative a API Pub/Sub e prepare sua conta de serviço.

2. Crie um tópico do Pub/Sub. Este tópico é de propriedade dos serviços de canal e você vai especificar uma conta de serviço que pode criar uma assinatura.

3. Crie uma assinatura do Pub/Sub. Essa assinatura pode ser enviada usando webhooks (o método preferido) ou extraida.

Para uma assinatura push, hospede um webhook que recebe os eventos emitidos pelos serviços de canal:

Formato da notificação

Confira a seguir um exemplo de notificação do Pub/Sub. Os dados da mensagem são transmitidos como uma string JSON codificada em base64.

{
  "message": {
    "attributes": {
      "event_type": "LICENSE_ASSIGNMENT_CHANGED",
      "subscriber_event_type": "ENTITLEMENT_EVENT"
    },
    "data": "eyJlbnRpdGxlbWVudF9ldmVudCI6eyJldmVudF90eXBlIjoiTElDRU5TRV9BU1NJR05NRU5UX0NIQU5HRUQiLCJlbnRpdGxlbWVudCI6ImFjY291bnRzL0MwMTIzNDU2L2N1c3RvbWVycy9TMDEyMzQ1NjcvZW50aXRsZW1lbnRzL1NhYmNkZWYxMjM0NSJ9fQ==",
    "message_id": 1918124788439510,
    "publish_time": "2021-01-14T01:23:45.678Z"
  },
  "subscription": "projects/project/subscriptions/channel-pubsub-test"
}

Estes são os mesmos dados da mensagem, decodificados:

{
  "entitlement_event": {
    "event_type": "LICENSE_ASSIGNMENT_CHANGED",
    "entitlement": "accounts/C0123456/customers/S01234567/entitlements/Sabcdef12345"}
  }
}

Etapa 1: ativar a API Pub/Sub e preparar sua conta de serviço

Para executar este codelab, você precisa do seguinte:

• O endereço de e-mail de uma conta de serviço no seu projeto. Esse endereço vai ser parecido com: [e-mail].
• Acesso a uma conta de superadministrador de domínio de revendedor (de preferência, o Partner Sales Console de teste).
• O ID da sua conta. Você pode encontrar essa informação nas configurações do Partner Sales Console.

Para preparar sua conta de serviço:

• Navegue até a seção Biblioteca de APIs no console do Google Cloud e ative a API Pub/Sub.
• Conceda à sua conta de serviço o papel do IAM do Pub/Sub no projeto. Conceder roles/pubsub.editor (nome de função = "Editor do Pub/Sub") é suficiente para este codelab, mas talvez seja melhor usar privilégios mais detalhados na integração de produção. Confira os detalhes completos do papel do IAM na página Controle de acesso do Pub/Sub.
• Se você optar por aplicar uma função personalizada, conceda a ela a permissão pubsub.subscriptions.create para criar assinaturas.

Pode haver um atraso após a aplicação dessas funções e permissões à sua conta.

Atenção: você vai receber erros 403 se não houver papéis do IAM na conta de serviço.

Etapa 2: criar o tema da sua conta

Para criar o tópico do Pub/Sub, use o método accounts.register. Esse método usa um e-mail de conta de serviço como um parâmetro. Somente as contas de serviço autorizadas por esse método podem se inscrever no novo tópico.

1. Acesse a documentação accounts.register e clique em Testar.
2. No campo account, insira accounts/ACCOUNT_ID, substituindo ACCOUNT_ID pelo ID da sua conta.
3. Clique em Adicionar parâmetros do corpo da solicitação, selecione serviceAccount e insira o endereço de e-mail da sua conta de serviço.
4. Clique em Execute e faça login como superadministrador do seu domínio de revendedor.

Você vai receber uma resposta 200 semelhante a esta:

{
  "topic": "projects/cloud-channel-pubsub/topics/C0123456-notify"
}

Esse é o tópico do Pub/Sub em que os eventos serão publicados.

Observação: esse valor é necessário na etapa 3b.

Etapa 3: assinar o tópico

Depois de criar o tópico do Pub/Sub, você precisa configurar como o aplicativo consome eventos de mudança. Você tem duas opções:

• Assinatura push: você fornece um callback POST HTTP. O Pub/Sub vai usar isso para notificar seu aplicativo sobre novos eventos.
• Assinatura de pull: o aplicativo faz chamadas HTTP periodicamente para receber mudanças na fila.

Neste codelab, vamos usar o push e enviar todos os eventos para uma função do Cloud Run que vai fazer login no Cloud Logging.

Etapa 3a: criar uma função do Cloud Run

Nesta etapa, vamos criar uma função do Cloud Run que vai registrar as mensagens recebidas.

1. Acesse a seção Funções do Cloud Run do console do Google Cloud. Talvez seja necessário ativar a API Cloud Run functions.
2. Clique em Criar função.
3. Na tela Configuração:
   1. Mude o nome da função. Se preferir, escolha outra região.
   2. No acionador HTTP, mude Autenticação para Permitir invocações não autenticadas e clique em Salvar.
   3. Anote o URL do acionador. Você precisará dele na próxima etapa.
   4. Clique em Próxima.

4. Na tela Code:

   1. Escolha qualquer ambiente de execução do Node.js
   2. Mude o Ponto de entrada para log.
   3. No arquivo index.js, substitua o exemplo de código por:

   exports.log = (req, res) => {
     if (req.body && req.body.message) {
       console.log(req.body);
       const message = req.body.message;
       // data is base64-encoded JSON
       const data = new Buffer.from(message.data, 'base64').toString();
       console.log(data);
     }
     res.status(200).send('OK');
   };
   

Você pode continuar para a próxima etapa enquanto a função do Cloud Run é implantada.

Etapa 3b: criar a assinatura

Somente contas de serviço registradas para o tópico do Channel Services (consulte a etapa 2) podem criar uma assinatura.

Para fazer isso, chame a API Pub/Sub com as credenciais da sua conta de serviço. Não se passe pelo superadministrador do domínio do revendedor, o que é necessário ao chamar a API Cloud Channel.

Para este codelab, você vai usar a ferramenta CLI gcloud no Cloud Shell.

1. Clique em Ativar o Cloud Shell na parte de cima do Console do Google Cloud.

2. Quando o shell estiver pronto, execute o comando a seguir. Substitua os valores de SERVICE_ACCOUNT pelo endereço de e-mail da sua conta de serviço, TOPIC pelo tópico criado na etapa 2 e PUSH_ENDPOINT pelo URL do gatilho da função do Cloud Run criada na etapa 3a:

   SERVICE_ACCOUNT=[e-mail]
   TOPIC=projects/cloud-channel-pubsub/topics/C0123456-notify
   PUSH_ENDPOINT=https://us-central1-project.cloudfunctions.net/pubsub
   

3. Ative a conta de serviço no shell:

   gcloud iam service-accounts keys create sa-keys.json \
       --iam-account=$SERVICE_ACCOUNT
   gcloud auth activate-service-account --key-file=sa-keys.json
   

4. Crie a assinatura:

   gcloud pubsub subscriptions create channel-pubsub-test \
       --topic=$TOPIC \
       --push-endpoint=$PUSH_ENDPOINT
   

Para confirmar se a assinatura está configurada, acesse a seção "Assinaturas do Pub/Sub".

Gerar alguns dados

Depois de concluir as etapas anteriores, você já pode receber dados.

A maneira mais fácil é criar um cliente no Partner Sales Console e provisionar um produto. Se você já terminou o codelab de provisionamento de ponta a ponta do Workspace, é possível criar um cliente com um Google Workspace executando o código de exemplo.

Acesse a função no console do Google Cloud e abra a guia Registros. Confira abaixo um exemplo do que você vai encontrar.

Observação: em casos raros, pode levar alguns minutos para que a assinatura do Pub/Sub comece a receber eventos do tópico.

Limpar

• Excluir a função do Cloud Run
• Excluir a assinatura

O tópico será limpo automaticamente quando não tiver mais inscritos.

Próximas etapas

Neste codelab, você descobriu como os Serviços de canal usam o Pub/Sub para criar uma integração reativa e em grande escala.

Referência de eventos

Consulte a referência do RPC para conferir a lista de eventos gerados pelo Channel Services.

Referência da API

Este codelab usa o console do Google Cloud, mas você pode realizar estas etapas de forma programática. Para fazer isso, siga estas etapas:

• Use accounts.register para criar o tópico.
• Use o subscriptions.create da API Pub/Sub para criar a assinatura do Pub/Sub.
• Consulte accounts.listSubscribers e accounts.unregister para conferir outros endpoints que podem ser usados na integração.

Garantias e práticas recomendadas do Pub/Sub

O atraso entre um evento e a notificação dele não é garantido. Da mesma forma, a ordem das notificações não é garantida. Por fim, as mensagens podem ser enviadas várias vezes.

Práticas recomendadas para o endpoint push:

• Como as mensagens podem ser atrasadas, enviadas fora de ordem ou enviadas várias vezes, o endpoint precisa ser idempotente e usar customers.get e entitlements.get.

• Embora o tempo limite padrão do Pub/Sub para push seja de 10 segundos, ele pode ser aumentado pela ackDeadline da assinatura do Pub/Sub. Recomendamos usar uma arquitetura baseada em mensagens e fazer o endpoint responder o mais rápido possível.

• Se o endpoint estiver inativo ou retornar erros 5xx, o Pub/Sub vai tentar novamente. Confira mais informações sobre como receber mensagens por push na documentação do Pub/Sub.

Se você preferir usar o pull, confira informações sobre como receber mensagens por pull na documentação do Pub/Sub.

Filtragem de eventos

Como as notificações dos serviços de canal incluem attributes, é possível criar assinaturas detalhadas do Pub/Sub com a filtragem do Pub/Sub.

Por exemplo, a filtragem com attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED" permite acompanhar todas as mudanças de assento do Google Workspace.