Notificações Push

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Este documento descreve como usar notificações push que informam ao seu aplicativo quando um recurso muda.

Visão geral

A API SDK Admin fornece notificações push que permitem observar as mudanças nos recursos. Use esse recurso para melhorar o desempenho do aplicativo. Ele permite que você elimine os custos extras de rede e computação envolvidos com os recursos de pesquisa para determinar se eles mudaram. Sempre que um recurso monitorado muda, a API Admin SDK notifica o aplicativo.

Para usar notificações push, é necessário fazer duas coisas:

  • Configure o URL de recebimento ou o receptor de callback "Webhook".

    Esse é um servidor HTTPS que processa as mensagens de notificação da API acionadas quando um recurso muda.

  • Configure um canal de notificação para cada endpoint de recurso que você quer observar.

    Um canal especifica informações de roteamento para mensagens de notificação. Como parte da configuração do canal, você identifica o URL específico em que quer receber notificações. Sempre que o recurso de um canal muda, a API Admin SDK envia uma mensagem de notificação como uma solicitação POST para esse URL.

No momento, a API SDK Admin é compatível com notificações de mudanças no recurso Atividades.

Como criar canais de notificação

Para solicitar notificações push, é necessário configurar um canal de notificação para cada recurso que você quer assistir. Depois que os canais de notificação são configurados, a API Admin SDK informa o aplicativo quando qualquer recurso monitorado muda.

Como fazer solicitações de exibição

Cada recurso verificável da API Admin SDK tem um método watch associado em um URI com o seguinte formato:

https://www.googleapis.com/apiName/apiVersion/resourcePath/watch

Para configurar um canal de notificação para mensagens sobre alterações em um recurso específico, envie uma solicitação POST para o método watch do recurso.

Cada canal de notificação é associado a um determinado usuário e um recurso específico (ou a um conjunto de recursos). Uma solicitação watch não terá êxito a menos que o usuário ou a conta de serviço atual sejam proprietários ou tenham permissão para acessar esse recurso.

Exemplos

Todas as solicitações de observação para o recurso "Atividades" têm o formato geral:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/userKey or all/applications/applicationName/watch
Authorization: Bearer auth_token_for_current_user
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token.
  "payload": true, // (Optional) Whether to include the payload (message body) in notifications.
  "expiration": 3600 // (Optional) Your requested channel expiration time.
}

É possível usar os parâmetros userKey, applicationName, eventName e filters para receber notificações somente de eventos, usuários ou aplicativos específicos.

Observação:os exemplos a seguir omitem o corpo da solicitação para maior clareza.

Monitorar todas as atividades administrativas:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch

Fique de olho em todas as atividades do Documentos Google:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch

Monitorar a atividade de um administrador específico de um usuário:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch

Procurar um evento específico, como alterar a senha de um usuário:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD

Procurar alterações em um documento específico:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch?eventName=EDIT&filters==doc_id=123456abcdef

Propriedades obrigatórias

Para cada solicitação watch, é necessário informar o seguinte:

  • Uma string de propriedade id que identifica exclusivamente esse novo canal de notificação no projeto. Recomendamos o uso de um identificador universalmente exclusivo (UUID) ou qualquer string exclusiva semelhante. Tamanho máximo: 64 caracteres.

    O valor do ID definido é retornado ao cabeçalho HTTP X-Goog-Channel-Id de cada mensagem de notificação que você receber para esse canal.

  • Uma string da propriedade type definida como o valor web_hook.

  • Uma string de propriedade address definida como o URL que detecta e responde a notificações desse canal. Esse é o URL de callback do webhook e precisa usar HTTPS.

    A API Admin SDK só poderá enviar notificações para esse endereço HTTPS se houver um certificado SSL válido instalado no seu servidor da Web. Certificados inválidos incluem:

    • Certificados autoassinados.
    • Certificados assinados por uma fonte não confiável.
    • Certificados que foram revogados
    • Certificados com um assunto que não corresponde ao nome do host de destino.

Propriedades opcionais

