Notificações push

Propriedades obrigatórias

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

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

  O valor do ID definido é retornado na Cabeçalho HTTP X-Goog-Channel-Id de cada notificação mensagem que você recebe para este 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 às notificações desse canal. Isso é seu URL de callback do webhook e precisa usar HTTPS.

  Observe que a API Admin SDK pode enviar notificações para este endereço HTTPS somente 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 destino nome do host.

Propriedades opcionais

Você também pode especificar esses campos opcionais com sua Solicitação watch:

• Uma propriedade token que especifica uma string arbitrária a ser usado como token de canal. Você pode usar o canal de notificação tokens para vários propósitos. Por exemplo, é possível usar para verificar se cada mensagem recebida é de um canal em que seu aplicativo criado, para garantir que a notificação não seja ou encaminhar a mensagem para o destino correto seu aplicativo com base na finalidade deste canal. Tamanho máximo: 256 caracteres.

  O token está incluído no Cabeçalho HTTP X-Goog-Channel-Token em todas as notificações que seu aplicativo recebe para este canal.

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

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

  • Não inclua dados sensíveis, como tokens OAuth.

  .

• Uma string de propriedade expiration definida como Carimbo de data/hora Unix (em milissegundos) da data e hora em que você quer que a API Admin SDK parar de enviar mensagens para este 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 um formato legível por humanos) em todas as mensagens de notificação enviadas o app recebe para este canal.

Resposta do relógio

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

O corpo da mensagem da resposta do relógio fornece informações sobre a 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, o informações retornadas também incluem os valores resourceId e resourceUri para identificar o recurso que está sendo monitorado canal de notificação.

Você pode transmitir as informações retornadas a outro canal de notificação operações, como quando você quer parar de receber notificações.

Para mais detalhes sobre a resposta, consulte o watch para o recurso Activities na referência da API.

Sincronizar mensagem

Após criar um canal de notificação para observar um recurso, o A API Admin SDK envia uma mensagem sync para indicar que as notificações estão sendo iniciadas. O HTTP X-Goog-Resource-State o valor do cabeçalho dessas mensagens é sync. Devido à rede problemas de sincronização, é possível receber a mensagem sync antes mesmo de receber a resposta do método watch.

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

O formato das mensagens sync que a API SDK Admin envia 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 HTTP X-Goog-Message-Number. Valor do cabeçalho de 1. Cada notificação subsequente para este canal tem um número de mensagem maior do que o anterior, embora a mensagem números não serão 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 limites internos da API SDK Admin ou padrões (o mais restritivo será usado). A validade do canal hora, se houver, é incluída 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 estão incluídas (em formato legível) em cada mensagem 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 automaticamente um canal de notificação. Quando um canal estiver próximo da expiração, será necessário substituí-lo por um novo chamando o método watch. Como sempre, você deve usar um valor exclusivo para a propriedade id do novo canal. Observe que há seja uma "sobreposição" período em que os dois canais de notificação do mesmo recurso estão ativos.

Interpretar o formato das mensagens de notificação

Todas as mensagens de notificação incluem um conjunto de cabeçalhos HTTP Prefixos X-Goog-. Alguns tipos de notificação também podem incluir corpo da 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, é possível retornar qualquer um dos seguintes códigos de status: 200, 201, 202, 204 ou 102.

Se o serviço usa a biblioteca de cliente das APIs do Google e retorna 500,502, 503 ou 504, a API SDK Admin novas tentativas com espera exponencial. Todos os outros códigos de status de retorno são considerados como uma falha de 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 SDK Admin.

As notificações push da API Reports tê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:

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