Meilleures pratiques pour la découverte des fichiers et la détection des modifications à l’échelle

SharePoint et OneDrive stockent des millions de fichiers. Il est essentiel d’utiliser les modèles d’appel appropriés pour comprendre tous les fichiers et les modifications à l’échelle. Historiquement, il existe de nombreuses API pour l’accès aux fichiers à un niveau atomique. Bon nombre de ces API ne sont pas efficaces à grande échelle, mais fonctionnent bien pour une interaction d’utilisateur unique. Ces instructions vous guident dans la surveillance d’un client Office 365 ou OneDrive afin que votre application s’intègre à Office 365 avec des performances et une efficacité optimales. Les applications qui ont généralement ce type de besoin sont les moteurs de synchronisation, les fournisseurs de sauvegarde, les indexeurs de recherche, les moteurs de classification et les fournisseurs de protection contre la perte de données.

Obtention des autorisations appropriées

Pour créer une relation de confiance avec les utilisateurs, il est important d’utiliser le jeu minimal d’étendues d’autorisations requises pour le fonctionnement d’une application. La plupart des applications d’analyse souhaitent fonctionner avec des autorisations d’application, ce qui indique que votre application s’exécute indépendamment d’un utilisateur particulier. Pour accéder aux fichiers, vous devez demander l’étendue Files.Read.All ou Files.ReadWrite.All. Pour accéder aux ressources SharePoint, notamment la liste de toutes les collections de sites, Sites.Read.All ou Sites.ReadWrite.All est approprié. Pour traiter correctement les autorisations, vous devrez également demander Sites.FullControl.All.

Types d’autorisation, étendues d’autorisation et utilisateurs

Lorsque vous configurez les autorisations d’une application dans Microsoft Azure, vous pouvez choisir entre les autorisations d’application et les autorisations déléguées. Comme indiqué ci-dessus, la plupart des applications d’analyse souhaitent des autorisations d’application. Les autorisations déléguées exigent que votre application fonctionne dans le contexte d’un utilisateur signé plutôt que globalement. Dans le modèle délégué, vous êtes limité au contenu accessible par l’utilisateur actuel.

Un aspect important des autorisations à noter est que lorsqu’un administrateur accorde des autorisations à une application demandant des autorisations d’application (plutôt que des autorisations déléguées), l’octroi d’autorisation est associé au locataire et à l’application, plutôt qu’à l’utilisateur administrateur. Bien qu’un administrateur soit tenu d’accorder l’accès, l’octroi d’accès ne confère pas d’autorisations administratives spéciales à l’application, au-delà de l’accès aux étendues de ressources demandées par l’application.

Modèle d’appel recommandé

Pour les applications qui traitent de grandes quantités de données provenant de SharePoint et de OneDrive, vous devez suivre un modèle d’appel cohérent comme suit.

1. Découvrir : configurez les emplacements que vous souhaitez analyser.
2. Analyser : découvrez et traitez l’ensemble des fichiers qui vous intéressent.
3. Avertir : surveillez les modifications apportées à ces fichiers via une notification.
4. Traiter les modifications : traiter uniquement les fichiers qui ont été modifiés à l’aide de la requête delta.

Le modèle ressemblera à ce qui suit. Cet article décrit en détail chaque étape d’implémentation.

Chacun de ces éléments peut avoir plusieurs mécanismes pour les accomplir dans l’API Microsoft Graph et les API SharePoint existantes. L’objectif de cet article est de vous offrir la meilleure méthode à votre disposition aujourd’hui pour effectuer chaque tâche.

Découvrir les emplacements à analyser

La configuration des emplacements que vous souhaitez que votre application analyse est un processus manuel aujourd’hui. Dans de nombreux cas, vous souhaitez fournir une expérience d’application orientée utilisateur pour cette étape. C’est vous qui décidez de la façon dont vous exposez cette fonctionnalité et si elle est exposée à tous les utilisateurs ou uniquement aux administrateurs. Vous voudrez déterminer les utilisateurs OneDrive et les sites et sous-sites SharePoint que vous analysez.

