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:
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
, insiraaccounts/ACCOUNT_ID
, substituindoACCOUNT_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.
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:
- Mude o nome da função. Se quiser, escolha outra região.
- No acionador HTTP, altere a Autenticação para Permitir invocações não autenticadas e clique em Salvar.
- Anote o URL do acionador. Você precisará dessa informação na próxima etapa.
- 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 ePUSH_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.
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
eaccounts.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
eentitlements.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.