Esta página foi traduzida pela API Cloud Translation.

Notificações Push

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

Visão geral

A API Directory fornece notificações push que permitem monitorar mudanças nos recursos. Você pode usar esse recurso para melhorar o desempenho do aplicativo. Assim, você não precisa de recursos de rede e computação extras custos envolvidos com os recursos de pesquisa para determinar se eles mudaram. Sempre que um recurso monitorado é alterado, a API Directory notifica seu para o aplicativo.

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

Configure o URL de recebimento ou o receptor de callback "webhook".
Isso é um servidor HTTPS que lida com as mensagens de notificação da API que são acionada quando um recurso é alterado.
Configure um (canal de notificação) para cada endpoint de recurso que você quiser assistir.
Um canal especifica informações de roteamento para mensagens de notificação. 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 Directory envia uma mensagem de notificação como um POST para esse URL.

No momento, a API Directory oferece suporte a notificações para mudanças no recurso Users.

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 configurados, a API Directory vai informar o aplicativo quando qualquer recurso monitorado for alterado.

Fazer solicitações de monitoramento

Cada recurso monitorável da API Directory 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 uma recurso específico, envie uma solicitação POST ao Método watch para o recurso.

Cada canal de notificação é associado a um usuário específico e a 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 monitoramento para o recurso User de um único domínio têm o seguinte formato:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=domain&event=event
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.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

Use os parâmetros domain e event para especificar o domínio e o tipo de evento para o qual você quer receber notificações.

Todas as solicitações de observação para o recurso Usuário para um cliente têm o formato geral:

POST https://admin.googleapis.com/admin/directory/users/v1/watch?customer=customer&event=event
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.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

Use os parâmetros customer e event para especificar o ID exclusivo da Conta do Google do cliente e o tipo de evento sobre o qual você quer receber notificações.

Os valores possíveis para event são:

add: evento criado pelo usuário
delete: evento de exclusão do usuário
makeAdmin: evento de alteração do status de administrador do usuário
undelete: evento de restauração do usuário
update: evento de atualização do usuário

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

Confira os eventos criados pelo usuário para o domínio mydomain.com:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=mydomain.com&event=add

Observe os eventos criados pelo usuário para o cliente my_customer:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?customer=my_customer&event=add

Propriedades obrigatórias

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

Uma string de 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 para 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 Directory só pode enviar notificações para este 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

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. É 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. Comprimento máximo: 256 caracteres.
O token é incluído 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.
Observação: se você precisar enviar dados dados, certifique-se de que estejam criptografados antes de adicioná-los ao token.
Uma string de propriedade expiration definida como um carimbo de data/hora do Unix (em milissegundos) da data e hora em que você quer que a API Directory 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.

Para mais detalhes sobre a solicitação, consulte o método watch para o recurso Users 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 a canal de notificação que você acabou de criar, conforme mostrado no exemplo abaixo.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab", // ID you specified for this channel.
  "resourceId": "B4ibMJiIhTjAQd7Ff2K2bexk8G4", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1384823632000, // 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.

Observação:a propriedade resourceId é uma identificador estável e independente da versão do recurso. O A propriedade resourceUri é o URI canônico do conteúdo no contexto da versão atual da API. Portanto, é são específicos da versã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 Users na referência da API.

Sincronizar mensagem

Após criar um canal de notificação para observar um recurso, o A API Directory 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 a problemas de tempo de rede, é possível receber a mensagem sync antes mesmo 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. 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 Directory 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 tempo de expiração, com um valor determinado pela sua solicitação ou por qualquer limite interno da API Directory ou padrão (o valor mais restritivo é 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á como renovar automaticamente 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, é 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.

Receber notificações

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

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 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 Directory 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 que você forneceu para identificar isso canal de notificação.
`X-Goog-Message-Number`	Número inteiro que identifica essa mensagem para este canal de notificação. 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 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 os usuários contêm as seguintes informações no corpo da solicitação:

Propriedade	Descrição
`kind`	Identifica isso como um recurso Usuário. Valor: a string fixa "`admin#directory#user`".
`id`	Identificador exclusivo do recurso do usuário.
`etag`	ETag da mensagem de notificação. Diferente da ETag do recurso Usuário.
`primaryEmail`	O endereço de e-mail principal do usuário.

Exemplos

As mensagens de notificação para eventos de recursos User têm a seguinte forma geral:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: directoryApiId
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/directory/v1/users?domain=domain&event=event
X-Goog-Resource-State:  event
X-Goog-Message-Number: 10

{
  "kind": "admin#directory#user",
  "id": long,
  "etag": string,
  "primaryEmail": string
}

Exemplo de um evento excluído pelo usuário:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 189
X-Goog-Channel-ID: deleteChannel
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Mon, 09 Dec 2013 22:24:23 GMT
X-Goog-Resource-ID:  B4ibMJiIhTjAQd7Ff2K2bexk8G4
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=mydomain.com&event=delete&alt=json
X-Goog-Resource-State:  delete
X-Goog-Message-Number: 236440

{
  "kind": "admin#directory#user",
  "id": "111220860655841818702",
  "etag": "\"Mf8RAmnABsVfQ47MMT_18MHAdRE/evLIDlz2Fd9zbAqwvIp7Pzq8UAw\"",
  "primaryEmail": "user@mydomain.com"
}

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 do Google e retornar 500, 502, 503 ou 504, a API Directory vai tentar novamente com espera exponencial. Todos os outros códigos de status de retorno são considerados uma falha de mensagem.

Parar notificações

A propriedade expiration controla quando as notificações são interrompidas automaticamente. Você pode optar por parar de receber notificações de um canal específico antes expira chamando o método stop URI a seguir:

https://www.googleapis.com/admin/directory_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 Directory 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 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 a seguir mostra como parar de receber notificações:

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

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