Neste documento, descrevemos como usar notificações push que informam seu aplicativo quando um recurso é modificado.
Visão geral
A API Admin SDK fornece notificações push que permitem monitorar alterações nos recursos. Use esse recurso para melhorar o desempenho do aplicativo. Isso permite eliminar a rede extra e os custos de computação envolvidos na pesquisa de recursos para determinar se eles mudaram. Sempre que um recurso monitorado é alterado, a API Admin SDK notifica o aplicativo.
Para usar as notificações push, você precisa fazer duas coisas:
Configure o URL de recebimento ou o receptor de callback "webhook".
É um servidor HTTPS que processa as mensagens de notificação de API acionadas quando um recurso é modificado.
Configure um canal de notificação para cada endpoint de recurso que você quer assistir.
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 as notificações. Sempre que um recurso de um canal é alterado, a API Admin SDK envia uma mensagem de notificação como uma solicitação
POST
para esse URL.
Atualmente, a API Admin SDK é compatível com notificações de alterações 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 configurados, a API Admin SDK informará ao aplicativo quando algum recurso monitorado for alterado.
Fazer solicitações para assistir
Cada recurso da API Admin SDK visível tem um método
watch
associado 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
para o método watch
do recurso.
Cada canal de notificação está associado a um usuário específico e a um recurso (ou conjunto de recursos) específico. Uma solicitação watch
não terá êxito, a menos que o usuário atual ou a conta de serviço seja proprietário ou tenha permissão para acessar esse recurso.
Exemplos
Todas as solicitações de observação para o recurso de atividades têm o formato 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. }
Você pode usar os parâmetros userKey, applicationName, eventName
e filters
para receber apenas notificações de eventos, usuários ou aplicativos específicos.
Observação:os exemplos a seguir omitem o corpo da solicitação para maior clareza.
Acompanhe todas as atividades do administrador:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch
Fique de olho em todas as atividades dos documentos:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch
Monitore a atividade do administrador de um usuário específico:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch
Fique atento a um evento específico, como alterar a senha de um usuário:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD
Fique atento a 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
Em cada solicitação watch
, é necessário preencher estes campos:
-
Uma string de propriedade
id
que identifica exclusivamente esse novo canal de notificação no projeto. Recomendamos o uso de um identificador universal exclusivo (UUID) ou qualquer string exclusiva semelhante. Tamanho máximo: 64 caracteres.O valor do ID definido é retornado 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 valorweb_hook
. -
Uma string de propriedade
address
definida como o URL que detecta e responde às notificações desse canal. Esse é o URL do callback do webhook, que precisa usar HTTPS.A API Admin SDK só consegue enviar notificações para esse endereço HTTPS quando há um certificado SSL válido instalado no servidor. 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 esses campos opcionais com sua solicitação watch
:
-
Uma propriedade
token
que especifica um valor de string arbitrário para ser usado como um 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 é de um canal criado pelo aplicativo, para garantir que a notificação não esteja sendo falsificada, ou para rotear a mensagem para o destino correto no seu 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ê usar tokens de canal de notificação, recomendamos que faça 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 Admin SDK 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) em todas as mensagens de notificação que seu aplicativo recebe para esse canal.
Para mais detalhes sobre a solicitação, consulte o método watch
do recurso Activities na Referência da API.
Assistir resposta
Se a solicitação watch
criar um canal de notificação, ela 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 nesse canal de notificação.
É possível transmitir as informações retornadas para outras operações de 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 observar um recurso, a
API Admin SDK envia uma mensagem sync
para indicar que
as notificações estão sendo iniciadas. 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
mesmo antes de receber a resposta do método watch
.
Você pode ignorar a notificação sync
, mas ela também pode ser usada. Por exemplo, se você decidir que não quer manter
o canal, é possível usar 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 algumas inicializações e se preparar para
eventos futuros.
Veja abaixo o formato das mensagens sync
que a API Admin SDK envia para o URL de recebimento.
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 mensagens 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 qualquer padrão ou limite interno da API Admin SDK. É usado o valor mais restritivo. O prazo de validade 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) em todas as mensagens de notificação que o aplicativo recebe para esse canal no cabeçalho HTTP X-Goog-Channel-Expiration
.
No momento, não há como renovar um canal de notificação de forma automática. Quando
um canal estiver perto de expirar, será necessário substituí-lo 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 estiverem ativos.
Receber notificações
Sempre que um recurso monitorado muda, o 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.
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 o
corpo de uma mensagem.
Cabeçalhos
As mensagens de notificação postadas pela API Admin SDK no URL de recebimento incluem os seguintes cabeçalhos HTTP:
Cabeçalho | Descrição |
---|---|
Sempre presente | |
|
UUID ou outra string exclusiva fornecida para identificar esse canal de notificação. |
|
Número inteiro que identifica a mensagem do canal de
notificação. O valor é sempre 1 para mensagens sync . Os números de mensagens aumentam a cada mensagem subsequente no canal, mas não são sequenciais. |
|
Um valor opaco que identifica o recurso monitorado. Esse ID é estável em todas as versões da API. |
|
O novo estado do recurso que acionou a notificação.
Valores possíveis:
sync ou um nome de evento.
|
|
Um identificador específico da versão da API para o recurso monitorado. |
Às vezes presente | |
|
Data e hora da expiração do canal de notificação, expressas em formato legível. Presente apenas se definido. |
|
Token do canal de notificação que foi definido pelo seu aplicativo e que você pode usar 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 atividades. |
id.time |
Hora de ocorrência da atividade. O valor está no formato de data e hora ISO 8601. A hora é 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: |
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 executou a atividade listada no relatório. Nesta versão da API, callerType é a solicitação de entidade USER ou OAuth 2LO que executou 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 proprietário do documento do aplicativo Documentos. Esse é 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 do usuário. Por exemplo, o endereço IP pode ser o endereço do servidor proxy do usuário ou o endereço de uma rede privada virtual (VPN, na sigla em inglês). 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 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 relatada pela API. E 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:
|
events[].parameters[] |
Pares de valores de parâmetros para vários 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 recurso 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 um 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 o sucesso, retorne qualquer um destes 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
tentará novamente com espera exponencial.
Todos os outros códigos de status de retorno são considerados falhas 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 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 são interrompidas automaticamente. Você pode optar por parar de receber notificações para 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 requer 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 correta podem interromper um canal. Especificamente, faça o seguinte:
- Se o canal foi criado por uma conta de usuário normal, apenas o mesmo usuário do mesmo cliente (conforme identificado pelos IDs do cliente OAuth 2.0 nos tokens de autenticação) que criou o canal poderá interromper o canal.
- Se o canal foi criado por uma conta de serviço, qualquer usuário do mesmo cliente pode interrompê-lo.
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" }