Notificações push

Propriedades obrigatórias

Com cada solicitação watch, é necessário informar estes campos:

• Uma string de propriedade id que identifica exclusivamente esse novo canal de notificação no seu projeto. Recomendamos usar um identificador universalmente exclusivo (UUID) ou qualquer string exclusiva semelhante. Tamanho 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 que você recebe para esse canal.

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

• Uma string de propriedade address definida como o URL que detecta e responde a notificações para esse canal de notificação. Esse é o URL de callback do webhook, que 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 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 de host de destino.

Propriedades opcionais

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

• Uma propriedade token que especifica um valor de string arbitrário para usar como um token de canal. É possível usar tokens do canal de notificação para várias finalidades. Por exemplo, você pode usar o token para verificar se cada mensagem recebida é para um canal criado pelo seu aplicativo, para garantir que a notificação não esteja sendo falsificada, ou para encaminhar a mensagem para o destino certo no aplicativo com base na finalidade desse canal. Tamanho máximo: 256 caracteres.

  O token é incluído no cabeçalho HTTP X-Goog-Channel-Token em todas as mensagens de notificação que o app recebe para esse canal.

  Se você usa tokens de 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 sensíveis, como tokens OAuth.

• 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 SDK Admin 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 (em formato legível por humanos) em todas as mensagens de notificação que seu aplicativo receber para esse canal.

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", // 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 enviadas como parte da solicitação, as informações retornadas também incluem resourceId e resourceUri para identificar o recurso que está sendo monitorado neste canal de notificação.

É possível transmitir as informações retornadas para outras operações do canal de notificação, como quando você quer parar de receber notificações.

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

Sincronizar mensagem

Depois de criar um canal de notificação para monitorar um recurso, a API 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 dessas mensagens é sync. Devido a problemas de sincronização da rede, é possível receber a mensagem sync mesmo antes de receber a 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. Também é possível usar a notificação sync para fazer alguma inicialização e se preparar para eventos futuros.

O formato das mensagens sync que a API Admin SDK 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 a anterior, embora os números das mensagens 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 qualquer limite interno da API Admin SDK ou padrão (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 validade são incluídas (em formato legível por humanos) em todas as mensagens de notificação que o app recebe para esse canal no cabeçalho HTTP X-Goog-Channel-Expiration.

No momento, não há uma forma automática de renovar um canal de notificação. Quando um canal estiver próximo da expiração, substitua-o por um novo chamando o método watch. Como sempre, é necessário 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 estiverem ativos.

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ção também podem incluir um corpo de mensagem.

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

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
        }
      ]
    }
  ]
}

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"
        }
      ]
    }
  ]
}

Responder a notificações

Para indicar sucesso, você pode retornar 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 intervalo exponencial. Todos os outros códigos de status de retorno são considerados uma falha de mensagem.

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

Esta seção traz 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: de sincronização e 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:

• admin
• agenda
• drive
• grupos
• login
• dispositivo móvel
• saml
• token
• user_accounts