Responder a alterações de ficheiros e contentores com webhooks

Aplica-se a: Programador

Utilize webhooks do Microsoft Graph quando a sua aplicação tiver de reagir a alterações de ficheiros num contentor do SharePoint Embedded. Uma subscrição indica ao Microsoft Graph para chamar o ponto final HTTPS quando o recurso subscrito for alterado.

Criar um ponto final de notificação

Expor um ponto final HTTPS que aceita POST pedidos. Durante o desenvolvimento local, utilize ngrok para fazer o túnel de pedidos para um servidor local.

ngrok http 3001

Quando o Microsoft Graph cria uma subscrição, valida o ponto final ao enviar um validationToken parâmetro de consulta. Devolva esse token como texto simples com HTTP 200.

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, "");
}

Registe a rota no servidor de API e ative a análise do corpo do pedido e da consulta antes de a rota processar as notificações.

server.use(restify.plugins.bodyParser(), restify.plugins.queryParser());
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();
});

Subscrever uma unidade de contentor

Crie a subscrição com o Microsoft Graph. Neste padrão, o ID de contentor do SharePoint Embedded é o ID da unidade.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "updated",
  "notificationUrl": "https://contoso.example/api/onReceiptAdded?driveId={container-id}",
  "resource": "drives/{container-id}/root",
  "expirationDateTime": "2026-06-25T03:58:34.088Z",
  "clientState": ""
}

Subscreva as alterações drives/{container-id}/root em e acrescente driveId={container-id} ao URL de notificação para que o processador possa identificar o contentor.

Calcular a expiração

As subscrições de itens de unidade têm uma duração máxima de 4.230 minutos. Utilize um script de pré-pedido ou um agendador de back-end para definir o tempo de expiração antes de criar a subscrição.

var now = new Date();
var duration = 1000 * 60 * 4230;
var expiry = new Date(now.getTime() + duration);
pm.environment.set("ContainerSubscriptionExpiry", expiry.toISOString());

Armazene o ID da subscrição, o recurso, o ID do contentor e o tempo de expiração. Renove cada subscrição antes de expirar.

Processar notificações com segurança

Regresse rapidamente a partir do pedido do webhook. Trabalho em segundo plano da fila, obter o ficheiro atual ou o estado do contentor com o Microsoft Graph e tornar o idempotente de processamento porque as notificações podem ser duplicadas ou atrasadas.

Utilize webhooks para ações como processamento de documentos, atualização de índices, notificações de utilizador ou acionadores de fluxo de trabalho. Mantenha uma tarefa de reconciliação periódica para notificações perdidas ou subscrições expiradas.

Verificar o fluxo

Crie uma subscrição, carregue ou atualize um ficheiro no contentor e confirme se o ponto final regista o ID de unidade esperado. Se a validação falhar, marcar o URL HTTPS público, o validationToken tipo de conteúdo de resposta e se o servidor analisa os parâmetros de consulta antes da execução da rota.

Próximas etapas

• Arquivo e restaurar contentores