Inscreva-se nos webhooks para receber notificações de alteração

  • Artigo

Aplica-se: Blocos de anotações do consumidor no OneDrive

Mantenha-se atualizado com as alterações feitas pelos usuários no OneNote, inscrevendo-se no serviço Webhooks.

Se você tiver um aplicativo Web ou serviço da Web que expõe um ponto de extremidade público, poderá receber notificações quase em tempo real quando forem feitas alterações aos blocos de anotações do OneNote pessoais dos usuários no OneDrive.

As notificações são enviadas quando uma alteração é feita em um bloco de anotações pertencente a um dos seus usuários. Isso inclui alterações em qualquer nível na hierarquia do bloco de anotações, incluindo alterações no conteúdo da página.

As notificações não contêm informações detalhadas sobre alterações ou usuários. Elas alertam quando uma alteração é feita, para que depois o manipulador de eventos possa consultar detalhes específicos. O serviço Webhooks não suporta assinaturas refinadas para tipos específicos de alterações ou recursos.

As notificações são enviadas como solicitações POST que contêm um objeto JSON, conforme mostrado no exemplo a seguir.

{
  "value":[
    {
      "subscriptionId":"client-id-of-your-registered-application",
      "userId":"id-of-the-user-who-owns-the-changed-resource" 
    }
  ]
}

Seu serviço deve responder prontamente à notificação com um dos seguintes códigos de status HTTP:

  • 200 OK
  • 202 Aceito
  • 204 Nenhum conteúdo (No Content)

Se não recebermos a resposta, tentaremos novamente algumas vezes com retirada exponencial e, finalmente, descartaremos a mensagem.

Para obter mais informações sobre as notificações

  • O escopo das notificações abrange o conteúdo dos seus usuários, independentemente de quem fez a alteração. As notificações não são enviadas com relação a alterações feitas no conteúdo compartilhado com seus usuários. Portanto, se Bob (que não é seu usuário) fizer uma alteração em um bloco de anotações da Alice (seu usuário), você receberá uma notificação com o ID de usuário da Alice. Você não receberá uma notificação se Alice alterar o bloco de anotações de Bob.

  • A userId (ID do usuário) na notificação corresponde à ID retornada no cabeçalho X-AuthenticatedUserId das respostas da API do OneNote.

  • Alterações feitas em um breve período podem ser combinadas em uma única notificação.

  • As notificações geralmente são enviadas alguns minutos após a alteração. Essa latência garante que as alterações estejam disponíveis para a API, mesmo que a alteração esteja disponível imediatamente no cliente.

Fluxo de trabalho de notificações

Um fluxo de trabalho típico de notificações de alto nível tem este aspecto:

  1. As alterações são feitas em um bloco de anotações de um de seus usuários.
  2. O OneNote envia uma ou mais solicitações POST para o seu URL de retorno de chamada registrado. Cada solicitação POST representa uma ou mais alterações.
  3. Seu serviço responde a cada solicitação POST com um código de status HTTP 200, 202 ou 204.
  4. As notificações disparam um manipulador de eventos na sua API de retorno de chamada.
  5. Você consulta o serviço OneNote para conferir as alterações detalhadas.

Consultar com base no carimbo de data/hora da última alteração é a melhor maneira de garantir que você capture todas as alterações. Armazene o carimbo de data/hora da lastModifiedTime mais recente dos resultados e use-o na sua próxima consulta de alteração.

Este pedido usa a propriedade lastModifiedTime para retornar todas as páginas que foram alteradas desde o carimbo de data/hora armazenado:

GET ../me/notes/pages?filter=lastModifiedTime%20ge%20{stored-iso-8601-timestamp}

Depois de consultar as alterações, atualize seu carimbo de data/hora armazenado com a lastModifiedTime mais recente.

Observação

O serviço Webhooks não deve ser usado como um mecanismo de sincronização. Você deve consultar periodicamente as alterações no caso de não ser possível enviar ou receber uma notificação.

Como se inscrever no serviço Webhooks

Para se inscrever no serviço Webhooks do OneNote, você precisará:

  • Registrar um URL de retorno de chamada que seja um ponto de extremidade público (HTTP ou HTTPS) onde você receberá solicitações HTTP POST do serviço Webhooks do OneNote. O serviço Webhooks não seguirá redirecionamentos HTTP.

  • Solicite as seguintes permissões para seu aplicativo:

    • wl.offline_access (Permissão de conta da Microsoft)
    • office.onenote, office.onenote_create, office.onenote_update_by_appou office.onenote_update para a API do OneNote, dependendo das capacidades do seu aplicativo

Quando você estiver pronto para se inscrever, entre em contato conosco: @onenotedev. Alguém da nossa equipe irá trabalhar com você na configuração.

À medida que seus usuários se registram no seu aplicativo, você deve fazer uma chamada para a API do OneNote em nome deles (por exemplo: GET ../me/notes/notebooks). Esta chamada irá:

  • Garantir que o OneNote registra o usuário para notificações de retorno de chamada.
  • Permitir recuperar e armazenar a ID do usuário, que é retornada no cabeçalho de resposta X-AuthenticatedUserId.

Modelo de expiração

Para notificações do webhook, registramos as IDs dos seus usuários. Cada interação feita por um determinado usuário renova o registro do usuário por seis meses.

Um registro fica inativo após um período de seis meses sem chamar a API do OneNote em nome do usuário. Você não receberá notificações de usuários inativos, incluindo usuários que desinstalaram seu aplicativo ou revogaram suas permissões.

Como as notificações de alteração não contêm detalhes sobre o usuário ou a alteração, o risco potencial à privacidade do usuário é reduzido. Os usuários inativos são registrados novamente sempre que você chama a API do OneNote em nome deles.

Confira também