Le compte de chaque utilisateur OneDrive contient un lecteur unique que vous pouvez surveiller. Les sous-sites et collections de sites SharePoint peuvent avoir plusieurs lecteurs, un pour chaque bibliothèque de documents du site. Vous pouvez découvrir chaque lecteur d’un site à l’aide du point de terminaison des /lecteurs. Par exemple, pour obtenir tous les lecteurs du site racine du client, vous pouvez utiliser :

https://graph.microsoft.com/v1.0/sites/root/drives

Le lecteur est le point de départ pour les activités de fichier à grande échelle. Vous utiliserez ces lecteurs pour obtenir des listes complètes de fichiers, connecter des webhooks pour les notifications et utiliser la requête delta pour obtenir des ensembles de modifications apportées aux éléments dans les lecteurs.

Comment trouver des collections de sites SharePoint et des lecteurs OneDrive Entreprise

À l’aide de Microsoft Graph avec les autorisations d’application, vous pouvez obtenir la liste complète des collections de sites, y compris les sites contenant les lecteurs OneDrive Entreprise. Pour obtenir cette liste, utilisez l’appel d’API suivant :

GET /sites

L’API d’énumération de sites prend également en charge la requête delta pour obtenir des informations sur les nouveaux sites créés ou les modifications apportées à la structure du site. La prise en charge des requêtes delta pour l’énumération de site est actuellement en cours de déploiement vers la version bêta de Microsoft Graph. Veuillez continuer votre lecture pour plus d’informations sur la requête delta.

Pour recevoir des notifications sur les nouvelles collections de sites, vous pouvez vous abonner à des webhooks à l’aide du point de terminaison des abonnements Microsoft Graph. La ressource cible pour ces notifications est /sites. Vous recevrez des notifications lorsque de nouvelles collections de sites sont créées ou supprimées, ainsi que lors de la création de sous-sites ou de listes.

Analyse et processus à l’aide d’une requête delta

Pour obtenir la liste initiale des fichiers dans un lecteur, appelez une requête delta unique sans paramètre. La requête delta fournit aux applications une analyse initiale de tout le contenu, puis les modifications ultérieures à partir d’un moment donné. La requête delta renvoie le lien nécessaire pour obtenir les modifications futures chaque fois qu’elle est appelée.

Par exemple, si vous souhaitez obtenir tous les fichiers de la bibliothèque de documents par défaut dans un site SharePoint, vous pouvez utiliser cette requête :

/sites/{siteId}/drive/root/delta

Cette API renvoie des pages de résultats qui représentent tous les fichiers du lecteur. Une fois que vous avez récupéré toutes les pages de fichiers à l’aide du retourné @odata.nextLink, vous pouvez refaire la requête delta avec le retourné @odata.deltaLink pour obtenir des modifications depuis la dernière fois que vous avez appelé la requête delta. N’oubliez pas de conserver l’URL retournée par @odata.deltaLink afin de pouvoir vérifier efficacement les modifications ultérieurement.

