Partager via

driveItem: delta

  • Article

Espace de noms: microsoft.graph

Importante

Les API sous la version /beta dans Microsoft Graph sont susceptibles d’être modifiées. L’utilisation de ces API dans des applications de production n’est pas prise en charge. Pour déterminer si une API est disponible dans v1.0, utilisez le sélecteur Version .

Suivre les modifications apportées à un driveItem 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, en retournant des pages d’éléments et un @odata.nextLink ou un @odata.deltaLink. 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 : vous devez supprimer un dossier localement uniquement s’il est vide après la synchronisation de toutes les modifications.

Autorisations

Choisissez l’autorisation ou les autorisations marquées comme moins privilégiées pour cette API. Utilisez une autorisation ou des autorisations privilégiées plus élevées uniquement si votre application en a besoin. Pour plus d’informations sur les autorisations déléguées et d’application, consultez Types d’autorisations. Pour en savoir plus sur ces autorisations, consultez les informations de référence sur les autorisations.

Type d’autorisation Autorisations avec privilèges minimum Autorisations privilégiées plus élevées
Déléguée (compte professionnel ou scolaire) Files.Read Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Déléguée (compte Microsoft personnel) Files.Read Files.Read.All, Files.ReadWrite, 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 de fonction

Paramètre Type 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 retourne un nouvel état depuis ce jeton.

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.

En-têtes de demande

Nom Description
Autorisation Porteur {token}. Obligatoire. En savoir plus sur l’authentification et l’autorisation.
deltaExcludeParent Chaîne. Si cet en-tête de demande est inclus, la réponse inclut les éléments qui ont été modifiés, et non les éléments parents dans la hiérarchie.

Corps de la demande

N’indiquez pas le corps de la demande pour cette méthode.

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.

En plus de la collection de DriveItems, la réponse inclut également l’une des propriétés suivantes :

Nom Valeur Description
@odata.nextLink url URL permettant de récupérer la page de modifications disponible suivante, s’il y a d’autres modifications dans l’ensemble actuel.
@odata.deltaLink url URL retournée au lieu de @odata.nextLink après le retour de toutes les modifications actuelles. Permet de lire la prochaine série de modifications apportées à l’avenir.

Exemples

Exemple 1 : Demande initiale

Voici un exemple d’appel de cette API pour établir votre état local.

Demande

Voici un exemple de la demande initiale.

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

Réponse

L’exemple suivant illustre la 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 soient récupérées.

Exemple 2 : dernière page d’un jeu

L’exemple suivant montre comment appeler cette API pour mettre à jour votre état local.

Demande

L’exemple suivant montre une requête après la demande initiale.

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

Réponse

L’exemple suivant illustre la 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 des éléments inclut la propriété @odata.deltaLink , qui fournit l’URL qui peut être utilisée ultérieurement pour récupérer les modifications depuis l’ensemble actuel d’éléments.

Il peut arriver que le service ne puisse pas fournir la liste des modifications apportées à un jeton donné (par exemple, si un client tente de réutiliser un ancien jeton après avoir été déconnecté pendant une longue période, ou si l’état du serveur a changé et qu’un nouveau jeton est requis). Dans ce cas, le service retourne une HTTP 410 Gone erreur avec une réponse d’erreur contenant un code d’erreur et un Location en-tête contenant un nouveau nextLink qui démarre une nouvelle énumération delta à partir de zéro. Une fois l’énumération complètement terminée, comparez les éléments renvoyés à votre état local et suivez les instructions suivantes.

Type d’erreur Instructions
resyncChangesApplyDifferences Remplacez tous 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 synification. Téléchargez les modifications locales que le serveur ignore.
resyncChangesUploadDifferences Chargez tous les éléments locaux que le service n’a pas retournés et chargez tous les fichiers qui diffèrent de la version du serveur (en conservant les deux copies si vous ne savez pas lequel est le plus à jour).

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.

Cela peut être utile si votre application souhaite uniquement connaître les modifications et n’a pas besoin de connaître 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

L’exemple suivant illustre une demande.

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

Réponse

L’exemple suivant illustre la 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"
}

Exemple 4 : récupération des résultats delta à l’aide d’un horodatage

