Responder a alterações de arquivo e contêiner com webhooks

Aplica-se a: Desenvolvedor

Use webhooks do Microsoft Graph quando seu aplicativo precisar reagir a alterações de arquivo em um contêiner do SharePoint Embedded. Uma assinatura informa ao Microsoft Graph para chamar seu ponto de extremidade HTTPS quando o recurso inscrito for alterado.

Criar um ponto de extremidade de notificação

Exponha um ponto de extremidade HTTPS que aceita POST solicitações. Durante o desenvolvimento local, use o ngrok para encapsular solicitações para um servidor local.

ngrok http 3001

Quando o Microsoft Graph cria uma assinatura, ele valida o ponto de extremidade enviando um validationToken parâmetro de consulta. Retorne esse token como texto sem formatação 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, "");
}

Registre a rota em seu servidor de API e habilite o corpo da solicitação e a análise de consulta antes que a rota lide com 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();
});

Inscrever-se em uma unidade de contêiner

Crie a assinatura com o Microsoft Graph. Nesse padrão, a ID do contêiner do SharePoint Embedded é a 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": "{future-expiration-date-time}",
  "clientState": ""
}

Assine as alterações na drives/{container-id}/root URL de notificação e anexe-a driveId={container-id} a ela para que o manipulador possa identificar o contêiner.

Calcular expiração

As assinaturas de item de unidade têm um tempo de vida máximo de 4.230 minutos. Use um script de pré-solicitação ou um agendador de back-end para definir o tempo de expiração antes de criar a assinatura.

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

Armazene a ID da assinatura, o recurso, a ID do contêiner e o tempo de expiração. Renove cada assinatura antes que ela expire.

Processar notificações com segurança

Retorne rapidamente da solicitação do webhook. Enfileire o trabalho em segundo plano, busque o estado atual do arquivo ou contêiner com o Microsoft Graph e torne o processamento idempotente porque as notificações podem ser duplicadas ou atrasadas.

Use webhooks para ações como processamento de documentos, atualização de índice, notificações do usuário ou gatilhos de fluxo de trabalho. Mantenha um trabalho de reconciliação periódico para notificações perdidas ou assinaturas expiradas.

Verificar o fluxo

Crie uma assinatura, carregue ou atualize um arquivo no contêiner e confirme se o ponto de extremidade registra a ID de unidade esperada. Se a validação falhar, marcar a URL HTTPS pública, o tipo de conteúdo de validationToken resposta e se o servidor analisa os parâmetros de consulta antes da execução da rota.

Próximas etapas

• Arquivo e restauração de contêineres