Esta página foi traduzida pela API Cloud Translation.

Notificações push

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

Visão geral

A API Admin SDK oferece notificações push que permitem monitorar mudanças nos recursos. Use esse recurso para melhorar o desempenho do seu aplicativo. Ele permite eliminar os custos de rede e computação extras envolvidos na pesquisa de recursos para determinar se eles mudaram. Sempre que um recurso monitorado é alterado, a API SDK Admin notifica seu para o aplicativo.

Para usar as notificações push, você precisa 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 que são 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 notificação mensagens. Como parte da configuração do canal, você deve identificar o URL específico em que você 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 para mudanças no recurso Activities.

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 forem definidos a API SDK Admin informa ao aplicativo quando um recurso monitorado mudanças.

Fazer solicitações de relógio

Cada recurso monitorável da API Admin SDK tem um watch em um URI com o 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 ao watch para o recurso.

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

Exemplos

Todas as solicitações de relógio para o recurso de 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", // 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.
}

Use 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.

Fique atento a todas as atividades administrativas:

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

Confira todas as atividades relacionadas aos documentos:

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

Observe 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

Fique de olho em um evento específico, como a alteração da senha de um usuário:

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

Monitorar as 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, 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 string exclusiva semelhante. Comprimento máximo: 64 caracteres.

O valor do ID definido é repetido no cabeçalho HTTP X-Goog-Channel-Id de cada mensagem de notificação que você recebe 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 à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

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

Uma propriedade token que especifica uma string arbitrária a ser usado como token de canal. É possível usar tokens de 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 app, para garantir que a notificação não esteja sendo falsificada, ou para encaminhar a mensagem ao destino certo no app 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 uma consulta de URL parâmetros. Exemplo: forwardTo=hr&createdBy=mobile
- Não inclua dados sensíveis, como tokens OAuth.
Observação: se você precisar enviar dados altamente sensíveis, verifique se eles estão criptografados antes de adicioná-los 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 por humanos) em todas as mensagens de notificação que o 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 o propriedade expiration na sua solicitação, o prazo o padrão é 21.600 segundos depois do horário atual.

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

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 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.

Observação: a propriedade resourceId é um identificador estável e independente da versão do recurso. A propriedade resourceUri é o URI canônico do recurso monitorado no contexto da versão atual da API. Portanto, é específico da versã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 método watch do 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 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 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 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 de mensagem 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 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, o 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á uma forma automática de renovar um canal de notificação. Quando um canal estiver perto de expirar, você precisará 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. É provável que haja um período de "sobreposição" quando os dois canais de notificação do mesmo recurso estiverem ativos.

Receber notificações

Sempre que um recurso monitorado muda, seu aplicativo recebe uma com a descrição da alteração. A API Admin SDK envia mensagens como solicitações POST HTTPS para o URL especificado como Propriedade address para esta notificação canal.

Observação:solicitações HTTPS de entrega de notificações especifique um user agent de APIs-Google e respeite o robots.txt. da API do Google Cloud, conforme descrito nas APIs do User agent.

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.

Cabeçalhos

Mensagens de notificação postadas pela API SDK Admin para seu destinatário incluem os seguintes cabeçalhos HTTP:

Cabeçalho	Descrição
Sempre presente
`X-Goog-Channel-ID`	UUID ou outra string exclusiva que você forneceu para identificar isso canal de notificação.
`X-Goog-Message-Number`	Número inteiro que identifica essa mensagem para esta notificação canal. O valor sempre é `1` para mensagens `sync`. Enviar mensagem os números aumentam a cada mensagem subsequente no canal, mas estão e não sequencial.
`X-Goog-Resource-ID`	Um valor opaco que identifica o recurso monitorado. Esse ID é entre 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 da expiração do canal de notificação, expressas em legível por humanos. Só aparece 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 tiverem o 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 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 de entidade `USER` ou 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 denunciadas.
`actor.profileId`	O ID exclusivo do perfil do Google Workspace do usuário.
`ownerDomain`	Domínio do Admin Console ou do proprietário do documento do app Documentos. É o domínio afetado pelo evento do relatório.
`ipAddress`	Endereço IP do usuário que está realizando 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 dele. Por exemplo, o endereço IP pode ser o endereço do servidor proxy do usuário ou um endereço da rede privada virtual (VPN). A API oferece suporte a 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 altera é identificado na propriedade `type`, que identifica um evento usando a propriedade `eventName`.
`events[].name`	Nome do evento. Esse é 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 de `eventName` em geral: Se nenhum `eventName` for fornecido, 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 diversos aplicativos.
`events[].parameters[].name`	O nome do parâmetro.
`events[].parameters[].value`	Valor de 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 a forma 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
        }
      ]
    }
  ]
}

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

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 SDK Admin vai tentar novamente com intervalo de espera 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 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:

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 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 comum, apenas o mesmo usuário do mesmo cliente (identificado pelos IDs de cliente OAuth 2.0 dos tokens de autenticação) que criou o canal pode interromper o canal.
Se o canal foi criado por uma conta de serviço, qualquer usuário do mesmo pode interromper o canal.

O exemplo de código abaixo 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"
}