Dans certains scénarios, le client peut connaître l’état d’un lecteur jusqu’à une heure spécifique, mais n’a pas de deltaLink pour ce point dans le temps. Dans ce cas, le client peut appeler delta à l’aide d’un horodatage codé par URL pour la valeur du paramètre de token chaîne de requête, par exemple, ?token=2021-09-29T20%3A00%3A00Z ou « ?token=2021-09-29T12%3A00%3A00%2B8%3A00 ».

L’utilisation d’un horodatage à la place d’un jeton est prise en charge uniquement sur OneDrive Entreprise et SharePoint.

Remarque : clients doivent utiliser le deltaLink fourni par delta requêtes lorsque cela est possible, plutôt que de générer leur propre jeton. Cette fonctionnalité ne doit être utilisée que lorsque deltaLink n’est pas connu.

Demande

L’exemple suivant illustre une demande.

GET /me/drive/root/delta?token=2021-09-29T20%3A00%3A00Z

Réponse

L’exemple suivant illustre la 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')"
}

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 parentReference propriété sur les éléments n’inclut pas de valeur pour path. Cela se produit parce que le changement de nom d’un dossier n’entraîne aucun retour de descendants du dossier à partir de delta. Lorsque vous utilisez delta, vous devez toujours suivre les éléments par ID.

  • La requête Delta ne retourne pas de propriétés DriveItem, en fonction de l’opération et du type de service, comme indiqué dans les tableaux suivants.

    OneDrive Entreprise

    Type d’opération Propriétés omises par la requête delta
    Créer/Modifier ctag
    Supprimer ctag, name

    OneDrive (consommateur)

    Type d’opération Propriétés omises par la requête delta
    Créer/Modifier s/o
    Supprimer ctag, size

Analyse des hiérarchies d’autorisations

Par défaut, la réponse à la requête delta inclut le partage d’informations pour tous les éléments de la requête qui ont changé, même s’ils héritent de leurs autorisations de leur parent et n’ont pas eux-mêmes de modifications de partage direct. Cela entraîne généralement un appel de suivi pour obtenir les détails d’autorisation pour chaque élément plutôt que pour ceux dont les informations de partage ont changé. Vous pouvez optimiser votre compréhension de la façon dont les modifications apportées aux autorisations se produisent en ajoutant l’en-tête Prefer: hierarchicalsharing à votre requête de requête Delta.

Lorsque l’en-tête Prefer: hierarchicalsharing est fourni, les informations de partage sont retournées pour la racine de la hiérarchie des autorisations et les éléments qui ont explicitement des modifications de partage. Dans les cas où le changement de partage consiste à supprimer le partage d’un élément, vous trouvez une facette de partage vide pour faire la distinction entre les éléments qui héritent de leur parent et ceux qui sont uniques mais n’ont aucun lien de partage. Vous pouvez également voir 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 faire en sorte que les modifications apportées aux autorisations soient clairement définies dans la réponse de requête Delta, vous pouvez fournir l’en-tête de Prefer: deltashowsharingchanges. Lorsque cet en-tête est fourni, tous les éléments qui apparaissent dans la réponse à la requête delta en raison de modifications d’autorisation ont l’annotation @microsoft.graph.sharedChanged":"True" OData. Cette fonctionnalité est applicable à SharePoint et OneDrive entreprise, mais pas aux comptes OneDrive consommateurs.

Remarque

  • L’utilisation de l’en-tête Prefer: deltashowsharingchanges vous oblige à utiliser Prefer: deltashowremovedasdeleted et Prefer: deltatraversepermissiongaps. Ces valeurs d’en-tête peuvent être jointes dans un seul en-tête : Prefer: deltashowremovedasdeleted, deltatraversepermissiongaps, deltashowsharingchanges.

  • Pour traiter correctement les autorisations, votre application doit demander les autorisations Sites.FullControl.All .

Pour plus d’informations sur les scénarios d’analyse, consultez Meilleures pratiques pour découvrir des fichiers et détecter les modifications à grande échelle.

Réponses d’erreur

En plus des erreurs de resynchronisation détaillées, consultez Réponses aux erreurs pour plus d’informations sur la façon dont les erreurs sont retournées.

Contenu connexe

Utiliser la requête delta pour suivre les modifications apportées aux données Microsoft Graph. Bonnes pratiques pour la découverte des fichiers et la détection des modifications à grande échelle.