Notificações push

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

Visão geral

A API Admin SDK fornece notificações push que permitem monitorar mudanças nos recursos. Você pode usar esse recurso para melhorar o desempenho do seu aplicativo. Isso elimina os custos extras de rede e computação envolvidos na sondagem de recursos para determinar se eles mudaram. Sempre que um recurso monitorado muda, a API Admin SDK notifica seu aplicativo.

Para usar notificações push, você precisa fazer duas coisas:

Configure o URL de recebimento ou o receptor de callback "webhook".
Este é 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 monitorar.
Um canal especifica informações de roteamento para mensagens de notificação. Como parte da configuração do canal, você precisa identificar 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 do SDK Admin oferece suporte a notificações de mudanças no recurso Atividades.

Criar canais de notificação

Para solicitar notificações push, configure um canal de notificação para cada recurso que você quer monitorar. Depois que os canais de notificação são configurados, a API Admin SDK informa ao aplicativo quando um recurso monitorado muda.

Fazer solicitações de relógio

Cada recurso de API do SDK Admin observável tem um método watch associado em um URI do seguinte formato:

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

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

Cada canal de notificação está associado a um usuário e a um recurso (ou conjunto de recursos) específicos. Uma solicitação watch só será bem-sucedida se o usuário atual ou a conta de serviço tiver a propriedade ou permissão para acessar esse recurso.

Exemplos

Todas as solicitações de observação para o recurso "Atividades" têm a forma 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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myFilesChannelDest",
  "payload": true,
  "expiration": 3600
}

O corpo da solicitação tem as seguintes propriedades:

id: um UUID ou uma string exclusiva semelhante que identifica este canal.
type: o tipo de mecanismo de entrega. O valor desse campo precisa ser web_hook.
address: o URL para onde as notificações são enviadas.
token: uma string arbitrária enviada ao endereço de destino com cada notificação para verificar se ela vem de uma fonte confiável.
payload: uma flag booleana que indica se o payload deve ser incluído na notificação.
expiration: o tempo de vida em segundos do canal de notificação.

Você pode usar os parâmetros userKey, applicationName, eventName e filters para receber notificações apenas de eventos, usuários ou aplicativos específicos.

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

Acompanhe todas as atividades de administrador:

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

Acompanhe todas as atividades do Docs:

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

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

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

Monitore um evento específico, como a mudança de senha de um usuário:

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

Acompanhe as mudanças 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

Em cada solicitação watch, você precisa fornecer estes campos:

Uma string de propriedade id que identifica de forma exclusiva esse novo canal de notificação no seu projeto. Recomendamos usar um identificador universal exclusivo (UUID) ou qualquer string exclusiva semelhante. Comprimento máximo: 64 caracteres.

O valor do ID definido é repetido no cabeçalho HTTP X-Goog-Channel-Id de todas as mensagens de notificação recebidas para esse canal.
Uma string de propriedade type definida como o valor web_hook.
Uma string de propriedade address definida como o URL que escuta e responde às notificações desse canal. Esse é o URL de retorno de chamada do webhook, que precisa usar HTTPS.

A API Admin SDK só pode 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 estes 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 tokens de 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 seu aplicativo (para garantir que a notificação não seja falsificada) ou para encaminhar a mensagem ao destino certo dentro do aplicativo com base na finalidade desse canal. Comprimento máximo: 256 caracteres.
O token é incluído no cabeçalho HTTP X-Goog-Channel-Token em todas as mensagens de notificação que seu aplicativo recebe para esse canal.

Se você usa tokens de canais de notificação, recomendamos que:
- Use um formato de codificação extensível, como parâmetros de consulta de URL. Exemplo: forwardTo=hr&createdBy=mobile
- Não inclua dados sensíveis, como tokens OAuth.
Observação:se você precisar enviar dados altamente sensíveis, criptografe-os antes de adicionar ao token.
Uma string de propriedade expiration definida como um carimbo de data/hora Unix (em milissegundos) 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 tempo de expiração, ele será incluído como o valor do cabeçalho HTTP X-Goog-Channel-Expiration (em formato legível para humanos) em todas as mensagens de notificação que seu aplicativo receber para esse canal.

Observação:para a API Admin SDK, o tempo máximo de expiração é de 21.600 segundos. Se você não definir a propriedade expiration na sua solicitação, o tempo de expiração será de 21.600 segundos após o horário atual.

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

Assistir resposta

Se a solicitação watch criar um canal de notificação, ela vai 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",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 3600
}

Além das propriedades enviadas como parte da solicitação, as informações retornadas também incluem resourceId e resourceUri para identificar o recurso monitorado nesse canal de notificação.

Observação:a propriedade resourceId é um identificador estável e independente de versão para o recurso. A propriedade resourceUri é o URI canônico do recurso monitorado no contexto da versão atual da API. Portanto, ela é específica da versão.

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

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