Les liens renvoyés par la requête delta ressembleront à ceci :

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(driveItem)",
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?$select=*%2csharepointIds&token=MzslMjM0OyUyMzE7MzsyM2YwNDVhMS1lNmRmLTQ1N2MtOGQ5NS1hNmViZDVmZWRhNWQ7NjM2NzExNzY2MzIxMDcwMDAwOzE5ODAzMzU5ODslMjM7JTIzOyUyMzQ",
    "value": [
        {
            "@odata.type": "#microsoft.graph.driveItem",
            "createdDateTime": "2017-07-27T02:41:36Z",
…
}

Pour obtenir un exemple plus détaillé, consultez la documentation de requête delta.

La requête delta renvoie un tableau driveItems. Si vous savez à l’avance que vous souhaitez des informations spécifiques, vous pouvez les inclure dans une instruction Select avec la requête delta. Vous pouvez également suivre l’appel delta avec une demande pour un driveItem spécifique si vous en avez besoin. La requête delta permet toujours de réduire le nombre d’éléments sur lequel vous devez effectuer une requête pour les modifications, ce qui rend votre application plus efficace.

Être averti des modifications à l’aide de webhooks

Pour utiliser au mieux la requête delta pour les modifications qui se produisent sur un lecteur, vous avez besoin d’une stratégie efficace pour savoir quand revenir et demander les modifications. Dans le passé, vous avez peut-être écrit votre application pour OneDrive et SharePoint à intervalles fixes et vous avez énuméré les modifications vous-même. Avec la requête delta, la partie d’énumération est effectuée pour vous. Vous devez donc simplement savoir quand revenir. Les webhooks vous permettent d’éviter l’interrogation du service et de recevoir une notification lorsqu’un changement vous intéresse. L’interrogation répétée ou à des taux élevés du service entraîne la limitation de votre application en raison de modèles d’appels excessifs.

Les webhooks sont joints à l’aide de l’API d’abonnements pour Microsoft Graph. Vous trouverez la documentation complète pour les webhooks Microsoft Graph et l’API Abonnements sur le site Microsoft Graph.

Vous devez créer un abonnement associé à une ressource spécifique (dans ce cas, un lecteur). Les lecteurs supportent le type de modification « mise à jour » pour les webhooks. Une « mise à jour » indique que le contenu du lecteur a changé ou qu’un nouveau contenu a été ajouté ou supprimé. Les abonnements aux webhooks ont un délai d’expiration associé qui doit être régulièrement actualisé. Consultez la documentation précédemment mentionnée sur la façon d’actualiser vos abonnements. Nous vous recommandons d’utiliser la requête delta avec votre dernier jeton de modification immédiatement après vous être abonné aux webhooks pour vous assurer que vous ne manquez pas les modifications qui se sont produites entre l’analyse initiale et la configuration de vos webhooks.

Même avec les webhooks envoyant des notifications à votre application, vous souhaiterez peut-être fournir une requête delta périodique pour vous assurer qu’aucune modification n’est manquée s’il semble qu’un longue période s’est écoulée depuis la réception d’une notification. Nous vous recommandons de ne pas effectuer plus d’une fois par jour cette vérification périodique. La requête delta vous permet toujours de facilement rattraper et de ne pas manquer les modifications apportées au système.

Réception de notifications webhook pour les événements de sécurité

OneDrive et SharePoint prennent en charge l’envoi de notifications d’événements de sécurité. Pour vous abonner à ces événements, vous devez ajouter l’en-tête « prefer:includesecuritywebhooks » à votre demande d’inscription de webhook. Une fois le webhook inscrit, vous recevez des notifications lorsque les autorisations changent sur un élément. Cette fonctionnalité est applicable à SharePoint et OneDrive Entreprise, mais pas aux comptes OneDrive des consommateurs.

Modifications de traitement

Une fois que votre application a reçu une notification par le biais d’un webhook, vous devez accepter la notification en envoyant immédiatement un Code accepté 202 à Microsoft Graph. Vous devez envoyer ce code avant de commencer un long traitement. Si vous ne le faites pas, d’autres tentatives sont envoyées, que votre application peut voir comme de fausses notifications.

Suivez l’accusé de réception avec une requête delta pour les dernières modifications et votre application doit être à jour. Si vous attendez des modèles de trafic élevé sur un lecteur particulier, vous devez envisager d’appeler une requête delta à intervalle réduit plutôt qu’après chaque notification de modification. Veillez également à stocker la nouvelle valeur renvoyée dans le paramètre deltaLink pour obtenir un nouveau jeton pour appeler à nouveau l’API.

Si votre traitement nécessite le téléchargement du contenu d’un fichier individuel, vous pouvez utiliser la propriété cTag pour déterminer si le contenu du fichier a changé depuis le dernier téléchargement. Une fois que vous savez que vous souhaitez télécharger le fichier, vous pouvez accéder à la propriété /content de driveItem renvoyée dans une réponse de requête delta.

Analyse des hiérarchies d’autorisations

Par défaut, la réponse de requête Delta inclut les informations de partage pour les éléments, même si elles héritent de leurs autorisations de leur parent et n’ont pas de modifications directes de partage. Notez que la réponse de requête delta inclut uniquement les éléments avec des modifications directes de leur contenu ou métadonnées et la hiérarchie parente des éléments modifiés. En règle générale, vous obtenez un appel de suivi afin d’obtenir les informations d’autorisation pour chaque élément plutôt que celles dont les informations de partage ont été modifiées. Vous pouvez optimiser votre compréhension de la façon dont les modifications sont apportées en ajoutant l’en-tête « Prefer: hierarchicalsharing » à votre requête de requête Delta.

Lorsque l’en-tête « Prefer: hierarchicalsharing » est fourni, des informations de partage sont renvoyées pour la racine de la hiérarchie des autorisations, ainsi que pour les éléments qui ont explicitement des modifications de partage. Dans les cas où la modification de partage a pour effet de supprimer le partage d’un élément, vous trouverez une facette de partage vide pour différencier les éléments qui héritent de leur parent et ceux qui sont uniques, mais qui n’ont pas de liens de partage. Vous verrez également cette facette de partage vide à la racine d’une hiérarchie d’autorisations qui n’est pas partagée pour établir l’étendue initiale.

Dans de nombreux scénarios d’analyse, vous souhaiterez peut-être spécifiquement utiliser les modifications apportées aux autorisations. Pour clairement afficher dans la réponse de requête delta quelles modifications sont le résultat d’autorisations en cours de modification, vous pouvez fournir l’en-tête dePrefer: deltashowsharingchanges ». Lorsque cet en-tête est fourni, l’annotation OData « @microsoft.graph.sharedChanged » : « True » est présente lors de l’appel sur Microsoft Graph pour tous les éléments qui s’affichent dans la réponse de requête delta en raison de modifications d’autorisation. Lorsque vous utilisez l’API SharePoint ou OneDrive directement, l’annotation est « @oneDrive.sharedChanged » : « True ». Tout comme les webhooks de sécurité, cette fonctionnalité est applicable à SharePoint et OneDrive Entreprise, mais pas aux comptes OneDrive consommateurs.

Que se passe-t-il lorsque vous êtes limité ?

Dans certains scénarios, votre application peut obtenir une réponse 429 ou 503 de Microsoft Graph. Cela indique que votre demande est actuellement limitée. L’une des choses à garder à l’esprit est que SharePoint limite les applications en fonction de l’utilisation d’une application avec chaque client. Le fait d’effectuer une requête pour une ressource dans un client vous offre en conséquence moins de ressources pour appeler une autre ressource pour ce même client. En fin de compte, il peut exister plusieurs raisons pour lesquelles votre application reçoit une réponse de limitation et il est essentiel que votre application réponde correctement dans ces situations.

Pour récupérer après avoir reçu un code de réponse 429 ou 503, recommencez après avoir attendu la durée spécifiée dans le champ Retry-After de l’en-tête de réponse. Si la limitation persiste, la valeur de Retry-After peut devenir plus longue au fil du temps, ce qui permet au système de récupérer. Les applications qui ne respectent pas la nouvelle tentative après la durée spécifiée avant de rappeler seront bloquées en raison de modèles d’appels abusifs.

En attendant la récupération 429 ou 503, vous devez vous assurer que vous suspendez toutes les autres requêtes que vous faites au service. Cela est particulièrement important dans les scénarios à plusieurs threads. Effectuer des appels supplémentaires pendant la réception de réponses de limitation prolongera le temps nécessaire à votre application pour devenir non limitée.

Pour plus d’informations sur la façon dont les ressources Microsoft Graph fonctionnent avec la limitation, voir les Conseils de limitation sur Microsoft Graph.