Notificações do Pub/Sub

• Certifique-se de que conclui o codelab de configuração da API para configurar um Google Cloud projeto e criar uma conta de serviço para chamar a API Cloud Channel.

• Recomendamos que use a Partner Sales Console de teste para este codelab.

• Familiarize-se com os conceitos do Pub/Sub.

Vista geral

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

Isto é particularmente útil para:

• Refletir as alterações feitas diretamente na Partner Sales Console nos seus próprios sistemas (por exemplo, alguém da sua equipa de apoio técnico cancelar uma autorização do Google Workspace).
• Detete eventos críticos acionados pelos seus clientes de revenda. Por exemplo:
  • Um cliente do Google Workspace a aceitar os Termos de Utilização.
  • Um cliente do Google Workspace que valida o respetivo domínio.
  • Um cliente do Google Workspace que adiciona utilizadores numa autorização flexível.
  • Um cliente do Google Workspace a sair.

A configuração do Pub/Sub consiste nos três passos seguintes:

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

2. Crie um tópico Pub/Sub. Este tópico é propriedade dos serviços de canal e especifica uma conta de serviço que pode criar uma subscrição.

3. Crie uma subscrição do Pub/Sub. Esta subscrição pode ser enviada através de webhooks (o método preferencial) ou extraída.

Para uma subscrição de envio, aloja um webhook que recebe os eventos emitidos pelos serviços de canal:

Formato de notificação

Segue-se um exemplo de uma 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 de mensagens, descodificados:

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

Passo 1: ative a API Pub/Sub e prepare a sua conta de serviço

Para executar este codelab, precisa do seguinte:

• O endereço de email de uma conta de serviço no seu projeto. Este endereço tem o seguinte aspeto: [e-mail].
• Acesso a uma conta de superadministrador de um domínio de revendedor (de preferência, a sua Partner Sales Console de teste).
• O ID da sua conta. Pode encontrar esta opção nas definições da Partner Sales Console.

Para preparar a sua conta de serviço:

• Navegue para a secção Biblioteca de APIs na Google Cloud consola e ative a API Pub/Sub.
• Conceda à sua conta de serviço a função de IAM do Pub/Sub no projeto. A concessão de roles/pubsub.editor (nome da função = "Editor do Pub/Sub") é suficiente para este codelab, mas é recomendável usar privilégios mais detalhados na integração de produção. Pode encontrar detalhes completos das funções de IAM na página Controlo de acesso do Pub/Sub.
• Se optar por aplicar uma função personalizada, tem de conceder a essa função a autorização pubsub.subscriptions.create para criar subscrições.

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

Atenção: recebe erros 403 se não existirem funções do IAM na conta de serviço.

Passo 2: crie o tópico para a sua conta

Para criar o tópico Pub/Sub, tem de usar o método accounts.register. Este método usa um email de conta de serviço como parâmetro. Apenas as contas de serviço autorizadas através deste método podem subscrever o seu novo tópico.

1. Aceda à documentação de accounts.register e clique em Experimentar!.
2. No campo account, introduza accounts/ACCOUNT_ID, substituindo ACCOUNT_ID pelo ID da sua conta.
3. Clique em Adicionar parâmetros do corpo do pedido, selecione serviceAccount e introduza o endereço de email da sua conta de serviço.
4. Clique em Executar e certifique-se de que inicia sessão como superadministrador do domínio do seu revendedor.

Deve receber uma resposta 200 semelhante à seguinte:

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

Este é o tópico do Pub/Sub onde os eventos são publicados.

Nota: este valor é necessário no passo 3b.

Passo 3: subscreva o tópico

Depois de criar o tópico Pub/Sub, tem de configurar a forma como a sua aplicação consome eventos de alteração. Tem duas opções:

• Subscrição de envio: fornece um callback HTTP POST. O Pub/Sub usa esta informação para notificar a sua aplicação acerca de novos eventos.
• Subscrição de obtenção: a sua aplicação faz periodicamente chamadas HTTP para obter alterações em fila.

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

Passo 3a: crie uma função do Cloud Run

Neste passo, vamos criar uma função do Cloud Run que vai registar as mensagens recebidas.

