Partager via

Suivre les modifications sur un lecteur

  • Article

Cette méthode permet à votre application de suivre les modifications apportées à un lecteur et à ses enfants au fil du temps.

Votre application commence par appeler le service delta sans aucun paramètre. Le service commence à énumérer la hiérarchie du lecteur, renvoyant les pages des éléments et un @odata.nextLink, ou un @odata.deltaLink, comme décrit ci-dessous. Votre application doit continuer à appeler avec @odata.nextLink jusqu’à ce que plus aucun @odata.nextLink ne soit renvoyé, ou jusqu’à ce que vous receviez une réponse avec un ensemble de modifications vide.

Une fois que vous avez reçu toutes les modifications, vous pouvez les appliquer à votre état local. Pour vérifier les modifications apportées à l’avenir, appelez une nouvelle fois delta à l’aide de @odata.deltaLink reçu dans la réponse précédente.

Les éléments supprimés sont renvoyés avec la facette deleted. Les éléments qui possèdent ce jeu de propriétés doivent être supprimés de votre état local.

Remarque : supprimez uniquement un dossier local s’il est vide une fois toutes les modifications synchronisées.

Autorisations

L’une des autorisations suivantes est nécessaire pour appeler cette API. Pour plus d’informations, notamment sur la façon de choisir les autorisations, voir Autorisations.

Type d’autorisation Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)
Déléguée (compte professionnel ou scolaire) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Déléguée (compte Microsoft personnel) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All
Application Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All

Requête HTTP

GET /drives/{drive-id}/root/delta
GET /groups/{groupId}/drive/root/delta
GET /me/drive/root/delta
GET /sites/{siteId}/drive/root/delta
GET /users/{userId}/drive/root/delta

Paramètres facultatifs de la requête

Cette méthode prend en charge les $selectparamètres de requête OData , $expandet $top pour personnaliser la réponse.

Paramètres

Nom Valeur Description
jeton string Facultatif. Si cela n’est pas spécifié, elle énumère l’état actuel de la hiérarchie. Si latest, renvoie une réponse vide avec le jeton delta le plus récent. Si un jeton delta précédent, renvoie le nouvel état depuis ce jeton.

Réponse

En cas de réussite, cette méthode renvoie un code de réponse 200 OK et une collection de ressources DriveItem dans le corps de la réponse.

Outre la collection de DriveItems, la réponse comprend également l’une des propriétés suivantes :

Nom Valeur Description
@odata.nextLink url URL destinée à récupérer la page de modifications disponible suivante, si d’autres modifications ont été apportées dans la série en cours.
@odata.deltaLink url URL renvoyée à la place de @odata.nextLink une fois que toutes les modifications en cours ont été renvoyées. Permet de lire la prochaine série de modifications apportées à l’avenir.

Exemple (requête initiale)

Voici comment appeler cette API pour établir votre état local.

Demande

Voici un exemple de la requête initiale.

GET https://graph.microsoft.com/v1.0/me/drive/root/delta

Réponse

Voici un exemple de réponse.

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
        {
            "id": "0123456789abc",
            "name": "folder2",
            "folder": { }
        },
        {
            "id": "123010204abac",
            "name": "file.txt",
            "file": { }
        },
        {
            "id": "2353010204ddgg",
            "name": "file5.txt",
            "deleted": { }
        }
    ],
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/drive/delta(token=1230919asd190410jlka)"
}

Cette réponse inclut la première page de modifications, et la propriété @odata.nextLink indique qu’il y a plus d’éléments disponibles dans l’ensemble d’éléments actuel. Votre application doit continuer à demander la valeur d’URL de @odata.nextLink jusqu’à ce que toutes les pages d’éléments aient été récupérées.

Exemple (dernière page d’une série)

Voici comment appeler cette API pour mettre à jour votre état local.

Demande

Voici un exemple de requête après la requête initiale.

GET https://graph.microsoft.com/v1.0/me/drive/root/delta(token='1230919asd190410jlka')

Réponse