Também é possível especificar esses campos opcionais com sua solicitação watch:

  • Uma propriedade token que especifica um valor de string arbitrário para usar como um token de canal. Você pode usar os tokens do canal de notificação para várias finalidades. Por exemplo, você pode usar o token para verificar se cada mensagem recebida é de um canal criado pelo aplicativo, para garantir que a notificação não seja falsificada, ou rotear a mensagem para o destino correto no seu aplicativo com base na finalidade deste canal. Comprimento máximo: 256 caracteres.

    O token é incluído no cabeçalho HTTP X-Goog-Channel-Token em cada mensagem de notificação que seu aplicativo recebe para esse canal.

    Se você usa tokens do canal de notificação, recomendamos o seguinte:

    • Use um formato de codificação extensível, como parâmetros de consulta de URL. Exemplo: forwardTo=hr&createdBy=mobile

    • Não inclua dados confidenciais, como tokens OAuth.

  • Uma string da propriedade expiration definida como um carimbo de data/hora Unix (em ms) da data e hora em que você quer que a API Admin SDK pare de enviar mensagens para esse canal de notificação.

    Se um canal tiver um prazo de validade, ele será incluído como o valor do cabeçalho HTTP X-Goog-Channel-Expiration (desta vez em formato legível) em todas as mensagens de notificação que seu aplicativo recebe para esse canal.

Para mais detalhes sobre a solicitação, consulte o método watch para o recurso Atividades na referência da API.

Resposta do relógio

Se a solicitação watch criar um canal de notificação, ela retornará um código de status HTTP 200 OK.

O corpo da mensagem da resposta do relógio fornece informações sobre o canal de notificação que você acabou de criar, conforme mostrado no exemplo abaixo.

