Notificações do Pub/Sub

• Não se esqueça de preencher Codelab de configuração da API para configurar uma no projeto do Google Cloud e criar uma conta de serviço para chamar o a API Cloud Channel.

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

• Saiba mais sobre o Pub/Sub diferentes.

Visão geral

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

Isso é especialmente útil 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 que são 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 a um direito flexível.
  • Um cliente do Google Workspace 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 pertence ao Channel Services e especificar uma conta de serviço que possa criar uma assinatura.

3. Crie uma assinatura do Pub/Sub. Esta assinatura pode ser push usando webhooks (o método preferido) ou pull.

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

Formato da notificação

Veja a seguir um exemplo de notificação do Pub/Sub. Os dados da mensagem são transmitida 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 projeto. Este endereço será assim: [e-mail].
• Acesso a uma conta de superadministrador do domínio do revendedor (de preferência seu testar o Partner Sales Console).
• O ID da sua conta. Você pode encontrar isso nas configurações do seu 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 à conta de serviço o papel de IAM do Pub/Sub no projeto. Conceder roles/pubsub.editor (nome do papel = "Editor do Pub/Sub") já é suficiente. para este codelab, mas recomendamos que você use privilégios mais refinados em sua integração de produção. Você pode encontrar detalhes completos do papel do IAM na Controle de acesso do Pub/Sub.
• Se você optar por aplicar um papel personalizado, precisará conceder a ele o pubsub.subscriptions.create para criar assinaturas.

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

Cuidado: você receberá erros 403 se não houver papéis do IAM no serviço conta.

Etapa 2: criar o tópico para sua conta

Para criar o tópico do Pub/Sub, você precisa usar o accounts.register. Esse método usa um e-mail da 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 o accounts.register documentação e clique em Testar.
2. No campo account, digite accounts/ACCOUNT_ID, substituindo ACCOUNT_ID pelo ID da 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 postados.

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

Etapa 3: inscrever-se no tópico

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

• Assinatura push: você fornece um callback HTTP POST. O Pub/Sub vai use 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 Push e enviar todos os eventos para um Função do Cloud Run que será registrada no Cloud Logging.

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

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

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

4. Na tela Código:

   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 com um código, chame a API Pub/Sub com seu serviço credenciais da conta de serviço. Verifique se você não falsifica a identidade do seu domínio de revendedor Superadministrador, 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 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 criado 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
   

Você pode confirmar se a assinatura está configurada em Seção de 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ê concluiu o Codelab completo de provisionamento do Workspace é possível criar um cliente com um Google Workspace executando o exemplo o código-fonte.

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

Observação :em casos raros, pode demorar alguns minutos para que o Pub/Sub para começar 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 houver nenhum para os assinantes restantes.

Próximas etapas

Este codelab mostrou como o Channel Services usa os recursos o Pub/Sub para que você possa criar 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 você pode realizar essas etapas de forma programática. Para fazer isso, siga estas etapas:

• Use accounts.register para criar o tópico.
• Usar API Pub/Sub subscriptions.create para criar a assinatura do Pub/Sub.
• Consulte accounts.listSubscribers e accounts.unregister para endpoints adicionais que você pode usar em sua integração.

Garantias e práticas recomendadas do Pub/Sub

O atraso entre um evento e sua 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 endpoints de push:

• Como as mensagens podem atrasar, serem enviadas fora de ordem ou várias vezes, seu endpoint deve ser idempotente e usar customers.get e entitlements.get

• Embora o tempo limite padrão do Pub/Sub para push seja de 10 segundos Esse valor pode ser aumentado pela ackDeadline), recomenda-se usar uma arquitetura baseada em mensagens e garantir para que o endpoint responda o mais rápido possível.

• Se o endpoint estiver inativo ou retornar erros 5xx, o Pub/Sub tentar de novo. Você pode encontrar mais informações sobre como receber mensagens por push na documentação do Pub/Sub.

Se você preferir usar pull, encontre 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, você pode criar para assinaturas refinadas com a criação do Pub/Sub assinaturas com Filtragem do Pub/Sub.

Por exemplo, filtrar com attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED" permite que você monitore todas Mudanças de licenças no Google Workspace.