Voici un exemple de réponse.

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
        {
            "id": "0123456789abc",
            "name": "folder2",
            "folder": { },
            "deleted": { }
        },
        {
            "id": "123010204abac",
            "name": "file.txt",
            "file": { }
        }
    ],
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?(token='1230919asd190410jlka')"
}

Cette réponse indique que l’élément nommé folder2 a été supprimé et que l’élément file.txt a été ajouté ou modifié entre la requête initiale et cette requête afin de mettre à jour l’état local.

La dernière page d’éléments comprendra la propriété @odata.deltaLink qui fournit l’URL pouvant servir ultérieurement à récupérer les modifications à partir du jeu d’éléments en cours.

Il se peut que le service ne puisse pas fournir une liste des modifications pour un jeton donné (par exemple, si un client tente de réutiliser un ancien jeton après avoir été déconnecté pendant un certain temps, ou si l’état du serveur a été modifié et qu’un nouveau jeton est requis). Dans ces scénarios, le service renverra une erreur HTTP 410 Gone avec une réponse d’erreur contenant l’un des codes d’erreur ci-dessous, et un en-tête Location contenant un nouveau nextLink qui recommence une énumération delta. Une fois l’énumération complètement terminée, comparez les éléments renvoyés avec votre état local et suivez les instructions suivantes.

Type d’erreur Instructions
resyncChangesApplyDifferences Remplacez les éléments locaux par la version du serveur (y compris les suppressions) si vous êtes sûr que le service était à jour avec vos modifications locales lors de la dernière synchronisation. Téléchargez les modifications locales que le serveur ignore.
resyncChangesUploadDifferences Téléchargez les éléments locaux que le service n’a pas renvoyés, et téléchargez les fichiers qui diffèrent de la version du serveur (tout en conservant les deux copies si vous ne savez pas quelle est la plus récente).

Dans certains cas, il peut être utile de demander la valeur actuelle de la ressource deltaLink avant de commencer à énumérer tous les éléments présents dans le lecteur.

Ceci peut s’avérer utile si votre application doit uniquement être informée des modifications en ignorant les éléments existants. Pour récupérer la dernière ressource deltaLink, appelez delta avec un paramètre de chaîne de requête ?token=latest.

Remarque : Si vous essayez de conserver une représentation locale complète des éléments dans un dossier ou un lecteur, vous devez utiliser delta pour l’énumération initiale. Il n’est pas garanti que d’autres méthodes, telles que la pagination via la collection d’children d’un dossier, renvoient tous les élément si une opération d’écriture a lieu au cours de l’énumération. L’utilisation delta est la seule façon de garantir que vous avez lu toutes les données dont vous avez besoin.

Demande

GET /me/drive/root/delta?token=latest

Réponse

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [ ],
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?token=1230919asd190410jlka"
}

Remarques

  • Le flux delta affiche le dernier état de chaque élément, et non chaque modification. Si un élément a été renommé deux fois, il apparaîtrait une seule fois uniquement, avec son nom le plus récent.

  • Le même élément peut s’afficher plusieurs fois dans un flux delta pour diverses raisons. Vous devez utiliser la dernière occurrence consultée.

  • La propriété parentReference des éléments n’indiquera pas de valeur pour path. En effet, le fait de renommer un dossier ne renvoie pas les descendants du dossier renvoyés depuis delta. Lorsque vous utilisez delta, vous devez toujours suivre les éléments par ID.

  • Pour les dossiers partagés ajoutés à un lecteur, delta ne retourne aucune information sur les modifications apportées au dossier partagé. Au lieu de cela, vous devez utiliser un autre appel delta qui cible le dossier partagé lui-même.

  • Delta présente des restrictions supplémentaires pour OneDrive Entreprise. Pour plus d’informations, consultez les notes de publication.

Réponses d’erreur

En plus des erreurs de resynchronisation détaillées ci-dessus, reportez-vous à Réponses d’erreur pour obtenir plus d’informations sur la manière dont les erreurs sont renvoyées.