{
  "kind": "api#channel",
  "id": "reportsApiId", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 3600, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

Além das propriedades que você enviou como parte da sua solicitação, as informações retornadas também incluem o resourceId e a resourceUri para identificar o recurso que está sendo monitorado nesse canal de notificação.

Você pode transmitir as informações retornadas para outras operações do canal de notificação, como quando quer parar de receber notificações.

Para mais detalhes sobre a resposta, consulte o método watch para o recurso Atividades na referência da API.

Sincronizar mensagem

Depois de criar um novo canal de notificação para assistir a um recurso, a API SDK Admin envia uma mensagem sync para indicar que as notificações estão iniciando. O valor do cabeçalho HTTP X-Goog-Resource-State para essas mensagens é sync. Devido a problemas de tempo da rede, é possível receber a mensagem sync mesmo antes de receber a resposta do método watch.

Você pode ignorar a notificação sync, mas também é possível usá-la. Por exemplo, se você decidir que não quer manter o canal, pode usar os valores X-Goog-Channel-ID e X-Goog-Resource-ID em uma chamada para parar de receber notificações. Você também pode usar a notificação sync para fazer alguma inicialização e se preparar para eventos posteriores.

Veja abaixo o formato de mensagens sync que a API Admin SDK envia ao URL de recebimento.

POST https://mydomain.com/notifications // Your receiving URL.
X-Goog-Channel-ID: channel-ID-value
X-Goog-Channel-Token: channel-token-value
X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format; present only if channel expires.
X-Goog-Resource-ID: identifier-for-the-watched-resource
X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource
X-Goog-Resource-State: sync
X-Goog-Message-Number: 1

As mensagens de sincronização sempre têm um valor de cabeçalho HTTP X-Goog-Message-Number de 1. Cada notificação subsequente para esse canal terá um número de mensagem maior que o anterior, embora os números de mensagens não sejam sequenciais.

Renovar canais de notificação

Um canal de notificação pode ter um prazo de validade, com um valor determinado pela sua solicitação ou por quaisquer limites ou padrões internos da API Admin SDK (o valor mais restritivo é usado). O prazo de validade do canal, se tiver um, será incluído como um carimbo de data/hora Unix (em ms) nas informações retornadas pelo método watch. Além disso, a data e a hora de expiração são incluídas (em formato legível) em todas as mensagens de notificação que seu aplicativo recebe para este canal no cabeçalho HTTP X-Goog-Channel-Expiration.

No momento, não há como renovar um canal de notificação automaticamente. Quando um canal estiver perto da expiração, crie um novo chamando o método watch. Como sempre, é necessário usar um valor exclusivo para a propriedade id do novo canal. Provavelmente, haverá um período de tempo acima do qual os dois canais de notificação para o mesmo recurso estão ativos.

Como receber notificações

Sempre que um recurso monitorado é alterado, seu aplicativo recebe uma mensagem de notificação descrevendo a mudança. A API Admin SDK envia essas mensagens como solicitações POST para HTTPS para o URL especificado como "address" para este canal de notificação.

Noções básicas sobre o formato das mensagens de notificação

Todas as mensagens de notificação incluem um conjunto de cabeçalhos HTTP com prefixos X-Goog-. Alguns tipos de notificação também podem incluir um corpo de mensagem.

Cabeçalhos

As mensagens de notificação postadas pela API Admin SDK para seu URL de recebimento incluem os seguintes cabeçalhos HTTP:

Cabeçalho Descrição
Sempre presente
X-Goog-Channel-ID UUID ou outra string exclusiva fornecida para identificar esse canal de notificação.
X-Goog-Message-Number Número inteiro que identifica essa mensagem para esse canal de notificação. O valor é sempre 1 para mensagens sync. Os números de mensagens aumentam para cada mensagem subsequente no canal, mas não são sequenciais.
X-Goog-Resource-ID Um valor opaco que identifica o recurso monitorado. Esse ID é estável em todas as versões da API.
X-Goog-Resource-State O novo estado do recurso, que acionou a notificação. Valores possíveis: sync ou um nome de evento.
X-Goog-Resource-URI Um identificador específico da versão da API para o recurso monitorado.
Às vezes presente
X-Goog-Channel-Expiration Data e hora de expiração do canal de notificação, expressas em formato legível. Presente apenas se definido.
X-Goog-Channel-Token Token do canal de notificação que foi definido pelo seu aplicativo e que você pode usar para verificar a origem da notificação. Presente apenas se definido.

As mensagens de notificação para atividades contêm as seguintes informações no corpo da solicitação:

Propriedade Descrição
kind Identifica isso como um recurso de atividade. Valor: a string fixa "admin#reports#activity".
id Identificador exclusivo do registro de atividade.
id.time Hora de ocorrência da atividade. O valor está no formato ISO 8601 de data e hora. A hora é a data completa mais os horários, minutos e segundos no formato AAAA-MM-DDThh:mm:ssTZD. Por exemplo, 2010-04-05T17:30:04+01:00.
id.uniqueQualifier Qualificador exclusivo se vários eventos tiverem o mesmo tempo.
id.applicationName Nome do aplicativo ao qual o evento pertence. Os valores possíveis são os seguintes:
id.customerId Identificador exclusivo de uma conta do Google Workspace.
actor O usuário está realizando a ação.
actor.callerType O tipo de autor que realizou a atividade listada no relatório. Nesta versão da API, o callerType é a solicitação da entidade USER ou OAuth 2LO que realizou a ação listada no relatório .
actor.email Endereço de e-mail principal do usuário cujas atividades estão sendo informadas.
actor.profileId O ID exclusivo do perfil do Google Workspace do usuário.
ownerDomain Domínio do Admin Console ou o proprietário do documento do aplicativo Documentos. Este é o domínio afetado pelo evento do relatório.
ipAddress Endereço IP do usuário que realiza a ação. Este é o endereço IP do usuário ao fazer login no Google Workspace, que pode ou não refletir a localização física do usuário. Por exemplo, o endereço IP pode ser do servidor do proxy do usuário ou de uma rede privada virtual (VPN). A API é compatível com IPv4 e IPv6.
events[] Eventos de atividade no relatório.
events[].type Tipo de evento. O serviço ou o recurso do Google Workspace alterado por um administrador é identificado na propriedade type, que identifica um evento usando a propriedade eventName.
events[].name Nome do evento. É o nome específico da atividade informada pela API. Cada eventName está relacionada a um serviço ou recurso específico do Google Workspace que a API organiza em tipos de evento.
Para parâmetros de solicitação eventName em geral:
  • Se nenhum eventName for informado, o relatório retornará todas as instâncias possíveis de um eventName.
  • Quando você solicita um eventName, a resposta da API retorna todas as atividades que contêm esse eventName. É possível que as atividades retornadas tenham outras propriedades do eventName além da solicitada.
events[].parameters[] Pares de valor de parâmetro para vários aplicativos.
events[].parameters[].name O nome do parâmetro.
events[].parameters[].value Valor da string do parâmetro.
events[].parameters[].intValue Valor inteiro do parâmetro.
events[].parameters[].boolValue Valor booleano do parâmetro.

Exemplos

As mensagens de notificação para eventos de recurso de atividade têm o formato geral:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: reportsApiId
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName
X-Goog-Resource-State:  eventName
X-Goog-Message-Number: 10

{
  "kind": "admin#reports#activity",
  "id": {
    "time": datetime,
    "uniqueQualifier": long,
    "applicationName": string,
    "customerId": string
  },
  "actor": {
    "callerType": string,
    "email": string,
    "profileId": long
  },
  "ownerDomain": string,
  "ipAddress": string,
  "events": [
    {
      "type": string,
      "name": string,
      "parameters": [
        {
          "name": string,
          "value": string,
          "intValue": long,
          "boolValue": boolean
        }
      ]
    }
  ]
}

Um exemplo de evento de atividade do administrador:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 596
X-Goog-Channel-ID: reportsApiId
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret987df98743md8g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json
X-Goog-Resource-State:  CREATE_USER
X-Goog-Message-Number: 23

{
  "kind": "admin#reports#activity",
  "id": {
    "time": "2013-09-10T18:23:35.808Z",
    "uniqueQualifier": "-0987654321",
    "applicationName": "admin",
    "customerId": "ABCD012345"
  },
  "actor": {
    "callerType": "USER",
    "email": "admin@example.com",
    "profileId": "0123456789987654321"
  },
  "ownerDomain": "apps-reporting.example.com",
  "ipAddress": "192.0.2.0",
  "events": [
    {
      "type": "USER_SETTINGS",
      "name": "CREATE_USER",
      "parameters": [
        {
          "name": "USER_EMAIL",
          "value": "liz@example.com"
        }
      ]
    }
  ]
}

Como responder a notificações

Para indicar o sucesso, é possível retornar qualquer um dos seguintes códigos de status: 200, 201, 202, 204 ou 102.

Se o serviço usar a biblioteca de cliente da API Google' e retornar 500,502, 503 ou 504, a API SDK Admin tentará novamente com espera exponencial. Cada outro código de status de devolução é considerado uma falha na mensagem.

Entenda os eventos de notificação da API Admin SDK

Esta seção fornece detalhes sobre as mensagens de notificação que você pode receber ao usar notificações push com a API Admin SDK.

As notificações push da API Reports contêm dois tipos de mensagens: sync e notificações de eventos. O tipo de mensagem é indicado no cabeçalho HTTP X-Goog-Resource-State. Os valores possíveis para notificações de eventos são os mesmos do método activities.list. Cada aplicativo tem eventos únicos:

Parando notificações

O prazo de expiração é o momento em que as notificações são interrompidas automaticamente. Você pode deixar de receber notificações de um canal específico antes que ele expire. Para isso, chame o método stop no seguinte URI:

https://www.googleapis.com/admin/reports_v1/channels/stop

Esse método exige que você forneça pelo menos as propriedades id e resourceId do canal, conforme mostrado no exemplo abaixo. Mesmo que a API Admin SDK tenha vários tipos de recursos que têm métodos watch, há apenas um método stop.

Somente usuários com a permissão correta podem interromper um canal. Especificamente, faça o seguinte:

  • Se o canal foi criado por uma conta de usuário normal, apenas o mesmo usuário do mesmo cliente (conforme identificado pelos IDs do cliente OAuth 2.0 dos tokens de autenticação) que criou o canal pode parar o canal.
  • Se o canal foi criado por uma conta de serviço, todos os usuários do mesmo cliente poderão interromper o canal.
POST https://www.googleapis.com/admin/reports_v1/channels/stop
  
Authorization: Bearer {auth_token_for_current_user}
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}