Notificações push

Visão geral

A API Revendedor usa a API Pub/Sub para entregar notificações push notificações sobre diferentes recursos do Google Workspace eventos de assinatura. Por exemplo, é possível configurar a fim de receber notificações quando os clientes status das assinaturas mudar.

Pré-requisitos

  • Ative a API Pub/Sub. para seu projeto do Google Cloud.
  • Conceda papéis de IAM do Pub/Sub à sua conta de serviço no do Google Cloud. A concessão do o papel roles/pubsub.editor for um bom meio-termo (fácil e não muito amplo), mas talvez você queira usar palavras-chave Permissões do Pub/Sub.

Criar um tópico

Para criar um tópico, é necessário se registrar na API do revendedor usando o método resellernotify.register. O método resellernotify.register usa o endereço de e-mail de uma conta de serviço como . Somente contas de serviço autorizadas por esse método podem assinar seus tópico recém-criado.

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/register
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

Uma resposta bem-sucedida retorna um código de status HTTP 200 e uma resposta JSON contendo o nome do tópico do Pub/Sub.

Veja a seguir um exemplo de resposta:

{
  "topicName": "projects/partner-watch/topics/C0abcdefg"
}

Para autorizar outras contas de serviço a usar seu tópico, chame resellernotify.register novamente.

Revogar acesso a uma conta de serviço

Com a API do revendedor, também é possível cancelar o registro de contas de serviço usando o endpoint resellernotify.unregister:

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/unregister
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

Inscrever-se em um tópico

Depois de criar o tópico do Pub/Sub, você precisa configurar como seu aplicativo consome seus eventos de alteração. Escolha uma das seguintes opções:

  • Assinatura push: você fornece um callback HTTP POST. Usos do Pub/Sub esse callback para notificar o aplicativo sobre novos eventos.
  • Assinatura pull: seu aplicativo faz periodicamente uma chamada HTTP para obter todas as alterações na fila.
.

Veja a seguir um exemplo de solicitação para assinar um tópico:

PUT https://pubsub.googleapis.com/v1/projects/PROJECT/subscriptions/SUBSCRIPTION_NAME
{
  "topic": "TOPIC_NAME"
  // Only needed for push configurations
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
  },
}

Substitua:

  • PROJECT: o projeto do Google Cloud
  • SUBSCRIPTION_NAME: um nome de identificação para o assinatura.
  • TOPIC_NAME: o tópico do Pub/Sub que você já criados.
  • PUSH_NOTIFICATION_ENDPOINT: sua notificação push endpoint do gerenciador.

Uma resposta bem-sucedida retorna um código de status HTTP 200. Confira a seguir exemplo de resposta: 

{
  "name": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME",
  "topic": "TOPIC_NAME",
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
    },
  "ackDeadlineSeconds": 10
}

Formatos de 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": {},
    "data": "eyJza3VfaWQiOiAiR29vZ2xlLUFwcHMtVW5saW1pdGVkIiwgImV2ZW50X3R5cGUiOiAiU1VCU0NSSVBUSU9OX0NBTkNFTExFRCIsICJjdXN0b21lcl9kb21haW5fbmFtZSI6ICJkb21haW4uY29tIiwgInN1YnNjcmlwdGlvbl9pZCI6ICIxMjM0NTY3IiwgImN1c3RvbWVyX2lkIjogIkMwYWJjZGVmIiwgIm1lc3NhZ2VfaWQiOiAiODY3NTMwOSIsICJwdWJsaXNoX3RpbWUiOiB7InNlY29uZHMiOiAxNDU3NzMxODQ2LCAibmFub3MiOiAzNDkwMDAwMDB9LCAicmVzZWxsZXJfY3VzdG9tZXJfaWQiOiAiQzByZXNlbGxlciJ9",
    "message_id": 1234567891012131
  },
  "subscription": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME"
}

Veja a seguir o exemplo de objeto message.data após a decodificação:

