Implementação de referência de exemplo de webhooks do SharePoint
A implementação de referência de PnP (Padrões e Práticas do SharePoint) mostra como você pode usar webhooks do SharePoint no aplicativo. Os webhooks são implementados de uma maneira pronta para a empresa, usando vários componentes do Microsoft Azure, como Azure Web Jobs, Azure SQL Server e Filas de Armazenamento do Azure para lidar com a notificação de trabalhos web assíncrona.
A implementação de referência só funciona com webhooks de lista do SharePoint.
Também pode seguir estes passos ao ver o vídeo no Canal do YouTube da Microsoft 365 Platform Community (PnP):
Aplica-se ao Office 365 Multilocatário (MT)
O Microsoft Azure é usado para hospedar os vários componentes necessários para implementar os webhooks do SharePoint.
O código-fonte e outros materiais para a implementação de referência estão disponíveis em dois níveis:
- Uma versão do aplicativo hospedado pelo provedor do SharePoint
- Um aplicativo do Azure AD do Office 365, que pode ser encontrado no repositório GitHub de exemplos de desenvolvedores do SharePoint.
Implantar a implementação de referência
O aplicativo mostra como gerenciar webhooks, especificamente para uma lista do SharePoint. Ele também contém uma implementação de referência de um ponto de extremidade de serviço de webhook que você pode reutilizar em seus projetos de webhook.
Guias de implantação
- O guia de implantação de implementação de referência de webhooks do SharePoint lista as etapas de implantação usadas para implantar a implementação de referência hospedada pelo provedor do SharePoint.
- Para implantar o aplicativo do Microsoft Azure AD do Office 365, use as etapas descritas em Guia de implantação de implementação de referência do Azure AD de webhooks do SharePoint, que mostra como usar uma função da API Web como um serviço de webhook.
- Se você estiver mais interessado em usar o Azure Functions, confira o Guia do Azure Functions para saber mais sobre como usá-lo na implementação de referência.
Introdução aos webhook
Os webhooks notificam o aplicativo sobre as alterações no SharePoint que o aplicativo precisa monitorar. O aplicativo não precisa mais sondar regularmente se há alterações. Com os webhooks, o aplicativo é notificado (modelo por push) sempre que ocorre uma alteração. Os webhooks não são específicos da Microsoft. Eles são um padrão da Web universal que também está sendo adotado por outros fornecedores (por exemplo, WordPress, GitHub, MailChimp e outros).
Adicionar um webhook à lista do SharePoint
A implementação de referência funciona com uma lista do SharePoint. Para adicionar um webhook a uma lista do SharePoint, primeiro o aplicativo cria uma assinatura de webhook enviando uma solicitação POST /_api/web/lists('list-id')/subscriptions. A solicitação inclui os seguintes itens:
- Uma carga que identifica a lista à qual você está adicionando o webhook.
- O local da URL de serviço de webhook para enviar as notificações.
- A data de expiração do webhook.
Depois que você solicitar que o SharePoint adicione o webhook, o SharePoint valida a existência do ponto de extremidade de serviço do webhook. Envia uma cadeia de validação ao ponto de extremidade de serviço. O SharePoint espera que o ponto de extremidade de serviço retorne a cadeia de validação em cinco segundos. Se esse processo falhar, a criação do webhook será cancelada. Caso você tenha implantado o serviço, isso funcionará e o SharePoint retornará uma mensagem HTTP 201 na solicitação POST que o aplicativo enviou inicialmente. A carga na resposta contém a ID da nova assinatura de webhook.
Examine a implementação de referência e você verá que todas as operações CRUD webhook são consolidadas na classe WebHookManager do projeto SharePoint.WebHooks.Common. A adição de um webhook é feita usando o método AddListWebHookAsync:
/// <summary>
/// This method adds a webhook to a SharePoint list. Note that you need your webhook endpoint being passed into this method to be up and running and reachable from the internet
/// </summary>
/// <param name="siteUrl">Url of the site holding the list</param>
/// <param name="listId">Id of the list</param>
/// <param name="webHookEndPoint">Url of the webhook service endpoint (the one that will be called during an event)</param>
/// <param name="accessToken">Access token to authenticate against SharePoint</param>
/// <param name="validityInMonths">Optional webhook validity in months, defaults to 3 months, max is 6 months</param>
/// <returns>subscription ID of the new webhook</returns>
public async Task<SubscriptionModel> AddListWebHookAsync(string siteUrl, string listId, string webHookEndPoint, string accessToken, int validityInMonths = 3)
{
// webhook add code...
}
Ao fazer uma chamada ao SharePoint, você precisará fornecer informações de autenticação e, nesse caso, está usando um cabeçalho Bearer de autenticação com um token de acesso. Para obter o token de acesso, intercepte o token por meio de um manipulador de eventos ExecutingWebRequest:
ClientContext cc = null;
// Create SharePoint ClientContext object...
// Add ExecutingWebRequest event handler
cc.ExecutingWebRequest += Cc_ExecutingWebRequest;
// Capture the OAuth access token since we want to reuse that one in our REST requests
private void Cc_ExecutingWebRequest(object sender, WebRequestEventArgs e)
{
this.accessToken = e.WebRequestExecutor.RequestHeaders.Get("Authorization").Replace("Bearer ", "");
}
O SharePoint chama o serviço de webhook
Quando o SharePoint detecta uma alteração em uma lista para a qual você criou uma assinatura de webhook, o ponto de extremidade de serviço é chamado pelo SharePoint. Ao examinar a carga do SharePoint, observe que as seguintes propriedades são importantes:
| Propriedade | Descrição |
|---|---|
| A ID da assinatura de webhook. Se desejar atualizar a assinatura de webhook, por exemplo, para prolongar a expiração do webhook, você precisará dessa ID. | |
| A ID da lista para a qual a alteração aconteceu. | |
| A URL relativa do servidor do site que contém o recurso para o qual a alteração aconteceu. |
Observação
O SharePoint só envia uma notificação de que uma alteração aconteceu, mas a notificação não inclui o que realmente foi alterado. Como você obtém informações sobre a Web e a lista que foram alteradas, isso significa que pode usar o mesmo ponto de extremidade de serviço para manipular eventos de webhook de vários sites e listas.
Quando o serviço é chamado, é importante que ele responda com uma mensagem HTTP 200 em até cinco segundos. Neste artigo você aprenderá mais sobre o tempo de resposta, mas, essencialmente, isso requer que lide com as notificações de forma assíncrona. Nesta implementação de referência, você fará isso usando Azure Web Jobs e Filas de Armazenamento do Microsoft Azure.
Localize as alterações em relação às quais o serviço precisa agir
Na etapa anterior, o ponto de extremidade de serviço foi chamado, mas o SharePoint só fornece informações sobre onde a mudança aconteceu, não o que realmente foi alterado. Para entender o que foi alterado, você precisará usar a API GetChanges() do SharePoint, conforme mostrado na imagem a seguir.
Você pode saber mais sobre a implementação GetChanges() no método ProcessNotification na classe ChangeManager do projeto SharePoint.WebHooks.Common.
Para evitar receber a mesma alteração repetidamente, é importante que você informe o SharePoint a partir de que ponto deseja receber as alterações. Isso é feito passando um changeToken, que também implica que o ponto de extremidade de serviço precisa persistir o último changeToken usado, para que ele possa ser usado na próxima vez que o ponto de extremidade de serviço for chamado.
Estas são algumas questões importantes sobre as alterações:
- O SharePoint não chama o serviço em tempo real: quando uma alteração ocorre em uma lista que tem um webhook, o SharePoint coloca na fila uma chamada de webhook. Uma vez por minuto, essa fila é lida e os pontos de extremidade de serviço apropriados são chamados. Esse processamento em lotes de solicitações é importante. Por exemplo, se um carregamento em massa de 1000 registros ocorrer de uma só vez, o processamento em lotes impedirá que o SharePoint chame o ponto de extremidade 1000 vezes. Assim, o ponto de extremidade é chamado somente uma vez, mas quando você chamar o método
GetChanges(), obtém 1000 eventos de alterações que precisa processar. - Para garantir uma resposta imediata, independentemente da quantidade de alterações, é importante que a carga de trabalho do ponto de extremidade de serviço seja executada de forma assíncrona. Na implementação da referência, aproveitamos a capacidade do Azure: o serviço serializa a carga de entrada e a armazena em uma fila de Armazenamento do Microsoft Azure, enquanto há um trabalho Web do Azure que é executado continuamente e verifica se há mensagens na fila. Quando há mensagens na fila, o trabalho Web as processa e também executa sua lógica de forma assíncrona.
Concluir o fluxo de ponta a ponta
O seguinte diagrama descreve o fluxo de webhook completo de ponta a ponta.
- O aplicativo cria uma assinatura de webhook. Quando ele faz isso, obtém o changeToken atual da lista para o qual criou o webhook.
- O aplicativo persiste o changeToken em um armazenamento persistente, como o SQL Azure, nesse caso.
- Ocorre uma alteração no SharePoint e o SharePoint chama seu ponto de extremidade de serviço.
- O ponto de extremidade de serviço serializa a solicitação de notificação e a armazena na fila de armazenamento.
- O trabalho Web vê a mensagem na fila e inicia a lógica de processamento de mensagens.
- A lógica de processamento de mensagens recupera o último token de alteração usado no armazenamento persistente.
- A lógica de processamento de mensagens usa a
GetChanges()API para determinar o que foi alterado. - As alterações retornadas são processadas e, agora, o aplicativo executa o que precisa ser feito com base nas alterações.
- Finalmente, o aplicativo persiste o último changeToken recuperado para que, na próxima vez, ele não receba alterações que já foram processadas.
Trabalhar com a renovação de webhooks
As assinaturas de webhooks são definidas para expirar em seis meses por padrão ou na data especificada quando são criadas. Muitas vezes, é necessário que o webhook esteja disponível por mais tempo. Os padrões descritos nas seções a seguir são adequados para aumentar o tempo de vida de uma assinatura de webhook. O primeiro padrão é leve e o segundo é um pouco mais complexo e requer que um trabalho Web adicional seja hospedado.
Modelo básico
Quando o serviço recebe uma notificação, também obtém informações sobre o tempo de vida de assinatura. Se a subscrição estiver prestes a expirar, dentro da lógica de processamento de notificações, basta prolongar a duração da subscrição. Esse modelo é implementado nesta implementação de referência e funciona bem na maioria dos casos. No entanto, em casos em que não há nenhuma alteração por seis meses na lista para a qual você criou uma assinatura de webhook, a assinatura de webhook nunca é prolongada e é excluída.
Modelo confiável, porém mais complexo
Crie um trabalho Web que lê semanalmente todas as IDs de assinatura do armazenamento persistente. Uma por uma, estenda sempre as assinaturas encontradas.
Observação
Esse trabalho Web não faz parte da implementação de referência.
A renovação real de um webhook de lista do SharePoint pode ser feita usando uma chamada REST PATCH /_api/web/lists('list-id')/subscriptions(‘subscriptionID’).
Na implementação de referência, a atualização de webhooks é implementada na classe WebHookManager do projeto SharePoint.WebHooks.Common.
A atualização de um webhook é feita usando o método UpdateListWebHookAsync:
/// <summary>
/// Updates the expiration datetime (and notification URL) of an existing SharePoint list webhook
/// </summary>
/// <param name="siteUrl">Url of the site holding the list</param>
/// <param name="listId">Id of the list</param>
/// <param name="subscriptionId">Id of the webhook subscription that we need to update</param>
/// <param name="webHookEndPoint">Url of the webhook service endpoint (the one that will be called during an event)</param>
/// <param name="expirationDateTime">New webhook expiration date</param>
/// <param name="accessToken">Access token to authenticate against SharePoint</param>
/// <returns>true if successful, exception in case something went wrong</returns>
public async Task<bool> UpdateListWebHookAsync(string siteUrl, string listId, string subscriptionId, string webHookEndPoint, DateTime expirationDateTime, string accessToken)
{
// webhook update code...
}
Depurando webhooks
Como o SharePoint está chamando o ponto de extremidade de serviço de webhook, o ponto de extremidade precisa ser acessível pelo SharePoint. Isso torna o desenvolvimento e a depuração um pouco mais complexos. Estas são algumas estratégias que você pode usar para facilitar o trabalho:
- Durante o desenvolvimento inicial, você pode fornecer sua própria carga serializada para a lógica de processamento de serviço. Isso torna possível testar completamente a lógica de processamento sem implantar o ponto de extremidade de serviço (e até mesmo sem configurar um webhook).
- Se tiver acesso aos recursos do Azure, você poderá implantar o ponto de extremidade para o Azure usando uma compilação de depuração e configurar o Serviço de Aplicativo do Azure para depuração. Isso permite que você defina um ponto de interrupção remoto e faça a depuração remota usando o Visual Studio.
- Se não quiser implantar o serviço durante o período de desenvolvimento, você precisa usar um túnel seguro para o serviço. A ideia é informar ao SharePoint que o serviço de notificação está localizado em um ponto de extremidade público compartilhado. No cliente, instale um componente que se conecta ao serviço público compartilhado e, sempre que é feita uma chamada ao ponto de extremidade público, o componente do cliente é notificado e envia a carga do serviço ao host local em execução. ngrok é uma implementação de uma ferramenta de túnel segura que você pode usar para depurar o serviço de webhook localmente.