Notificações sobre alterações de recursos

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

Visão geral

A API Google Drive fornece notificações push que permitem monitorar mudanças nos recursos. Use esse recurso para melhorar o desempenho do seu 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 Google Drive notifica seu para o aplicativo.

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

• Configurar o URL de recebimento ou "webhook" receptor de callback.

  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 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 Google Drive envia uma mensagem de notificação como um POST. para esse URL.

Observação:a palavra "canal" usado neste documento refere-se especificamente a um canal de notificação e não a qualquer outro tipo de canais usados nessa API ou serviço.

Atualmente, a API Google Drive é compatível com notificações de alterações em os 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 definidos a API Google Drive informa ao aplicativo quando um recurso monitorado mudanças.

Fazer solicitações de monitoramento

Cada recurso da API do Google Drive observável tem um recurso 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ó terá êxito se o usuário atual ou conta de serviço é proprietário ou tem 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 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 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 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 Google Drive é capaz de 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

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. Você pode usar o canal de notificação tokens para vários propósitos. Por exemplo, é possível usar para verificar se cada mensagem recebida é de um canal em que seu aplicativo criado, para garantir que a notificação não seja ou encaminhar a mensagem para o destino correto seu aplicativo com base na finalidade deste canal. Tamanho máximo: 256 caracteres.

  O token está incluído no 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 Carimbo de data/hora Unix (em milissegundos) da data e hora em que você quer que a API Google Drive parar de enviar mensagens para este 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 um formato legível por humanos) em todas as mensagens de notificação enviadas o app recebe para este canal.

.

Observação: Na API Google Drive, o prazo de validade máximo é 86.400 segundos (1 dia) após o horário atual para o recurso files e 604.800 segundos (1 semana) para changes. Se você não definir o propriedade expiration na sua solicitação, o prazo o horário padrão é 3.600 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.

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": "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, 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. A 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.

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

Sincronizar mensagem

Após criar um canal de notificação para observar um recurso, o A API Google Drive 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 deseja manter o canal, é possível usar X-Goog-Channel-ID e X-Goog-Resource-ID valores 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 Google Drive 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 prazo de validade, com um valor determinado pela sua solicitação ou por limites internos da API Google Drive 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, 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 próximo da expiração, será necessário 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. Observe que há seja uma "sobreposição" período em que os dois canais de notificação do mesmo recurso estão ativos.

Receber notificações

Sempre que um recurso monitorado muda, seu aplicativo recebe uma com a descrição da alteração. A API Google Drive 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 das mensagens de notificação

Todas as mensagens de notificação incluem um conjunto de cabeçalhos HTTP Prefixos X-Goog-. Alguns tipos de notificação também podem incluir corpo da mensagem.

Cabeçalhos

Mensagens de notificação postadas pela API Google Drive para o 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. Este 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, 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	Mais detalhes sobre as mudanças. Valores possíveis: content, parents, children ou permissions , Não fornecido com sync mensagens.
X-Goog-Channel-Expiration	Data e hora da expiração do canal de notificação, expressas em legível por humanos. Presente apenas se definido.
X-Goog-Channel-Token	O token do canal de notificação que foi definido pelo aplicativo. que você pode usar para verificar a fonte de 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, é 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 das APIs do Google e retorna 500,502, 503 ou 504, a API Google Drive novas tentativas 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.

X-Goog-Resource-State	Aplicável a	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.
remove	files	Um recurso existente foi excluído ou cancelado.
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 do log de mudanças foram adicionados.

Outros eventos de estado de recursos podem ser adicionados a essa lista com o tempo. Talvez você receba tipos de eventos inesperados. Seus manipuladores de eventos devem ignorá-los.

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 alteração	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 param 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/drive/v3/channels/stop

Este método exige que você forneça pelo menos o nome id e as propriedades resourceId, conforme mostrado nas exemplo abaixo. Se a API Google Drive 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 tiver sido criado por uma conta de usuário normal, somente o mesmo usuário do mesmo cliente (conforme identificado pelos IDs de cliente OAuth 2.0 da tokens de autorização) que criaram o canal podem interrompê-lo.
• 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/drive/v3/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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