Utilizar Webhooks

Configurar Webhooks com o SharePoint Embedded

Os webhooks são mensagens automatizadas que são transmitidas por uma aplicação quando um acionador é ativado. Podem ser utilizadas no SPE para permitir a automatização de fluxos de trabalho, a integração de sistemas e a resposta a eventos em tempo real.

Irá utilizar webhooks para invocar o API de Serviços Cognitivos do Azure a partir da aplicação sempre que um ficheiro existente for atualizado ou for carregado um novo ficheiro.

Para configurar webhooks com a sua aplicação SharePoint Embedded atual, tem de:

1. Crie e registe um ponto final de webhook para receber notificações sempre que houver uma alteração no contentor. Isto será feito com as APIs REST.
2. Ligue-se ao Graph e subscreva as alterações. Pode expor a sua aplicação na Internet ao executá-la localmente ou ao implementá-la na cloud. Neste tutorial, irá utilizar o primeiro ao utilizar o ngrok e, em seguida, subscrever as alterações ao fazer uma chamada POST.
3. Execute qualquer ação pretendida ao processar os dados do webhook. Um desses casos de utilização é abordado no tutorial Ativar o processamento de documentos com os Serviços Cognitivos do Azure.

Dica

Para saber mais sobre as APIs do Microsoft Graph utilizadas neste tutorial, veja Criar subscrição.

Criar e registar um webhook

Abra o ficheiro index.ts e adicione um ponto onReceiptAddedfinal:

server.post('/api/onReceiptAdded', async (req, res, next) => {
  try {
    const response = await onReceiptAdded(req, res);
    res.send(200, response)
  } catch (error: any) {
    res.send(500, { message: `Error in API server: ${error.message}` });
  }
  next();
});

Também tem de adicionar o plug-in do analisador de consultas na parte superior deste ficheiro para que seja executado no arranque do servidor:

server.use(restify.plugins.bodyParser(), restify.plugins.queryParser());

Crie onReceiptAdded.ts e implemente o método onReceiptAdded para ler validationToken e driveId. validationToken é necessário quando o Microsoft Graph faz uma chamada única para verificar o ponto final após a criação da subscrição do webhook. driveId é o container-id para o qual a subscrição é criada.

require('isomorphic-fetch');

export const onReceiptAdded = async (req: Request, res: Response) => {

  const validationToken = req.query['validationToken'];
  if (validationToken) {
    res.send(200, validationToken, {"Content-Type":"text/plain"});
    return;
  }

  const driveId = req.query['driveId'];
  if (!driveId) {
    res.send(200, "Notification received without driveId, ignoring", {"Content-Type":"text/plain"});
    return;
  }

  console.log(`Received driveId: ${driveId}`);

  res.send(200, "");
  return;
}

Ligar ao Graph e subscrever alterações

Siga a documentação para criar um túnel para o servidor back-end com o ngrok.

Depois de iniciar a aplicação, execute o seguinte comando num terminal:

ngrok http 3001

Após a conclusão com êxito, deverá obter o seguinte resultado. O ponto final destinado ao público da aplicação está realçado no retângulo vermelho:

Assim que o túnel estiver ativo, pode subscrever as alterações delta no contentor ao adicionar o URL do webhook. Para tal, abra o Postman e faça o seguinte POST pedido com o token de acesso ao grafo adequado e notificationUrl com o driveId anexado como um parâmetro de consulta para garantir que recebe notificações de alterações apenas no contentor pretendido.

POST  https://graph.microsoft.com/v1.0/subscriptions
{
  "changeType": "updated",
  "notificationUrl":"https://5ac2-2404-f801-8028-3-691a-87b2-d309-545b.ngrok-free.app/api/onReceiptAdded?driveId={{ContainerId}}",
  "resource": "drives/{{ContainerId}}/root",
  "expirationDateTime": "2024-01-20T03:58:34.088Z",
  "clientState": ""
}

Pode utilizar o seguinte fragmento de código para definir o tempo máximo de expiração possível de 4230 minutos a partir da hora atual ao adicioná-lo à secção "Script de Pré-pedido". Irá definir uma variável de ambiente que pode ser utilizada no corpo do pedido.

var now = new Date()
var duration = 1000 * 60 * 4230; // max lifespan of driveItem subscription is 4230 minutes
var expiry = new Date(now.getTime() + duration);
var expiryDateTime = expiry.toISOString();

pm.environment.set("ContainerSubscriptionExpiry", expiryDateTime);

Neste momento, se adicionar/atualizar qualquer ficheiro no contentor, receberá uma notificação no ponto final adicionado anteriormente (/api/onReceiptAdded) e uma mensagem de registo na consola do : Received driveId: <containerId>