Uso de webhooks

Configuración de webhooks con SharePoint Embedded

Los webhooks son mensajes automatizados que transmite una aplicación cuando se activa un desencadenador. Se pueden usar en SPE para permitir la automatización de flujos de trabajo, la integración de sistemas y responder a eventos en tiempo real.

Usará webhooks para invocar la Cognitive Services APIs de Azure desde la aplicación cada vez que se actualice un archivo existente o se cargue un nuevo archivo.

Para configurar webhooks con la aplicación de SharePoint Embedded actual, debe:

1. Cree y registre un punto de conexión de webhook para obtener notificaciones cada vez que haya un cambio en el contenedor. Esto se realizará mediante las API REST.
2. Conéctese a Graph y suscríbase a los cambios. Puede exponer la aplicación a Internet ejecutándola localmente o implementándola en la nube. Para este tutorial, empleará el primero mediante ngrok y, a continuación, suscribirse a los cambios mediante una llamada POST.
3. Realice cualquier acción deseada controlando los datos del webhook. Uno de estos casos de uso se trata en el tutorial Habilitación del procesamiento de documentos con Azure Cognitive Services.

Sugerencia

Para obtener más información sobre las API de Microsoft Graph usadas en este tutorial, consulte Creación de una suscripción.

Creación y registro de un webhook

Abra el archivo index.ts y agregue un punto de conexión onReceiptAdded:

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

También debe agregar el complemento del analizador de consultas en la parte superior de este archivo para que se ejecute al iniciar el servidor:

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

Cree onReceiptAdded.ts e implemente el método onReceiptAdded para leer validationToken y driveId. validationToken es necesario cuando Microsoft Graph realiza una llamada única para comprobar el punto de conexión al crear la suscripción de webhook. driveId es el identificador de contenedor para el que se crea la suscripción.

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

Conectarse a Graph y suscribirse a los cambios

Siga la documentación para crear un túnel para el servidor back-end mediante ngrok.

Después de iniciar la aplicación, ejecute el siguiente comando en un terminal:

ngrok http 3001

Una vez completada correctamente, debe obtener la siguiente salida. El punto de conexión orientado al público de la aplicación se resalta en el rectángulo rojo:

Una vez que la tunelización está activa, puede suscribirse a los cambios diferenciales en el contenedor agregando la dirección URL del webhook. Para ello, abra Postman y realice la siguiente POST solicitud con el token de acceso de grafo adecuado y notificationUrl con el driveId anexado como parámetro de consulta para asegurarse de que recibe notificaciones de cambios solo en el contenedor deseado.

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

Puede usar el siguiente fragmento de código para establecer el tiempo de expiración máximo posible de 4230 minutos a partir de la hora actual agregando esto a la sección "Script de solicitud previa". Establecerá una variable de entorno que se puede usar en el cuerpo de la solicitud.

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

En este punto, si agrega o actualiza cualquier archivo en el contenedor, recibirá una notificación en el punto de conexión agregado anteriormente (/api/onReceiptAdded) y un mensaje de registro en la consola: Received driveId: <containerId>