Esta página foi traduzida pela API Cloud Translation.

Notificações push

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

Visão geral

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

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

Fazer solicitações de monitoramento

Cada recurso observável da API Google Calendar está associado a 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 é proprietário ou tem permissão para acessar esse recurso.

Exemplo

Começar a monitorar as mudanças em uma coleção de eventos em 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

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 Calendar é 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 Calendar 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.

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 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/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, 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 recursos Acl, CalendarList, Events e Settings na Referência da API.

Sincronizar mensagem

Após criar um canal de notificação para observar um recurso, o A API Google Calendar 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 Calendar 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 Calendar. 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 Calendar envia essas 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 Calendar 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`, `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 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 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 conferir os detalhes completos da mudança.

Exemplos

Alterar a mensagem de notificação para o conjunto modificado 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 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 Calendar 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 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. Você vai começar a receber notificações sobre ela.
`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 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/calendar/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 Calendar 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/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, tenha em mente o seguinte:

Eventos e ACLs por agenda Se você quiser receber notificações sobre todos os eventos ou alterações na ACL das agendas A e B, precisará se inscrever separadamente nos eventos/coleções da ACL de A e B.

Configurações e listas de agendas por usuário As configurações e as listas de agendas têm apenas uma coleção por usuário, portanto você só pode se inscrever uma vez.

Além disso, você não será notificado quando tiver acesso a uma nova coleção (por exemplo, uma nova agenda), embora será notificado se 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. É normal que uma pequena porcentagem das mensagens seja descartada em condições normais de trabalho. Não se esqueça de lidar com eles mensagens ausentes normalmente, de modo que o aplicativo ainda é sincronizado mesmo que nenhuma mensagem push seja recebida.