driveItem: delta
Espace de noms: microsoft.graph
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, 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
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, renvoie le nouvel état depuis ce jeton. |
Paramètres facultatifs de la requête
Cette méthode prend en charge les $select
paramètres de requête OData , $expand
et $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.
Outre la collection de DriveItems, la réponse comprend é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 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. |
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/v1.0/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 aient été récupérées.
Exemple 2 : dernière page d’un jeu
Voici un exemple montrant comment appeler cette API pour mettre à jour votre état local.
Demande
Voici un exemple de demande après la demande initiale.
GET https://graph.microsoft.com/v1.0/me/drive/root/delta(token='MzslMjM0OyUyMzE7MzsyM2YwNDVhMS1lNmRmLTQ1N2MtOGQ5NS1hNmViZDVmZWRhNWQ7NjM3OTQzNzQwODQ3NTcwMDAwOzU4NTk2OTY0NDslMjM7JTIzOyUyMzA')
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='MzslMjM0OyUyMzE7MzsyM2YwNDVhMS1lNmRmLTQ1N2MtOGQ5NS1hNmViZDVmZWRhNWQ7NjM3OTQzNzQwODQ3NTcwMDAwOzU4NTk2OTY0NDslMjM7JTIzOyUyMzA')"
}
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 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 ce cas, le service retourne une HTTP 410 Gone
erreur avec une réponse d’erreur contenant l’un des codes d’erreur ci-dessous, 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). |
Exemple 3 : récupération du deltaLink actuel
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’utilisationdelta
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"
}
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
GET /me/drive/root/delta?token=2021-09-29T20%3A00%3A00Z
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 pas le 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 certaines 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 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 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 à utiliserPrefer: deltashowremovedasdeleted
etPrefer: 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 ci-dessus, reportez-vous à Réponses d’erreur pour obtenir plus d’informations sur la manière dont les erreurs sont renvoyées.
Contenu connexe
Utiliser la requête delta pour suivre les modifications dans les données Microsoft GraphMeilleures pratiques pour la découverte de fichiers et la détection des modifications à grande échelle