Receber notificações push

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

Visão geral

A API Google Calendar fornece notificações push que permitem monitorar mudanças nos recursos. Você pode usar esse recurso para melhorar o desempenho de seu aplicativo. Ele permite eliminar os custos extras de rede e computação envolvidos na pesquisa de recursos para determinar se eles mudaram. Sempre que um recurso monitorado muda, a API Google Calendar notifica seu aplicativo.

Para usar notificações push, faça 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 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 mensagens. 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 Calendar envia uma mensagem de notificação como uma POST solicitação para esse URL.

No momento, a API Google Calendar oferece suporte a notificações de mudanças nos recursos ACL, CalendarList, Events e Settings.

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 Calendar vai informar seu aplicativo quando qualquer recurso monitorado mudar.

Fazer solicitações de monitoramento

Cada recurso da API Google Calendar que pode ser monitorado tem um método watch associado a 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 está associado a um usuário e a um recurso (ou conjunto de recursos) específico. Uma solicitação watch só será bem-sucedida se o usuário atual for proprietário do recurso ou tiver permissão para acessá-lo.

Exemplo

Comece a monitorar mudanças em uma coleção de eventos em uma agenda específica:

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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

No corpo da solicitação, forneça o id do canal, o type como web_hook e o URL de recebimento em address. Você também pode fornecer:

  • Um token para usar como token de canal.
  • Um tempo de expiration em milissegundos para o prazo de validade do canal solicitado.

Propriedades obrigatórias

Com 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. Comprimento máximo: 64 caracteres.

    O valor do ID definido é repetido no X-Goog-Channel-Id cabeçalho HTTP de cada mensagem de notificação recebida para esse canal.

  • Uma string de propriedade type definida como o valor web_hook.

  • Uma string de propriedade address definida como o URL que escuta e responde a notificações para esse canal de notificação. Esse é o URL de callback do webhook, e ele precisa usar HTTPS.

    A API Google Calendar só pode enviar notificações para esse endereço HTTPS 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 que têm um assunto que não corresponde ao nome do host de destino.

Propriedades opcionais

Você também pode especificar estes campos opcionais com sua watch solicitação:

  • Uma propriedade token que especifica um valor de string arbitrário para usar como 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 seu aplicativo (para garantir que a notificação não seja 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 X-Goog-Channel-Token cabeçalho HTTP em cada mensagem de notificação que seu aplicativo recebe para esse canal.

    Se você usar tokens de canal de notificação, recomendamos que:

    • 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 Calendar 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 cada mensagem 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, Events e Settings na referência da API.

Resposta de monitoramento

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 de monitoramento 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",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events",
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

O corpo da resposta fornece detalhes do canal, como:

  • kind: identifica isso como um recurso de canal da API.
  • id: o ID especificado para esse canal.
  • resourceId: o ID do recurso monitorado.
  • resourceUri: o ID específico da versão do recurso monitorado.
  • token: o token fornecido no corpo da solicitação.
  • expiration: o prazo de validade do canal como um carimbo de data/hora Unix em milissegundos.

Além das propriedades enviadas como parte da solicitação, as informações retornadas também incluem o resourceId e resourceUri para identificar o recurso que está sendo monitorado nesse canal de notificação.

Você pode transmitir as informações retornadas para outras operações de canal de notificação, como quando quiser parar de receber notificações.

Para mais detalhes sobre a resposta, consulte o watch método para os recursos ACL, CalendarList, Events e Settings na referência da API.

Mensagem de sincronização

Depois de 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 começando. O valor do cabeçalho X-Goog-Resource-State HTTP para estas 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.

É 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, poderá usar os valores X-Goog-Channel-ID e X-Goog-Resource-ID em uma chamada para parar de receber notificações. Você também pode usar a sync notificação para fazer alguma inicialização para se preparar para eventos posteriores.

O formato das mensagens sync que a API Google Calendar envia para o 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 X-Goog-Message-Number HTTP 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 prazo de validade, com um valor determinado pela sua solicitação ou por limites ou padrões internos da API Google Calendar (o valor mais restritivo é usado). O prazo de validade do canal, se houver, será incluído como um carimbo de data/hora Unix (em milissegundos) nas informações retornadas pelo watch método. Além disso, a data e a hora de validade são incluídas (em formato legível) em cada mensagem de notificação que seu aplicativo recebe para esse canal no X-Goog-Channel-Expiration cabeçalho HTTP.

No momento, não há uma maneira automática de renovar um canal de notificação. Quando um canal estiver perto do vencimento, 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. É provável que haja um período de "sobreposição" em que os dois canais de notificação do mesmo recurso estejam ativos.

Receber notificações

Sempre que um recurso monitorado muda, seu aplicativo recebe uma mensagem de notificação descrevendo a mudança. A API Google Calendar envia estas mensagens como solicitações HTTPS POST para o URL especificado como a address propriedade para este 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 X-Goog- prefixos. Alguns tipos de notificações também podem incluir um corpo da 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 essa mensagem para esse 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, 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 de validade do canal de notificação, expressas em formato legível. Presente apenas se definido.
X-Goog-Channel-Token Token de canal de notificação 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 postadas pela API Calendar no URL de recebimento não incluem um corpo da mensagem. Essas mensagens não contêm informações específicas sobre recursos atualizados. Você precisa fazer outra chamada de API para conferir os detalhes completos da mudança.

Exemplo

Mensagem de notificação de mudança para uma coleção modificada de eventos:

POST https://mydomain.com/notifications
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 sucesso, retorne 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 uma espera exponencial. Qualquer outro código de status de retorno é considerado uma falha 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 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. As notificações agora podem ser recebidas.
exists ACLs, listas de agendas, eventos, configurações. Um recurso foi alterado. As mudanças possíveis 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 param 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/workspace/calendar/api/v3/reference/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 Calendar tiver vários tipos de recursos com métodos watch, haverá apenas um stop método.

Somente usuários com a permissão certa podem parar um canal. Especificamente:

  • Se o canal foi 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 dos tokens de autenticação) que criou o canal poderá interrompê-lo.
  • Se o canal foi criado por uma conta de serviço, qualquer usuário do mesmo cliente poderá interrompê-lo.

O exemplo de código a seguir mostra como parar de receber notificações:

POST https://www.googleapis.com/workspace/calendar/api/v3/reference/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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