Notificações do Pub/Sub

Conclua o codelab de configuração da API para configurar um projeto do Google Cloud e criar uma conta de serviço para chamar a API Cloud Channel.
Recomendamos usar o Test Partner Sales Console para este codelab.
Conheça os conceitos do Pub/Sub.

Informações gerais

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

Isso é especialmente útil para:

refletir as alterações 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).
Detectar eventos críticos acionados pelos seus clientes de revenda. Por exemplo:
- Um cliente do Google Workspace aceitando os Termos de Serviço.
- Um cliente do Google Workspace verificando o domínio.
- Um cliente do Google Workspace adicionando usuários em um direito flexível.
- Um cliente do Google Workspace fazendo a transferência.

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

Ative a API Pub/Sub e prepare sua conta de serviço.
Crie um tópico do Pub/Sub. Esse tópico pertence ao Channel Services, e você especificará uma conta de serviço que pode criar uma assinatura.
Crie uma assinatura do Pub/Sub. Essa assinatura pode ser push usando webhooks (o método preferido) ou pull.

Para uma assinatura push, você hospedará um webhook que receberá os eventos emitidos pelo Channel Services:

Notificações push do Channel Services

Formato da notificação

Veja 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"
}

Esses 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. O endereço será semelhante a: service-account@project.iam.gserviceaccount.com.
Acesso a uma conta de superadministrador do domínio do revendedor (preferencialmente o Test Partner Sales Console).
O ID da sua conta. Acesse as 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 do papel = 'Editor do Pub/Sub') é suficiente para este codelab, mas convém usar privilégios mais refinados na integração de produção. Encontre detalhes completos dos papéis do IAM na página Controle de acesso do Pub/Sub.
Se você optar por aplicar um papel personalizado, precisará conceder a esse papel a permissão pubsub.subscriptions.create para criar assinaturas.

Pode haver um atraso após a aplicação desses papéis e permissões à sua conta.

Etapa 2: criar o tópico para sua conta

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

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

Você 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 postados.

Etapa 3: assinar o tópico

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

Assinatura push: você fornece um callback POST HTTP. O Pub/Sub o usará 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 que será registrada no Cloud Logging.

Enviar notificações do Channel Services para uma função do Cloud

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

Nesta etapa, criaremos uma função do Cloud que registrará as mensagens recebidas.

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

Na tela Code:

Escolha qualquer ambiente de execução do Node.js
Mude o Ponto de entrada para log.
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');
};

É possível prosseguir para a próxima etapa durante a implantação da função do Cloud.

Etapa 3b: criar a assinatura

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

Para fazer isso com o código, chame a API Pub/Sub com as credenciais da sua conta de serviço. Não falsifique a identidade do superadministrador do domínio de revendedor, que é obrigatório ao chamar a API Cloud Channel.

Para os fins deste codelab, você usará a ferramenta CLI gcloud no Cloud Shell.

Clique em Ativar o Cloud Shell na parte de cima do Console do Google Cloud.
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 acionador da função do Cloud criada na etapa 3a:
```
SERVICE_ACCOUNT=service-account@project.iam.gserviceaccount.com
TOPIC=projects/cloud-channel-pubsub/topics/C0123456-notify
PUSH_ENDPOINT=https://us-central1-project.cloudfunctions.net/pubsub
```

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

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 de assinaturas do Pub/Sub.

Gerar alguns dados

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

A maneira mais fácil é criar um cliente no Partner Sales Console e provisionar um produto. Se você tiver concluído o codelab de provisionamento completo do Workspace, crie um cliente com um Google Workspace executando o exemplo de código.

Acesse a função no console do Google Cloud e abra a guia Registros. Confira a seguir um exemplo do que será exibido.

Registros de amostra para eventos do Pub/Sub

Limpar

Excluir a Função do Cloud
Excluir a assinatura

O tópico será limpo automaticamente quando não tiver nenhum inscrito restante.

Próximas etapas

Este codelab ajudou você a descobrir como o Channel Services usa o Pub/Sub para permitir que você crie sua integração de maneira reativa e em grande escala.

Referência de eventos

Consulte a referência da RPC para ver a lista de eventos gerados pelo Channel Services.

Referência da API

Este codelab usa o console do Google Cloud, mas é possível executar essas 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 conhecer 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 entregues várias vezes.

Práticas recomendadas para o endpoint de push:

Como as mensagens podem ser atrasadas, enviadas fora de ordem ou enviadas várias vezes, seu 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 (pode ser aumentado com o 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. Encontre mais informações sobre como receber mensagens por push na documentação do Pub/Sub.

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

Filtragem de eventos

Como as notificações do Channel Services incluem attributes, é possível criar assinaturas refinadas criando assinaturas específicas do Pub/Sub com filtragem do Pub/Sub.

Por exemplo, filtrar com attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED" permite monitorar todas as mudanças de licenças por usuário do Google Workspace.