Corrigir erros e reativar uma assinatura do Google Workspace

Nesta página, explicamos como reativar uma assinatura suspensa do Google Workspace resolvendo ou solucionando erros e chamando o método subscriptions.reactivate.

As assinaturas do Google Workspace são suspensas sempre que um erro impede que elas recebam eventos. Por exemplo, uma assinatura é suspensa quando não é possível encontrar o recurso de destino ou o endpoint de notificação. Depois de resolver os erros da assinatura, você poderá reativá-la para começar a receber eventos novamente.

Você pode saber mais sobre uma assinatura suspensa das seguintes maneiras:

  • Seu app recebe um evento de ciclo de vida sobre a suspensão. Se a assinatura for suspensa devido a um erro no endpoint, talvez você não receba um evento de ciclo de vida.
  • Use os métodos subscriptions.get ou subscriptions.list para verificar se o campo state da assinatura está definido como SUSPENDED.
  • Você recebe uma notificação sobre uma falha na entrega ao endpoint de notificação. Para saber como monitorar falhas de entrega em tópicos do Google Cloud Pub/Sub, consulte Processar falhas de mensagens.

As assinaturas reativadas mantêm a data de validade original. Para estender o prazo de validade de uma assinatura, consulte Atualizar ou renovar uma assinatura do Google Workspace.

Apps Script

  • Um projeto do Apps Script:
    • Use seu projeto do Google Cloud em vez do padrão criado automaticamente pelo Apps Script.
    • Para todos os escopos adicionados ao configurar a tela de permissão OAuth, você também precisa adicionar os escopos ao arquivo appsscript.json no seu projeto do Apps Script. Por exemplo, se você especificou o escopo chat.messages, adicione o seguinte: 
      • "oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages"
]
    • Ative o serviço avançado do Google Workspace Events.

Python

  • Python 3.6 ou mais recente
  • A ferramenta de gerenciamento de pacotes pip
  • As bibliotecas de cliente mais recentes do Google para Python. Para instalar ou atualizar, execute o seguinte comando na interface de linha de comando: 
      pip3 install --upgrade google-api-python-client google-auth-oauthlib

Identificar e resolver erros

Para identificar o erro de uma assinatura, revise o campo suspensionReason dela. Você pode encontrar esse campo quando receber um evento de ciclo de vida sobre a suspensão ou usando o método subscriptions.get para analisar todos os campos da assinatura.

A tabela a seguir mostra possíveis erros de uma assinatura e, quando possível, como resolvê-los. Se não for possível resolver o erro, exclua a assinatura ou aguarde a expiração dela. A API Google Workspace Events exclui automaticamente as assinaturas expiradas.

Erro Descrição Como resolver

USER_SCOPE_REVOKED

O usuário autorizador revogou a concessão de um ou mais escopos do OAuth necessários para a assinatura. Adquira outro token de acesso. Para mais detalhes, consulte Receber um token de acesso do servidor de autorização do Google.

RESOURCE_DELETED

O recurso de destino da assinatura é excluído. Se o recurso for restaurado, chame o método reactivate. Caso contrário, nenhuma ação é necessária, já que não é possível reativar uma assinatura sem o recurso de destino original.

USER_AUTHORIZATION_FAILURE

O usuário autorizador não tem mais acesso ao recurso da assinatura. Nenhuma ação é necessária. Não é possível reativar a assinatura porque o usuário que a autorizou não tem acesso ao recurso de destino.

ENDPOINT_PERMISSION_DENIED

O aplicativo do Google Workspace não tem acesso para entregar eventos ao seu endpoint de notificação. Conceda acesso à conta de serviço para o aplicativo do Google Workspace que entrega eventos.

Contas de serviço:
  • Eventos do Google Chat: chat-api-push@system.gserviceaccount.com
  • Eventos do Google Drive: drive-api-event-push@system.gserviceaccount.com
  • Eventos do Google Meet: meet-api-event-push@system.gserviceaccount.com

