Esta página foi traduzida pela API Cloud Translation.

Notificações push

Neste documento, descrevemos como usar notificações push que informam seu aplicativo quando um recurso é modificado.

Visão geral

A API Google Calendar 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 Google Calendar 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".
É 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 Google Calendar envia uma mensagem de notificação como uma solicitação POST para esse URL.

Atualmente, a API Google Calendar é compatível com notificações de mudanças nos recursos Acl, CalendarList, Eventos e Configurações.

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 Calendar informa ao aplicativo quando algum recurso monitorado muda.

Fazer solicitações para assistir

Cada recurso da API Google Calendar que pode ser assistido 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 seja proprietário ou tenha permissão para acessar esse recurso.

Exemplo

Comece a observar alterações em uma coleção de eventos de uma determinada agenda:

POST https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events/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-myCalendarChannelDest", // (Optional) Your channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration time.
}

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 valor web_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.

Observe que a API Google Calendar só consegue enviar notificações para esse endereço HTTPS quando há 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 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.
Observação: se você precisar enviar dados altamente confidenciais, verifique se eles estão criptografados antes de adicioná-los ao token.
Uma string de propriedade expiration definida como um carimbo de data/hora Unix (em milissegundos) da data e da hora em que você quer que a API Google Calendar pare de enviar mensagens a 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 para os recursos Acl, CalendarList, Eventos e Configurações 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": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events", // Version-specific ID of the watched resource.
  "token": "target=myApp-myCalendarChannelDest", // Present only if one was provided.
  "expiration": 1426325213000, // 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.

Observação:a propriedade resourceId é um identificador estável e independente da versão para o recurso. A propriedade resourceUri é o URI canônico do recurso monitorado no contexto da versão atual da API. Por isso, ela é específica para a versã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 para os recursos Acl, CalendarList, Eventos e Configurações na Referência da API.

Sincronizar mensagem

Após criar um canal de notificação para monitorar um recurso, a API Google Calendar 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.

Confira abaixo o formato das mensagens sync que a API Google Calendar 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 limites internos ou padrões da API Google Calendar. É 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 Google Calendar envia essas mensagens como solicitações HTTPS POST para o URL especificado como a propriedade address desse canal de notificação.

Observação:as solicitações HTTPS de entrega de notificações especificam um user agent de APIs-Google e respeitam as diretivas robots.txt, conforme descrito em APIs User agent do 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 o corpo de uma mensagem.

Cabeçalhos

As mensagens de notificação postadas pela API Google Calendar no URL de recebimento incluem os seguintes cabeçalhos HTTP:

Cabeçalho	Descrição
Sempre presente
`X-Goog-Channel-ID`	UUID ou outra string exclusiva fornecida para identificar esse canal de notificação.
`X-Goog-Message-Number`	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.
`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`, `exists` ou `not_exists`.
`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 da 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 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 postadas pela API Google Calendar no URL de recebimento não incluem o corpo da mensagem. Essas mensagens não contêm informações específicas sobre os recursos atualizados. Será necessário fazer outra chamada de API para ver todos os detalhes da mudança.

Exemplos

Altere a mensagem de notificação para coleção modificada de eventos:

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/calendar/v3/calendars/my_calendar@gmail.com/events
X-Goog-Resource-State:  exists
X-Goog-Message-Number: 10

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 Google Calendar vai 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 Google Calendar

Esta seção fornece detalhes sobre as mensagens de notificação que você pode receber ao usar as notificações push com a API Google Calendar.

X-Goog-Resource-State	Aplicável a	Entregue quando
`sync`	ACLs, listas de agendas, eventos, configurações.	Um novo canal foi criado. Você vai começar a receber notificações sobre ele.
`exists`	ACLs, listas de agendas, eventos, configurações.	Houve uma alteração em um recurso. As possíveis alterações incluem a criação de um novo recurso ou a modificação ou exclusão de um recurso existente.

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/calendar/v3/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 Google Calendar 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/calendar/v3/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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

Considerações especiais

Ao trabalhar com notificações push, lembre-se do seguinte:

Eventos e ACLs são por agenda Se você quiser receber notificações sobre todas as alterações em eventos ou ACLs das agendas A e B, inscreva-se separadamente nos eventos/coleções de ACLs de A e B.

Configurações e listas de agendas por usuário Como as configurações e as listas de agendas só têm uma coleção por usuário, é possível se inscrever apenas uma vez.

Além disso, você não será notificado quando tiver acesso a uma nova coleção (por exemplo, uma nova agenda), embora seja notificado quando essa agenda for adicionada à lista de agendas (supondo que você esteja inscrito na coleção da lista de agendas).

As notificações não são 100% confiáveis. É esperado que uma pequena porcentagem das mensagens seja descartada em condições normais de trabalho. Gerencie essas mensagens ausentes corretamente para que o aplicativo ainda seja sincronizado mesmo que nenhuma mensagem de push seja recebida.