Respuesta a los cambios de archivos y contenedores con webhooks

Se aplica a: Desarrollador

Use webhooks de Microsoft Graph cuando la aplicación tenga que reaccionar ante los cambios de archivo en un contenedor de SharePoint Embedded. Una suscripción indica a Microsoft Graph que llame al punto de conexión HTTPS cuando cambie el recurso suscrito.

Creación de un punto de conexión de notificación

Exponga un punto de conexión HTTPS que acepte POST solicitudes. Durante el desarrollo local, use ngrok para tunelizar las solicitudes a un servidor local.

ngrok http 3001

Cuando Microsoft Graph crea una suscripción, valida el punto de conexión mediante el envío de un parámetro de validationToken consulta. Devuelve ese token como texto sin formato con 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 la ruta en el servidor de API y habilite el cuerpo de la solicitud y el análisis de consultas antes de que la ruta controle las notificaciones.

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();
});

Suscripción a una unidad de contenedor

Cree la suscripción con Microsoft Graph. En este patrón, el identificador de contenedor de SharePoint Embedded es el identificador de unidad.

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": ""
}

Suscríbase a los cambios en drives/{container-id}/root y anexe driveId={container-id} a la dirección URL de notificación para que el controlador pueda identificar el contenedor.

Cálculo de la expiración

Las suscripciones a elementos de unidad tienen una duración máxima de 4.230 minutos. Use un script de solicitud previa o un programador de back-end para establecer la hora de expiración antes de crear la suscripción.

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

Almacene el identificador de suscripción, el recurso, el identificador de contenedor y la hora de expiración. Renueve cada suscripción antes de que expire.

Procesar notificaciones de forma segura

Vuelva rápidamente desde la solicitud de webhook. Trabajo en segundo plano de la cola, captura el estado actual del archivo o contenedor con Microsoft Graph y hace que el procesamiento sea idempotente porque las notificaciones se pueden duplicar o retrasar.

Use webhooks para acciones como el procesamiento de documentos, la actualización de índices, las notificaciones de usuario o los desencadenadores de flujo de trabajo. Mantenga un trabajo de conciliación periódico para las notificaciones perdidas o las suscripciones expiradas.

Comprobación del flujo

Cree una suscripción, cargue o actualice un archivo en el contenedor y confirme que el punto de conexión registra el identificador de unidad esperado. Si se produce un error en la validación, compruebe la dirección URL HTTPS pública, el tipo de contenido de respuesta validationToken y si el servidor analiza los parámetros de consulta antes de la ejecución de la ruta.

Pasos siguientes

• Archivo y restaurar contenedores