Neste documento, descrevemos como usar notificações push que informam seu aplicativo quando um recurso é alterado.
Visão geral
A API Google Drive fornece notificações push que permitem monitorar alterações nos recursos. Use esse recurso para melhorar o desempenho do aplicativo. Ela elimina os custos extras de rede e computação envolvidos na pesquisa de recursos para determinar se eles mudaram. Sempre que um recurso monitorado é alterado, a API Google Drive notifica seu aplicativo.
Para usar notificações push, você precisa fazer duas coisas:
Configure o URL de recebimento ou o receptor de callback do "webhook".
Esse é um servidor HTTPS que processa as mensagens de notificação da API que são acionadas quando um recurso é alterado.
Configure um (canal de notificação) para cada endpoint de recurso que você quer monitorar.
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 notificações. Sempre que o recurso de um canal é alterado, a API Google Drive envia uma mensagem de notificação como uma solicitação
POST
para esse URL.
Atualmente, a API Google Drive é compatível com notificações de mudanças nos métodos files
e changes
.
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 são configurados, a API Google Drive informa ao aplicativo quando algum recurso monitorado é alterado.
Fazer solicitações de monitoramento
Cada recurso monitorável da API Google Drive 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 e
um recurso (ou conjunto de recursos) específicos. Uma solicitação watch
não será bem-sucedida, a menos que o usuário atual ou a conta de serviço tenha ou tenha permissão para acessar esse recurso.
Exemplos
O exemplo de código a seguir mostra como usar um recurso channels
para começar a monitorar mudanças em um único recurso files
usando o método files.watch
:
POST https://www.googleapis.com/drive/v3/files/fileId/watch Authorization: Bearer CURRENT_USER_AUTH_TOKEN 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 files channel token. "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time. }
O exemplo de código a seguir mostra como usar um recurso channels
para começar a monitorar todos os changes
usando o método changes.watch
:
POST https://www.googleapis.com/drive/v3/changes/watch Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a77", // Your channel ID. "type": "web_hook", "address": "https://mydomain.com/notifications", // Your receiving URL. ... "token": "target=myApp-myChangesChannelDest", // (Optional) Your changes channel token. "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time. }
Propriedades obrigatórias
Para cada solicitação watch
, você precisa fornecer estes campos:
-
Uma string de propriedade
id
que identifica exclusivamente esse novo canal de notificação no seu 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 cada mensagem de notificação que você receber para esse canal. -
Uma string de propriedade
type
definida com o valorweb_hook
. -
Uma string de propriedade
address
definida como o URL que detecta e responde a notificações desse canal. Esse é o URL de callback do webhook e precisa usar HTTPS.A API Google Drive 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 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 a ser usado como um token de canal. Os tokens de canal de notificação podem ser usados para várias finalidades. Por exemplo, é possível usar o token para verificar se cada mensagem recebida é de um canal criado pelo seu aplicativo (para garantir que a notificação não esteja sendo falsificada) ou rotear a mensagem para o destino correto dentro do 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 seu aplicativo recebe para esse canal.Se você usar 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 Google Drive 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.
Para mais detalhes sobre a solicitação, consulte o método watch
para os métodos files
e changes
na Referência da API.
Resposta do relógio
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": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel. "resourceId": "o3hgv1538sdjfh", // ID of the watched resource. "resourceUri": "https://www.googleapis.com/drive/v3/files/o3hgv1538sdjfh", // Version-specific ID of the watched resource. "token": "target=myApp-myFilesChannelDest", // Present only if one was provided. "expiration": 1426325213000, // Actual expiration date and time as UNIX timestamp (in milliseconds), if applicable. }
Além das propriedades enviadas como parte da solicitação, as
informações retornadas 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 canais de notificação, como quando você quer parar de receber notificações.
Para mais detalhes sobre a resposta, consulte o método watch
para os métodos files
e changes
na Referência da API.
Sincronizar mensagem
Depois de criar um canal de notificação para observar um recurso, a API Google Drive envia uma mensagem sync
para indicar que as notificações estão sendo iniciadas. 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ê não quiser manter
o canal, poderá 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 uma inicialização e se preparar para eventos posteriores.
O formato das mensagens sync
que a API Google Drive 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 prazo de validade, com um valor determinado pela sua solicitação ou por quaisquer limites ou padrões internos da API Google Drive. O valor mais restritivo será usado. 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 por humanos) em todas as mensagens de notificação recebidas pelo aplicativo para esse 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, você precisa usar um valor exclusivo para a propriedade id
do novo canal. Provavelmente
haverá um período de "sobreposição" em que os dois canais de notificação para o
mesmo recurso vão ficar ativos.
Receber notificações
Sempre que um recurso monitorado muda, o aplicativo recebe uma
mensagem de notificação com a descrição da alteração. A API Google Drive envia essas mensagens como solicitações HTTPS POST
para o URL especificado como a propriedade address
desse canal de notificação.
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 o corpo de uma mensagem.
Cabeçalhos
As mensagens de notificação postadas pela API Google Drive no URL de recebimento incluem os seguintes cabeçalhos HTTP:
Cabeçalho | Descrição |
---|---|
Sempre presente | |
|
UUID ou outra string exclusiva que você forneceu para identificar esse canal de notificação. |
|
Número inteiro que identifica essa mensagem para esse canal de
notificação. O valor sempre é 1 para mensagens sync . Os números
de mensagens aumentam para 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 , add , remove , update ,
trash , untrash ou change
.
|
|
Um identificador específico da versão da API para o recurso monitorado. |
Às vezes presente | |
|
Mais detalhes sobre as mudanças.
Valores possíveis:
content ,
parents ,
children ou
permissions
.
Não fornecido com sync mensagens. |
|
Data e hora da expiração do canal de notificação, expressas em formato legível por humanos. Presente apenas se definido. |
|
Token do canal de notificação que foi definido pelo aplicativo e que pode ser usado para verificar a fonte da notificação. Presente apenas se definido. |
As mensagens de notificação para files
e changes
estão vazias.
Exemplos
Mude a mensagem de notificação para recursos files
, que não inclui um corpo de solicitação:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 0 X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66 X-Goog-Channel-Token: 398348u3tu83ut8uu38 X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT X-Goog-Resource-ID: ret08u3rv24htgh289g X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/files/ret08u3rv24htgh289g X-Goog-Resource-State: update X-Goog-Changed: content,properties X-Goog-Message-Number: 10
Mude a mensagem de notificação para recursos changes
, que inclui um corpo de solicitação:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 118 X-Goog-Channel-ID: 8bd90be9-3a58-3122-ab43-9823188a5b43 X-Goog-Channel-Token: 245t1234tt83trrt333 X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT X-Goog-Resource-ID: ret987df98743md8g X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/changes X-Goog-Resource-State: changed X-Goog-Message-Number: 23 { "kind": "drive#changes" }
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 usa a biblioteca de cliente da API do Google e retorna 500
, 502
, 503
ou 504
, a API Google Drive faz uma nova tentativa 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 Google Drive
Esta seção fornece detalhes sobre as mensagens de notificação que você pode receber ao usar notificações push com a API Google Drive.
Entregue quando | ||
---|---|---|
sync |
files , changes |
Um canal foi criado. Você vai começar a receber notificações sobre ela. |
add |
files |
Um recurso foi criado ou compartilhado. |
|
files |
Um recurso existente foi excluído ou cancelado. |
|
files |
Uma ou mais propriedades (metadados) de um recurso foram atualizadas. |
|
files |
Um recurso foi movido para a lixeira. |
|
files |
Um recurso foi removido da lixeira. |
|
changes |
Um ou mais itens do log de mudanças foram adicionados. |
Para eventos update
, é possível fornecer o cabeçalho HTTP X-Goog-Changed
. Esse cabeçalho contém uma lista separada por vírgulas que descreve os tipos de alterações ocorridas.
Tipo de mudança | Indica |
---|---|
content |
O conteúdo do recurso foi atualizado. |
properties |
Uma ou mais propriedades de recursos foram atualizadas. |
parents |
Um ou mais recursos pais foram adicionados ou removidos. |
children |
Um ou mais recursos filhos foram adicionados ou removidos. |
permissions |
As permissões do recurso foram atualizadas. |
Exemplo com cabeçalho X-Goog-Changed
:
X-Goog-Resource-State: update X-Goog-Changed: content, permissions
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 que ele expire chamando o método stop
no seguinte URI:
https://www.googleapis.com/drive/v3/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 Google Drive 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, somente o mesmo usuário do mesmo cliente (conforme identificado pelos IDs do cliente OAuth 2.0 dos tokens de autenticação) que criou o canal pode interrompê-lo.
- 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/drive/v3/channels/stop Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66", "resourceId": "ret08u3rv24htgh289g" }