Para tópicos do Pub/Sub, conceda o papel de Publicador do Pub/Sub (roles/pubsub.publisher) ) à conta de serviço.

ENDPOINT_NOT_FOUND

O endpoint de notificação não existe ou não foi encontrado. Verifique se o endpoint ainda está ativo e funcionando. Para resolver problemas com tópicos do Pub/Sub, consulte a documentação de solução de problemas.

ENDPOINT_RESOURCE_EXHAUSTED

O endpoint de notificação não recebeu eventos devido a cota insuficiente ou limitação de taxa. Solicitar um aumento da cota.

APP_SCOPE_REVOKED

O administrador do domínio revogou a concessão de um ou mais escopos do OAuth para o app Chat. Receber aprovação do administrador.

APP_AUTHORIZATION_FAILURE

O app do Chat que autorizou a criação da assinatura não tem mais acesso ao recurso de destino dela. Recupere o acesso ao recurso de destino. Por exemplo, se o recurso de destino for um espaço do Chat, o app Chat poderá precisar de uma assinatura do espaço.

Reativar uma assinatura

Depois de resolver o erro que suspendeu sua assinatura, use o método reactivate para permitir que ela receba eventos novamente. O método verifica se todos os erros foram resolvidos e muda o campo state da assinatura de SUSPENDED para ACTIVE.

Para reativar uma assinatura do Google Workspace:

Apps Script

  1. No projeto do Apps Script, crie um arquivo de script chamado reactivateSubscription e adicione o seguinte código:

    function reactivateSubscription() {
  // The name of the subscription to reactivate.
  const name = 'subscriptions/SUBSCRIPTION_ID';

  // Call the Workspace Events API using the advanced service.
  const response = WorkspaceEvents.Subscriptions.reactivate({}, name);
  console.log(response);
}

    Substitua:

    • SUBSCRIPTION_ID: o ID da assinatura. Para conseguir o ID, use uma destas opções:
      • O valor do campo uid.
      • O ID do nome do recurso representado no campo name. Por exemplo, se o nome do recurso for subscriptions/subscription-123, use subscription-123.

  2. Para reativar a assinatura do Google Workspace, execute a função reactivateSubscription no seu projeto do Apps Script.

Python

  1. No diretório de trabalho, crie um arquivo chamado reactivate_subscription.py e adicione o seguinte código:

    """Reactivate subscription."""

from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [SCOPES]

# Authenticate with Google Workspace and get user authentication.
flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
CREDENTIALS = flow.run_local_server()

# Call the Workspace Events API using the service endpoint.
service = build(
    'workspaceevents',
    'v1',
    credentials=CREDENTIALS,
)

NAME = 'subscriptions/SUBSCRIPTION_ID'
response = service.subscriptions().reactivate(name=NAME).execute()
print(response)

    Substitua:

    • SCOPES: um ou mais escopos do OAuth que oferecem suporte a cada tipo de evento da assinatura. Formatado como uma matriz de strings. Para listar vários escopos, separe-os por vírgulas. Por exemplo, 'https://www.googleapis.com/auth/chat.spaces.readonly', 'https://www.googleapis.com/auth/chat.memberships.readonly'.
    • SUBSCRIPTION_ID: o ID da assinatura. Para conseguir o ID, use uma destas opções:
      • O valor do campo uid.
      • O ID do nome do recurso representado no campo name. Por exemplo, se o nome do recurso for subscriptions/subscription-123, use subscription-123.

  2. No seu diretório de trabalho, verifique se você armazenou as credenciais de ID do cliente OAuth e nomeou o arquivo como credentials.json. O exemplo de código usa esse arquivo JSON para autenticar com o Google Workspace e receber credenciais de usuário. Para instruções, consulte Criar credenciais de ID do cliente OAuth.

  3. Para reativar a assinatura do Google Workspace, execute o seguinte comando no terminal:

    python3 reactivate_subscription.py
A API Google Workspace Events retorna uma operação de longa duração que contém a instância do recurso Subscription.