Mensagem de sincronização

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

É seguro ignorar a notificação sync, mas você também pode usá-la. Por exemplo, se você decidir que não quer manter o canal, use 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.

O formato das mensagens sync que a API do SDK Admin envia para seu URL de recebimento é mostrado abaixo.

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 the 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 tem um número de mensagem maior que o anterior, embora os números não sejam sequenciais.

Renovar canais de notificação

Um canal de notificação pode ter um tempo de expiração, com um valor determinado pela sua solicitação ou por limites internos ou padrões da API Admin SDK (o valor mais restritivo é usado). O tempo de expiração do canal, se houver, é incluído como um carimbo de data/hora Unix (em milissegundos) 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 esse canal no cabeçalho HTTP X-Goog-Channel-Expiration.

No momento, não há uma maneira automática de renovar um canal de notificação. Quando um canal estiver perto de expirar, substitua-o por um novo chamando o método watch. Como sempre, você precisa usar um valor exclusivo para a propriedade id do novo canal. É provável que haja um período de "sobreposição" quando os dois canais de notificação do mesmo recurso estão ativos.

Receber notificações

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

Observação:as solicitações HTTPS de entrega de notificações especificam um user agent de APIs-Google e respeitam as diretivas do robots.txt, conforme descrito em User agent das APIs do Google.

Interpretar o formato da mensagem de notificação

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

Cabeçalhos

As mensagens de notificação postadas pela API Admin SDK no 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 este canal de notificação.
`X-Goog-Message-Number`	Número inteiro que identifica esta mensagem para este canal de notificação. O valor é sempre `1` para mensagens `sync`. Os números das 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 do 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 definido pelo seu aplicativo e que pode ser usado 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 da ocorrência da atividade. O valor está no formato de data e hora ISO 8601. O horário é a data completa mais horas, 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 ocorrerem ao mesmo tempo.
`id.applicationName`	Nome do aplicativo a que o evento pertence. Os valores possíveis incluem: admin agenda drive grupos groups_enterprise login dispositivo móvel saml token user_accounts
`id.customerId`	O identificador exclusivo de uma conta do Google Workspace.
`actor`	Usuário que 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` é o `USER` ou a solicitação de entidade OAuth 2LO que realizou a ação listada no relatório .
`actor.email`	O 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 proprietário do documento do aplicativo Documentos. É o domínio afetado pelo evento do relatório.
`ipAddress`	Endereço IP do usuário que está realizando a ação. É o endereço IP do usuário ao fazer login no Google Workspace, que pode ou não refletir a localização física dele. Por exemplo, o endereço IP pode ser o endereço do servidor 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 recurso do Google Workspace que um administrador muda é 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á relacionado a um serviço ou recurso específico do Google Workspace que a API organiza em tipos de eventos. Para parâmetros de solicitação `eventName` em geral: Se nenhum `eventName` for informado, o relatório vai 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 `eventName` além da solicitada.
`events[].parameters[]`	Pares de valores de parâmetros para várias aplicações.
`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 recursos de atividade têm o seguinte formato geral:

POST https://mydomain.com/notifications
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
        }
      ]
    }
  ]
}

Exemplo de um evento de atividade do administrador:

POST https://mydomain.com/notifications
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"
        }
      ]
    }
  ]
}

Responder a notificações

Para indicar sucesso, retorne um dos seguintes códigos de status: 200, 201, 202, 204 ou 102.

Se o serviço usar a biblioteca de cliente da API do Google e retornar 500,502, 503 ou 504, a API Admin SDK vai tentar novamente com backoff exponencial. Qualquer outro código de status de retorno é considerado uma falha na mensagem.

Entender 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: mensagens de sincronização 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 exclusivos:

Parar notificações

A propriedade expiration controla quando as notificações param automaticamente. Você pode parar de receber notificações de um canal específico antes que ele expire chamando 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. Se a API Admin SDK tiver vários tipos de recursos com métodos watch, haverá apenas um método stop.

Somente usuários com a permissão certa podem encerrar um canal. Especificamente:

Se o canal foi criado por uma conta de usuário comum, somente o mesmo usuário do mesmo cliente (identificado pelos IDs do cliente OAuth 2.0 dos tokens de autenticação) que criou o canal pode interrompê-lo.
Se o canal foi criado por uma conta de serviço, qualquer usuário do mesmo cliente pode interromper o canal.

O exemplo de código a seguir mostra como parar de receber notificações:

POST https://www.googleapis.com/admin/reports_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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

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

Visão geral

Criar canais de notificação

Fazer solicitações de relógio

Exemplos

Propriedades obrigatórias

Propriedades opcionais

Assistir resposta

Mensagem de sincronização

Renovar canais de notificação

Receber notificações

Interpretar o formato da mensagem de notificação

Cabeçalhos

Exemplos

Responder a notificações

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

Parar notificações

Notificações push