{
  "customer_id": "C0abcdef",
  "customer_domain_name": "domain.com",
  "event_type": "SUBSCRIPTION_CANCELLED",
  "sku_id": "Google-Apps-Unlimited",
  "subscription_id": "1234567",
  // Optional fields depended on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

Tipos de evento

A lista a seguir contém todos os tipos de evento possíveis:

  • NEW_SUBSCRIPTION_CREATED: uma nova assinatura foi criada.
  • SUBSCRIPTION_TRIAL_ENDED: o teste de uma assinatura terminou.
  • PRICE_PLAN_SWITCHED: o cliente passou de um plano flexível para um anual de um plano eficaz de resposta a incidentes. Esse evento não será acionado se o cliente fizer uma conversão para um plano flexível como parte de uma renovação.
  • COMMITMENT_CHANGED: o compromisso anual aumentou ou diminuiu.
  • SUBSCRIPTION_RENEWED: uma assinatura anual foi renovada.
  • SUBSCRIPTION_SUSPENDED: a assinatura foi suspensa. Consulte a subscription_suspension_reasons.
  • SUBSCRIPTION_SUSPENSION_REVOKED: a suspensão de uma assinatura suspensa foi revogada.
  • SUBSCRIPTION_CANCELLED: a assinatura foi cancelada. Consulte a subscription_cancellation_reason. Também pode ser usado para detectar transferências de dados.

  • SUBSCRIPTION_CONVERTED: a assinatura foi convertida. Alguns exemplos de casos de do evento são as seguintes:

    • Converter a assinatura direta em assinatura de revendedor.
    • Converta a assinatura paga em um período de carência.
    • Converter assinatura on-line em off-line.

  • SUBSCRIPTION_UPGRADE: o SKU da assinatura foi atualizado. Por exemplo, o upgrade da assinatura do Google Workspace Business Starter para o Business Padrão.

  • SUBSCRIPTION_DOWNGRADE: o SKU da assinatura sofreu downgrade. Por exemplo, o Fizemos downgrade da assinatura do Google Workspace Business Standard para Business Starter.

  • LICENSE_ASSIGNMENT_CHANGED: a licença foi atribuída ou revogada a partir de um usuário. Você pode usar esse evento para rastrear de forma reativa as alterações no número de assentos do Assinaturas flexíveis.

Motivos do cancelamento da assinatura

O motivo do cancelamento da assinatura é preenchido quando event_type é SUBSCRIPTION_CANCELLED. Confira a seguir os possíveis motivos para cancelamento:

  • TRANSFERRED_OUT: o cliente foi transferido para faturamento direto ou para outro revendedor.
  • PURCHASE_OF_SUBSUMING_SKU: o cliente fez upgrade para uma SKU que substitui outra. Por exemplo, se um cliente do Google Workspace Business Starter e Google Vault para o Google Workspace Business Plus, o A assinatura do Vault foi incluída porque está incluída no Google Workspace Business Plus.
  • RESELLER_INITIATED: o revendedor cancelou a assinatura.
  • OTHER: a assinatura foi cancelada por algum motivo não listado.

Motivos da suspensão da assinatura

O motivo da suspensão da assinatura é preenchido quando event_type é SUBSCRIPTION_SUSPENDED. Estes são os possíveis motivos da suspensão:

  • PENDING_TOS_ACCEPTANCE: o cliente não fez login e aceitou os Termos de Serviço de Revenda do Google Workspace.
  • RENEWAL_WITH_TYPE_CANCEL: o compromisso do cliente terminou e a o serviço foi cancelado ao fim da vigência.
  • RESELLER_INITIATED: o revendedor suspendeu manualmente a assinatura.
  • TRIAL_ENDED: o teste do cliente expirou, e o cliente não selecionou um plano que não seja de teste.
  • OTHER: o cliente está suspenso por um motivo interno do Google, por exemplo: por exemplo, abuso.

Limitações do Pub/Sub

A ordem das notificações push não é garantida. As mensagens podem ser entregues várias vezes e em situações extremas, não. Recomendamos usar reseller.subscriptions.get em todas as assinaturas alteradas para extrair o o estado atual.