Utilisation de webhooks

Configurer des webhooks avec SharePoint Embedded

Les webhooks sont des messages automatisés transmis par une application lorsqu’un déclencheur est activé. Ils peuvent être utilisés dans SPE pour permettre l’automatisation des flux de travail, l’intégration des systèmes et pour répondre aux événements en temps réel.

Vous utiliserez des webhooks pour appeler le API Cognitive Services Azure à partir de l’application chaque fois qu’un fichier existant est mis à jour ou qu’un nouveau fichier est chargé.

Pour configurer des webhooks avec votre application SharePoint Embedded actuelle, vous devez :

1. Créez et inscrivez un point de terminaison webhook pour recevoir des notifications chaque fois qu’une modification est apportée à votre conteneur. Cette opération sera effectuée à l’aide d’API REST.
2. Connectez-vous à Graph et abonnez-vous aux modifications. Vous pouvez exposer votre application à Internet en l’exécutant localement ou en la déployant sur le cloud. Pour ce tutoriel, vous allez utiliser le premier en utilisant ngrok, puis en vous abonnant aux modifications en effectuant un appel POST.
3. Effectuez l’action souhaitée en gérant les données du webhook. L’un de ces cas d’usage est abordé dans le didacticiel Activation du traitement des documents avec Azure Cognitive Services.

Conseil

Pour en savoir plus sur les API Microsoft Graph utilisées dans ce tutoriel, consultez Créer un abonnement.

Créer et inscrire un webhook

Ouvrez le fichier index.ts et ajoutez un point de terminaison 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();
});

Vous devez également ajouter le plug-in de l’analyseur de requête en haut de ce fichier afin qu’il s’exécute au démarrage du serveur :

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

Créez onReceiptAdded.ts et implémentez la méthode onReceiptAdded pour lire validationToken et driveId. validationToken est requis lorsque Microsoft Graph effectue un appel unique pour vérifier le point de terminaison lors de la création de l’abonnement webhook. driveId est l’id de conteneur pour lequel l’abonnement est créé.

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

Se connecter à Graph et s’abonner aux modifications

Suivez la documentation pour créer un tunnel pour votre serveur principal à l’aide de ngrok.

Après avoir démarré l’application, exécutez la commande suivante dans un terminal :

ngrok http 3001

Une fois l’opération terminée, vous devez obtenir la sortie suivante. Le point de terminaison public de l’application est mis en surbrillance dans le rectangle rouge :

Une fois le tunneling actif, vous pouvez vous abonner aux modifications delta dans le conteneur en ajoutant l’URL du webhook. Pour ce faire, ouvrez Postman et effectuez la requête suivante POST avec le jeton d’accès au graphique approprié et notificationUrl avec le driveId ajouté en tant que paramètre de requête pour vous assurer que vous recevez des notifications pour les modifications uniquement dans le conteneur souhaité.

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

Vous pouvez utiliser l’extrait de code suivant pour définir le délai d’expiration maximal possible de 4230 minutes à partir de l’heure actuelle en ajoutant ce code à la section « Script de pré-demande ». Il définit une variable d’environnement qui peut être utilisée dans le corps de la requête.

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

À ce stade, si vous ajoutez/mettez à jour un fichier dans le conteneur, vous recevez une notification au point de terminaison précédemment ajouté (/api/onReceiptAdded) et un message de journal sur la console : Received driveId: <containerId>