1. Aceda à secção Funções do Cloud Run da Google Cloud consola. Pode ter de ativar a API Cloud Run Functions.
2. Clique em Criar função.
3. No ecrã Configuração:
   1. Altere o nome da função. Opcionalmente, escolha uma região diferente.
   2. No acionador HTTP, altere a Autenticação para Permitir invocações não autenticadas e clique em Guardar.
   3. Tome nota do URL de acionamento. Vai precisar dele no passo seguinte.
   4. Clicar em Seguinte.

4. No ecrã Código:

   1. Escolha qualquer tempo de execução do Node.js
   2. Altere o Ponto de entrada para log
   3. No ficheiro index.js, substitua o código de exemplo 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');
   };
   

Pode avançar para o passo seguinte enquanto a função do Cloud Run é implementada.

Passo 3b: crie a subscrição

Apenas as contas de serviço que foram registadas no tópico Channel Services (Serviços de canal) (consulte o passo 2) podem criar uma subscrição.

Pode fazê-lo com código chamando a API Pub/Sub com as credenciais da sua conta de serviço. Certifique-se de que não se faz passar pelo superadministrador do domínio do revendedor, o que é necessário quando chama a Cloud Channel API.

Para efeitos deste codelab, vai usar a ferramenta CLI gcloud na Cloud Shell.

1. Clique em Ativar Cloud Shell na parte superior do Google Cloud console.

2. Quando a shell estiver pronta, execute o seguinte comando. Substitua os valores de SERVICE_ACCOUNT pelo endereço de email da sua conta de serviço, TOPIC pelo tópico criado no passo 2, e PUSH_ENDPOINT pelo URL de acionador da função do Cloud Run criada no passo 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 na 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 subscrição:

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

Pode confirmar que a subscrição está configurada acedendo à secção de subscrições do Pub/Sub.

Gere alguns dados

Depois de concluir os passos anteriores, está tudo pronto para receber dados.

A forma mais fácil é criar um cliente na Consola de vendas de parceiros e aprovisionar um produto. Se concluiu o codelab de aprovisionamento do Workspace ponto a ponto pode criar um cliente com o Google Workspace executando o código de exemplo.

Aceda à sua função na Google Cloud consola e abra o separador Registos. Segue-se um exemplo do que deve ver.

Nota: em casos raros, pode demorar alguns minutos até que a subscrição do Pub/Sub comece a receber eventos do tópico.

Limpar

• Elimine a função do Cloud Run
• Elimine a subscrição

O tópico é limpo automaticamente quando não tiver mais subscritores.

Passos seguintes

Este codelab explicou como os serviços de canal tiram partido do Pub/Sub para lhe permitir criar a sua integração de forma reativa e em grande escala.

Referência de eventos

Consulte a referência de RPC para ver a lista de eventos gerados pelos serviços de canal.

Referência da API

Este codelab usa a consola Google Cloud , mas pode executar estes passos de forma programática. Para isso:

• Use accounts.register para criar o tópico.
• Use as APIs Pub/Sub subscriptions.create para criar a subscrição do Pub/Sub.
• Consulte accounts.listSubscribers e accounts.unregister para ver pontos finais adicionais que pode usar na sua integração.

Garantias e práticas recomendadas do Pub/Sub

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

Práticas recomendadas para o ponto final de envio:

• Uma vez que as mensagens podem ser enviadas com atraso, fora de ordem ou várias vezes, o seu ponto final deve ser idempotente e usar customers.get e entitlements.get

• Embora o limite de tempo predefinido do Pub/Sub para o envio seja de 10 segundos (este pode ser aumentado através do ackDeadlineda subscrição do Pub/Sub), recomenda-se a utilização de uma arquitetura baseada em mensagens e que o ponto final responda o mais rapidamente possível.

• Se o seu ponto final estiver inativo ou devolver erros 5xx, o Pub/Sub vai tentar novamente. Pode encontrar mais informações sobre como receber mensagens através de push na documentação do Pub/Sub.

Se preferir usar o método pull, pode encontrar informações sobre como receber mensagens através do método pull na documentação do Pub/Sub.

Filtragem de eventos

Uma vez que as notificações dos serviços de canal incluem attributes, pode criar subscrições detalhadas criando subscrições específicas do Pub/Sub com filtragem do Pub/Sub.

Por exemplo, a filtragem com attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED" permite-lhe acompanhar todas as alterações de utilizadores do Google Workspace.