Esta página foi traduzida pela API Cloud Translation.

Notificações push

Visão geral

A API Reseller usa a API Pub/Sub para enviar notificações push sobre diferentes eventos de assinatura do Google Workspace. Por exemplo, você pode configurar notificações push para receber alertas quando o status da assinatura dos seus clientes mudar.

Pré-requisitos

Ative a API Pub/Sub para seu projeto do Google Cloud.
Conceda papéis do IAM do Pub/Sub à sua conta de serviço no projeto do Cloud. Conceder o papel roles/pubsub.editor é um bom compromisso (fácil e não muito amplo), mas talvez seja melhor usar permissões do Pub/Sub mais específicas.

Criar um tópico

Para criar um tópico, registre-se na API Reseller usando o método resellernotify.register. O método resellernotify.register usa um endereço de e-mail de conta de serviço como um parâmetro. Somente as contas de serviço autorizadas por esse método podem se inscrever no 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 o acesso de uma conta de serviço

A API Reseller também permite 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"
}

Assinar um tema

Depois de criar o tópico do Pub/Sub, configure como seu aplicativo consome os eventos de mudança. Escolha uma das seguintes opções:

Assinatura por push: você fornece um callback HTTP POST. O Pub/Sub usa esse callback para notificar seu aplicativo sobre novos eventos.
Assinatura de pull: seu aplicativo faz periodicamente uma chamada HTTP para receber todas as mudanças enfileiradas.

Confira um exemplo de solicitação para se inscrever em 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 sua assinatura.
TOPIC_NAME: o tópico do Pub/Sub que você criou antes.
PUSH_NOTIFICATION_ENDPOINT: o endpoint do manipulador de notificações push.

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

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

Formatos de notificação

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

Confira abaixo o objeto message.data de exemplo 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 eventos possíveis:

NEW_SUBSCRIPTION_CREATED: uma nova assinatura foi criada.
SUBSCRIPTION_TRIAL_ENDED: o teste de uma assinatura terminou.
PRICE_PLAN_SWITCHED: o cliente mudou de um plano flexível para um plano anual. Esse evento não é acionado se o cliente fizer a conversão de um plano com compromisso para um plano flexível como parte de uma renovação.
COMMITMENT_CHANGED: o compromisso anual foi aumentado ou reduzido.
SUBSCRIPTION_RENEWED: uma assinatura anual foi renovada.
SUBSCRIPTION_SUSPENDED: a assinatura está suspensa. Consulte o campo subscription_suspension_reasons.
SUBSCRIPTION_SUSPENSION_REVOKED: a suspensão de uma assinatura que já estava suspensa foi revogada.
SUBSCRIPTION_CANCELLED: a assinatura foi cancelada. Consulte o campo subscription_cancellation_reason. Também pode ser usado para detectar transferências.
SUBSCRIPTION_CONVERTED: a assinatura foi convertida. Alguns exemplos de casos para esse evento são:
- Converter uma assinatura direta em uma de revendedor.
- Converter uma assinatura paga em uma oferta de carência.
- Converter uma assinatura on-line em uma off-line.
SUBSCRIPTION_UPGRADE: a SKU de assinatura foi atualizada. Por exemplo, a assinatura foi atualizada do Google Workspace Business Starter para o Business Standard.
SUBSCRIPTION_DOWNGRADE: o downgrade da SKU de assinatura foi concluído. Por exemplo, a assinatura foi reduzida do Google Workspace Business Standard para o Business Starter.
LICENSE_ASSIGNMENT_CHANGED: a licença foi atribuída ou revogada de um usuário. É possível usar esse evento para rastrear de forma reativa as mudanças na contagem de assentos das assinaturas flexíveis.

Motivos de cancelamento de assinaturas

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

TRANSFERRED_OUT: o cliente fez a transferência para o 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 com o Google Workspace Business Starter e upgrades do Google Vault fizer upgrade para o Google Workspace Business Plus, a assinatura do Vault será incorporada porque está incluída no Google Workspace Business Plus.
RESELLER_INITIATED: o revendedor cancelou a assinatura.
OTHER: a assinatura foi cancelada por um motivo diferente dos listados.

Motivos para a suspensão de assinaturas

O motivo da suspensão da assinatura é preenchido quando o event_type é SUBSCRIPTION_SUSPENDED. Confira abaixo os possíveis motivos para suspensão:

PENDING_TOS_ACCEPTANCE: o cliente não fez login nem aceitou os Termos de Serviço revendidos do Google Workspace.
RENEWAL_WITH_TYPE_CANCEL: o compromisso do cliente terminou e o serviço foi cancelado ao fim do período.
RESELLER_INITIATED: o revendedor suspendeu manualmente a assinatura.
TRIAL_ENDED: o teste do cliente expirou, e ele não selecionou um plano sem teste.
OTHER: o cliente foi suspenso por um motivo interno do Google, como 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 serem entregues. Recomendamos usar reseller.subscriptions.get em todas as assinaturas alteradas para extrair o estado atual.