Receber e responder a eventos de ciclo de vida das assinaturas do Google Workspace

Esta página explica os eventos de ciclo de vida que você recebe para assinaturas do Google Workspace e como usá-los para manter uma assinatura ativa.

A API Google Workspace Events envia os seguintes tipos de eventos de ciclo de vida:

O app precisa processar explicitamente esses tipos de eventos de ciclo de vida e ignorar novos tipos de eventos que possam aparecer no futuro.

Os eventos de ciclo de vida da API Google Workspace Events são estruturados de acordo com a especificação do CloudEvents. Para saber mais, consulte Estrutura dos eventos do Google Workspace.

Eventos de suspensão

Quando ocorre um erro em uma assinatura do Google Workspace, a API Google Workspace Events suspende a assinatura e impede que ela receba eventos. É necessário resolver os erros da assinatura antes de reativá-la.

Para notificar você sobre uma suspensão, a API Google Workspace Events envia um evento de ciclo de vida com o tipo de evento google.workspace.events.subscription.v1.suspended.

Depois de receber um evento de suspensão, você pode saber o motivo da suspensão, resolver erros e reativar a assinatura. Para mais detalhes, consulte Resolver erros e reativar uma assinatura do Google Workspace.

O exemplo a seguir mostra um CloudEvent para um evento de ciclo de vida sobre uma assinatura do Google Workspace que foi suspensa devido ao erro ENDPOINT_PERMISSION_DENIED:

{
  "id": "EVENT_UUID",
  "source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
  "subject": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
  "type": "google.workspace.events.subscription.v1.suspended",
  "time": "2023-06-08T06:50:43.641299Z",
  "spec_version": '1.0',
  "datacontenttype": "application/json",
  "data": {
    "subscription":{
      "name": "subscriptions/SUBSCRIPTION_ID",
      "suspension_reason": "ENDPOINT_PERMISSION_DENIED",
      ...
    }
  }
}

Eventos de lembrete de vencimento

Depois que uma assinatura expirar, a API Google Workspace Events vai excluí-la permanentemente, e não será possível renová-la ou reativá-la.

Para notificar você sobre uma assinatura que está prestes a expirar, a API Google Workspace Events envia eventos de ciclo de vida 12 horas e uma hora antes do horário de expiração. O tipo de evento para eventos de ciclo de vida é google.workspace.events.subscription.v1.expirationReminder.

Quando você receber um evento de lembrete de expiração, use o método subscriptions.update() para atualizar o tempo de expiração. Confira mais detalhes em Atualizar ou renovar uma assinatura do Google Workspace.

O exemplo a seguir mostra um CloudEvent para um evento de ciclo de vida sobre uma assinatura do Google Workspace que está prestes a expirar:

{
  "id": "EVENT_UUID",
  "source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
  "subject": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
  "type": "google.workspace.events.subscription.v1.expirationReminder",
  "time": "2023-06-08T06:50:43.641299Z",
  "spec_version": '1.0',
  "datacontenttype": "application/json",
  "data": {
    "subscription":{
      "name": "subscriptions/SUBSCRIPTION_ID",
      "expire_time": "2023-06-08T18:50:43.641299Z",
      ...
    }
  }
}

Eventos de assinatura expirada

A API Google Workspace Events envia um evento do ciclo de vida quando a assinatura expira. O tipo de evento para este evento de ciclo de vida é google.workspace.events.subscription.v1.expired.

A API Google Workspace Events exclui permanentemente as assinaturas expiradas. Se a assinatura expirar, use o método subscriptions.create() para criar outra. Confira mais detalhes em Criar uma assinatura do Google Workspace.

O exemplo a seguir mostra um CloudEvent para um evento de ciclo de vida sobre uma assinatura do Google Workspace expirada:

{
  "id": "EVENT_UUID",
  "source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
  "subject": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
  "type": "google.workspace.events.subscription.v1.expired",
  "time": "2023-06-08T07:00:00.000000Z",
  "spec_version": '1.0',
  "datacontenttype": "application/json",
  "data": {
    "subscription":{
      "name": "subscriptions/SUBSCRIPTION_ID",
      "expire_time": "2023-06-08T07:00:00.000000Z",
      ...
    }
  }
}