Suivre les modifications sur un lecteurTrack changes for a Drive

Cette méthode permet à votre application de suivre les modifications apportées à un lecteur et à ses enfants au fil du temps.This method allows your app to track changes to a drive and its children over time.

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.Your app begins by calling delta without any parameters. The service starts enumerating the drive's hierarchy, returning pages of items and either an @odata.nextLink or an @odata.deltaLink, as described below. Your app should continue calling with the @odata.nextLink until you no longer see an @odata.nextLink returned, or you see a response with an empty set of changes.

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.After you have finished receiving all the changes, you may apply them to your local state. To check for changes in the future, call delta again with the @odata.deltaLink from the previous response.

Les éléments supprimés sont renvoyés avec lafacette deleted. Les éléments qui possèdent ce jeu de propriétés doivent être supprimés de votre état local.Deleted items are returned with the deleted facet. Items with this property set should be removed from your local state.

Remarque : supprimez uniquement un dossier local s’il est vide une fois toutes les modifications synchronisées.Note: you should only delete a folder locally if it is empty after syncing all the changes.

AutorisationsPermissions

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.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Type d’autorisationPermission type Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)Permissions (from least to most privileged)
Déléguée (compte professionnel ou scolaire)Delegated (work or school account) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.AllFiles.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Déléguée (compte Microsoft personnel)Delegated (personal Microsoft account) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.AllFiles.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All
ApplicationApplication Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.AllFiles.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All

Requête HTTPHTTP request

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 fonctionFunction parameters

ParamètreParameter TypeType DescriptionDescription
jetontoken stringstring Facultatif.Optional. Si cela n’est pas spécifié, elle énumère l’état actuel de la hiérarchie.If unspecified, enumerates the hierarchy's current state. Si latest, renvoie une réponse vide avec le jeton delta le plus récent.If latest, returns empty response with latest delta token. Si un jeton delta précédent, renvoie le nouvel état depuis ce jeton.If a previous delta token, returns new state since that token.

Paramètres facultatifs de la requêteOptional query parameters

Cette méthode prend en charge les paramètres de requête OData $select, $expand et $top pour vous aider à personnaliser la réponse.This method supports the $select, $expand, and $top OData query parameters to customize the response.

RéponseResponse

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.If successful, this method returns a 200 OK response code and a collection of DriveItem resources in the response body.

Outre la collection de DriveItems, la réponse comprend également l’une des propriétés suivantes :In addition to the collection of DriveItems, the response will also include one of the following properties:

NomName ValeurValue DescriptionDescription
@odata.nextLink**@odata.nextLink** urlurl 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.A URL to retrieve the next available page of changes, if there are additional changes in the current set.
@odata.deltaLink**@odata.deltaLink** urlurl 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.A URL returned instead of **@odata.nextLink** after all current changes have been returned. Used to read the next set of changes in the future.

Exemple (requête initiale)Example (Initial Request)

Voici comment appeler cette API pour établir votre état local.Here is an example of how to call this API to establish your local state.

DemandeRequest

Voici un exemple de la requête initiale.Here is an example of the initial request.

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

RéponseResponse

Voici un exemple de réponse.Here is an example of the response.

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

Exemple de code SDKSDK sample code


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Me.Drive.Root.Delta()
    .Request()
    .GetAsync();

Pour plus d’informations sur la façon d' Ajouter le kit de développement logiciel (SDK) à votre projet et de créer une instance authProvider , consultez la documentation SDK .Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Cette réponse comprend la première page de modifications. La propriété **@odata.nextLink** indique qu’il y a davantage d’éléments disponibles dans l’ensemble des éléments en cours. Votre application doit continuer à demander la valeur de l’URL de **@odata.nextLink** jusqu’à ce vous ayez récupéré toutes les pages d’éléments.This response includes the first page of changes, and the **@odata.nextLink** property indicates that there are more items available in the current set of items. Your app should continue to request the URL value of **@odata.nextLink** until all pages of items have been retrieved.

Exemple (dernière page d’une série)Example (Last page in a set)

Voici comment appeler cette API pour mettre à jour votre état local.Here is an example of how to call this API to update your local state.

DemandeRequest

Voici un exemple de requête après la requête initiale.Here is an example request after the initial request.

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

RéponseResponse

Voici un exemple de réponse.Here is an example of the response.

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')"
}

