Notificações sobre alterações de recursos

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

Visão geral

A API Google Drive oferece notificações push que permitem monitorar mudanças nos recursos. Você pode usar esse recurso para melhorar o desempenho do 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 assistido muda, a API Google Drive notifica seu 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 mensagens de notificação. Como parte da configuração do canal, você precisa identificar o URL específico em que você quer receber notificações. Sempre que o recurso de um canal muda, a API Google Drive envia uma mensagem de notificação como uma solicitação POST para esse URL.

Observação:a palavra "canal" usada neste documento se refere especificamente a um canal de notificação e não a outros tipos de canais usados nesta API ou serviço. Vários canais de notificação podem estar ativos ao mesmo tempo para o mesmo recurso.

No momento, a API Google Drive oferece suporte a 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 forem configurados, a API Google Drive vai informar ao seu aplicativo quando qualquer recurso monitorado for alterado.

Fazer solicitações de relógio

Cada recurso assistível da API do Google Drive tem um método watch associado em um URI do 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 é associado a um usuário específico e a um recurso (ou conjunto de recursos) específico. Uma solicitação watch só será bem-sucedida se o usuário atual ou a conta de serviço tiver ou tiver permissão para acessar esse recurso.

Exemplos

O exemplo de código abaixo mostra como usar um recurso channels para começar a detectar 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 observar 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

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

• Uma string de propriedade id que identifica exclusivamente esse novo canal de notificação no seu projeto. Recomendamos usar um identificador universal 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 todas as mensagens de notificação que você recebe para esse canal.

• Uma string de 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 Google Drive 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

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

• Uma propriedade token que especifica um valor de string arbitrário para usar como um token de canal. É possível usar tokens do 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 seu aplicativo, para garantir que a notificação não esteja sendo falsificada, ou para encaminhar a mensagem para o destino certo no 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 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 parâmetros de consulta de URL. 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 do 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 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 Google Drive, o tempo máximo de expiração é 86400 segundos (um dia) após a hora atual para o recurso files e 604800 segundos (uma semana) para changes. Se você não definir a propriedade expiration na solicitação, o tempo de expiração vai ser definido como 3600 segundos após o horário atual.

Para mais detalhes sobre a solicitação, consulte o método watch para os métodos files e changes na referência da API.

Assistir resposta

Se a solicitação watch criar um canal de notificação, ela vai 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 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.

É 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 para os métodos files e changes na referência da API.

Sincronizar mensagem

Depois de criar um canal de notificação para monitorar um recurso, a API Google Drive envia uma mensagem sync para indicar que as notificações estão começando. 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 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. 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 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 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 tempo de expiração, com um valor determinado pela sua solicitação ou por qualquer limite interno da API do Google Drive ou padrão (o valor mais restritivo é usado). O tempo de expiração 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 que o aplicativo recebe para esse 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 próximo da expiração, substitua-o 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 assistido muda, seu aplicativo recebe uma mensagem de notificação que descreve a mudança. A API Google Drive envia essas mensagens como solicitações POST HTTPS para o URL especificado como a propriedade address para este canal de notificação.

Observação:as solicitações HTTPS de envio de notificações especificam um user agent de APIs-Google e respeitam as diretivas do robots.txt, conforme descrito em User Agent das APIs Google.

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

As mensagens de notificação postadas pela API Google Drive 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 esse 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. Os números de mensagem aumentam para cada mensagem subsequente no canal, mas não são sequenciais.
X-Goog-Resource-ID	Um valor opaco que identifica o recurso monitorado. Esse ID é estável em todas as versões da API.
X-Goog-Resource-State	O novo estado do recurso que acionou a notificação. Valores possíveis: sync, add, remove, update, trash, untrash ou change .
X-Goog-Resource-URI	Um identificador específico da versão da API para o recurso monitorado.
Às vezes presente
X-Goog-Changed	Detalhes adicionais sobre as mudanças. Valores possíveis: content, parents, children ou permissions . Não foi fornecido com mensagens sync.
X-Goog-Channel-Expiration	Data e hora de expiração do canal de notificação, expressas em formato legível. Só aparece se definido.
X-Goog-Channel-Token	Token do canal de notificação que foi 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 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 sucesso, você pode 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 do Google Drive 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 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.

X-Goog-Resource-State	Aplicável a	Enviado quando
sync	files, changes	Um canal foi criado. Você vai começar a receber notificações sobre isso.
add	files	Um recurso foi criado ou compartilhado.
remove	files	Um recurso foi excluído ou não está mais compartilhado.
update	files	Uma ou mais propriedades (metadados) de um recurso foram atualizadas.
trash	files	Um recurso foi movido para a lixeira.
untrash	files	Um recurso foi removido da lixeira.
change	changes	Um ou mais itens da lista de mudanças foram adicionados.

Eventos de estado de recurso adicionais podem ser adicionados a essa lista com o tempo. Você pode receber tipos de eventos inesperados. Os manipuladores de eventos precisam ignorar esses eventos.

Para eventos update, o cabeçalho HTTP X-Goog-Changed pode ser fornecido. Esse cabeçalho contém uma lista separada por vírgulas que descreve os tipos de mudanças que ocorreram.

Tipo de alteração	Indica
content	O conteúdo do recurso foi atualizado.
properties	Uma ou mais propriedades do recurso foram atualizadas.
parents	Um ou mais recursos principais 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 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 certa podem interromper um canal. Especificamente:

• 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 cliente pode interromper o canal.

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