Se a solicitação falhar, consulte a seção a seguir para resolver outros erros.

Reativar uma assinatura como um app do Google Chat

Você pode reativar uma assinatura de eventos do Chat como um app do Chat em vez de como um usuário. O processo é semelhante, exceto:

  1. Em vez da autenticação do usuário, autentique como um app do Chat com aprovação única do administrador.

  2. Especifique os escopos de autorização que permitem que o app do Chat se inscreva em eventos do Chat. Esses escopos de autorização sempre começam com chat.app e incluem o seguinte:

    • https://www.googleapis.com/auth/chat.app.memberships: inscrever-se em eventos de membros do espaço do Chat.
    • https://www.googleapis.com/auth/chat.app.messages.readonly: Inscreva-se em eventos de mensagens e reações do espaço do Chat.
    • https://www.googleapis.com/auth/chat.app.spaces: Assine eventos do espaço do Chat.

crie uma chave de API

Para chamar um método da API Developer Preview, use uma versão não pública do documento de descoberta da API. Para autenticar a solicitação, transmita uma chave de API.

Para criar a chave de API, abra o projeto do Google Cloud do app e faça o seguinte:

  1. No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.

    Ir para Credenciais

  2. Clique em Criar credenciais > Chave de API.
  3. Sua nova chave de API é exibida.
    • Clique em Copiar para copiar a chave de API e usar no código do app. A chave de API também pode ser encontrada na seção "Chaves de API" das credenciais do seu projeto.
    • Para evitar o uso não autorizado, recomendamos restringir os locais e as APIs em que a chave de API pode ser usada. Para mais detalhes, consulte Adicionar restrições de API.

Escrever um script que chama a API Google Workspace Events

O exemplo de código a seguir reativa uma assinatura do Google Workspace de um app do Chat:

Python 

  """Reactivate subscription."""

  from google.oauth2 import service_account
  from apiclient.discovery import build

  # Specify required scopes.
  SCOPES = [SCOPES]

  # Specify service account details.
  CREDENTIALS = (
      service_account.Credentials.from_service_account_file('credentials.json')
      .with_scopes(SCOPES)
  )

  # Call the Workspace Events API using the service endpoint.
  service = build(
      'workspaceevents',
      'v1beta',
      credentials=CREDENTIALS,
      discoveryServiceUrl='https://workspaceevents.googleapis.com/$discovery/rest?version=v1beta&labels=DEVELOPER_PREVIEW&key=API_KEY',
  )

  NAME = 'subscriptions/SUBSCRIPTION_ID'
  response = service.subscriptions().reactivate(name=NAME).execute()
  print(response)

Substitua:

  • SCOPES: especifique escopos de autorização que permitam que o app do Chat se inscreva em eventos do Chat. Esses escopos de autorização sempre começam com chat.app e incluem o seguinte:

    • https://www.googleapis.com/auth/chat.app.memberships: inscrever-se em eventos de membros do espaço do Chat.
    • https://www.googleapis.com/auth/chat.app.messages.readonly: Inscreva-se em eventos de mensagens e reações do espaço do Chat.
    • https://www.googleapis.com/auth/chat.app.spaces: Assine eventos do espaço do Chat.

  • API_KEY: a chave de API que você criou para criar o endpoint de serviço da API Google Workspace Events.

  • SUBSCRIPTION_ID: o ID da assinatura. Para receber o ID, use qualquer uma das seguintes opções:

    • O valor do campo uid.
    • O ID do nome do recurso representado no campo name. Por exemplo, se o nome do recurso for subscriptions/subscription-123, use subscription-123.

Resolver vários erros

Se você resolveu o erro que suspendeu a assinatura e o método reactivate falhar, outro erro pode ter ocorrido depois que a assinatura foi suspensa.

Para identificar outros erros, analise a saída da solicitação com falha. A saída contém todos os erros que ainda estão presentes.

Quando a assinatura tem vários erros, o valor do campo suspensionReason sempre usa o erro original que suspendeu a assinatura.