Exemple de code SDKSDK sample code


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Me.Drive.Root.Delta('1230919asd190410jlka')
    .Request()
    .GetAsync();

Pour plus d’informations sur la façon d' Ajouter le kit de développement logiciel (SDK) à votre projet et de créer une instance authProvider , consultez la documentation SDK .Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

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.This response indicates that the item named folder2 was deleted and the item file.txt was either added or modified between the initial request and this request to update the local state.

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.The final page of items will include the **@odata.deltaLink** property, which provides the URL that can be used later to retrieve changes since the current set of items.

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.There may be cases when the service can't provide a list of changes for a given token (for example, if a client tries to reuse an old token after being disconnected for a long time, or if server state has changed and a new token is required). In these cases the service will return an HTTP 410 Gone error with an error response containing one of the error codes below, and a Location header containing a new nextLink that starts a fresh delta enumeration from scratch. After finishing the full enumeration, compare the returned items with your local state and follow these instructions.

Type d’erreurError Type InstructionsInstructions
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.Replace any local items with the server's version (including deletes) if you're sure that the service was up to date with your local changes when you last sync'd. Upload any local changes that the server doesn't know about.
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).Upload any local items that the service did not return, and upload any files that differ from the server's version (keeping both copies if you're not sure which one is more up-to-date).

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.In some scenarios, it may be useful to request the current deltaLink value without first enumerating all of the items in the drive already.

Ceci peut s’avérer utile si votre application doit uniquement être informée des modifications en ignorant les éléments existants.This can be useful if your app only wants to know about changes, and doesn't need to know about existing items. Pour récupérer la dernière ressource deltaLink, appelez delta avec un paramètre de chaîne de requête ?token=latest.To retrieve the latest deltaLink, call delta with a query string parameter ?token=latest.

Remarque : Si vous tentez de tenir à jour une représentation locale complète des éléments d’un dossier ou d’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. delta constitue l’unique moyen de garantir que vous avez lu tous les données nécessaires.Note: If you are trying to maintain a full local representation of the items in a folder or a drive, you must use delta for the initial enumeration. Other approaches, such as paging through the children collection of a folder, are not guaranteed to return every single item if any writes take place during the enumeration. Using delta is the only way to guarantee that you've read all of the data you need to.

DemandeRequest

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

RéponseResponse

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 de code SDKSDK sample code


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var queryOptions = new List<QueryOption>()
{
    new QueryOption("token", "latest")
};

var delta = await graphClient.Me.Drive.Root.Delta()
    .Request( queryOptions )
    .GetAsync();

Pour plus d’informations sur la façon d' Ajouter le kit de développement logiciel (SDK) à votre projet et de créer une instance authProvider , consultez la documentation SDK .Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

RemarquesRemarks

  • 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.The delta feed shows the latest state for each item, not each change. If an item were renamed twice, it would only show up once, with its latest name.

  • 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.The same item may appear more than once in a delta feed, for various reasons. You should use the last occurrence you see.

  • 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.The parentReference property on items will not include a value for path. This occurs because renaming a folder does not result in any descendants of the folder being returned from delta. When using delta you should always track items by id.

  • Dans OneDrive Entreprise et SharePoint, delta est uniquement pris en charge dans le dossier root, et non dans les autres dossiers d’un lecteur.In OneDrive for Business and SharePoint, delta is only supported on the root folder, not on other folders within a drive.

  • La requête delta ne renverra pas certaines propriétés DriveItem, en fonction du type d’opération et de service, comme indiqué dans les tableaux suivants.Delta query will not return some DriveItem properties, depending on the operation and service type, as shown in the following tables.

    OneDrive EntrepriseOneDrive for Business

    Type d’opérationOperation type Propriétés omises par la requête deltaProperties omitted by delta query
    Créer/ModifierCreate/Modify ctag, lastModifiedByctag, lastModifiedBy
    SupprimerDelete ctag, lastModifiedBy, name

    OneDrive (consommateur)OneDrive (consumer)

    Type d’opérationOperation type Propriétés omises par la requête deltaProperties omitted by delta query
    Créer/ModifierCreate/Modify s/on/a
    SupprimerDelete ctag, size

Réponses d’erreurError responses

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.In addition to the resync errors detailed above, see Error Responses for details about how errors are returned.