Documentation clarification for using DriveItem delta endpoint to download SharePoint Document library files

Question

Documentation clarification for using DriveItem delta endpoint to download SharePoint Document library files

Ralph 10

Attempting to download all files from a SharePoint Document library and then perform daily delta downloads for synchronization. This is being implemented in C# using the Microsoft Graph SDK.

The approach involves using the Delta endpoints of the Microsoft Graph, specifically the DriveItem delta endpoint.

Questions

Seeking clarification on the results from the API calls and the documentation.

There are multiple identical results returned. The remarks documentation section mentions that The same item may appear more than once in a delta feed, for various reasons. You should use the last occurrence you see. Does this imply that a C# linq Last operation should be performed based on the Id field? If there are four identical items (IDs), should only the last instance be processed?
When setting the page size (top) to 2, sometimes 4 results are returned. What might be causing this? Is it related to the folder structure within the document library?
The root drive item appears in every page response. Is this behavior related to Replays?
The goal is to download only files and not the folder structure. Is it appropriate to filter items with Where(x => x.File != null)?
If a folder is deleted, will a delete object be returned for all the files within that folder?

What I did

I wrote a [sample project]([https://github.com/LockTar/azure-storage-blob-manager-sample](https://github.com/%5BLockTar/azure-storage-blob-manager-sample%5D(https://github.com/LockTar/azure-storage-blob-manager-sample)) with a SharePoint document library downloader.
The SP downloader SharePoinDriveItemDeltaDownloader is requesting a site id and list id.

The logic of the downloader is doing this:

It asks the user for the SharePoint List ID (or uses an environment variable) and an optional delta marker for incremental sync.
Reads credentials from environment variables: It retrieves the necessary Azure AD and SharePoint credentials.
Initializes the Microsoft Graph client: Authenticates and prepares to interact with the SharePoint API.
Finds the correct drive and root folder: Looks up the drive and root folder for the specified SharePoint list.
Fetches items using the delta API: Retrieves the first page of items (or resumes from a delta marker), then continues paging through results if more are available.
Processes each item: For each file or folder, it logs details and (optionally) downloads files that have changed.
Tracks and summarizes results: Counts downloaded and skipped files, and prints a summary including the new delta link for future incremental syncs.

Getting a sample for driveitem delta endpoint just like the sample for users would be nice!

Sampath 3,750 Reputation points Microsoft External Staff Moderator

2025-06-10T20:05:11.87+00:00
Hello @Ralph ,

You can implement a sync system that:

Downloads all files from a SharePoint Document Library initially.

Uses the delta API endpoint for daily delta (incremental) sync.

Implemented in C# using Microsoft Graph SDK.

Identical Results Returned

The delta API can return duplicate entries for the same file/folder.

This behavior is by design:

“The same item may appear more than once in a delta feed, for various reasons. You should use the last occurrence you see.”

In your implementation, this means:

var distinctItems = items.GroupBy(x => x.Id) .Select(g => g.Last()) .ToList();

Group by Id (unique file/folder ID).

Use the last occurrence (Last()) to ensure you have the latest change.

Setting top=2 but receiving 4 results can happen because:

Folder hierarchy expansion: if an item is a folder, the delta query may expand its children.

Additional system metadata or deleted entries.

Microsoft Graph’s delta endpoint does not always strictly respect top in a naive way—it might expand/merge results to ensure logical page completeness.

Root Drive Item Appears in Every Page

Yes, this is expected driveItem/delta always includes the root folder as a starting point in every page (replay).

Ignore duplicate root entries during processing; they’re included to maintain delta consistency.

Filter Only Files

Your code correctly filters using:

items.Where(x => x.File != null)

This ensures you process only files (skip folders).

Deleted Folders and Their Contents
If a folder is deleted, only that folder will have a Deleted object.

Files inside the deleted folder are not explicitly listed as deleted in the delta feed—Microsoft Graph’s delta sync assumes a hierarchical model (the deletion of a parent implies the child is gone).

However, in some delta scenarios (like explicit file deletions), deleted files might appear separately with the Deleted object.

nextLink: returned when there’s more data to page through.

deltaLink: returned when you’ve reached the end of the current delta session.

Never process both simultaneously—if both are present, ensure your loop logic favors nextLink until you reach only deltaLink.

Sometimes, an item can appear in multiple pages if:

It was modified multiple times during the delta session.

Metadata or sharing links were updated mid-session.

Always use the last occurrence across all pages:

// After all pages processed var finalDistinctItems = allItemsAcrossPages .GroupBy(x => x.Id) .Select(g => g.Last()) .ToList();

Example: Delta Sync Handling in C#

Here’s a refined snippet addressing these considerations:

private static DeltaSyncResult HandleItems(List<DriveItem> items) { var result = new DeltaSyncResult(); // Group by Id and use last occurrence to handle duplicates var distinctItems = items .GroupBy(item => item.Id) .Select(g => g.Last()) .ToList(); foreach (var item in distinctItems) { if (item.Deleted != null) { ConsoleUtils.PrintInfo($"Item deleted: {item.Name} (ID: {item.Id})"); continue; } if (item.File != null) { result.Total++; ConsoleUtils.PrintInfo($"Downloading file: {item.Name}"); // Implement download logic here... result.Downloaded++; } } return result; }

Reference:

driveItem/delta - Microsoft Docs (C#)

driveItem/delta - Microsoft Docs (HTTP)

Delta Query Concept
Ralph 10 Reputation points

2025-06-11T13:52:17.4866667+00:00

Thank you for the reply on all the questions.

So when deleting a folder, files are not marked as deleted. This means that I can not filter on only files otherwise I miss the deleted files under that folder. Do I understand you correctly?

You said that I have to do a Last over all the pages. Is this really necessary? I think that the changes are in order? Reason why I ask this is that we chuck the changes with the top functionality. In the page (result of the top) I can do a last. We then put that last item on a queue. The next page can then again have that same item (or multiple times). I can do a last here again and put that last item also on the queue. I guess it should not really matter that we process those changes twice right?
Sampath 3,750 Reputation points Microsoft External Staff Moderator

2025-06-11T17:44:46.0033333+00:00

Hello @Ralph ,

Yes, your understanding is correct .When a folder is deleted, the delta feed only marks the folder itself as deleted, but not the individual files inside it. This means that if you filter only for files (Where(x => x.File != null)), you might miss detecting deletions of files that were inside the deleted folder.

Regarding processing the last occurrence across all pages:

If your changes are strictly ordered, then performing Last() within each page should work fine.

However, items can appear multiple times across different pages due to metadata updates or modifications during the delta session.

If you process the same item multiple times, it shouldn't cause issues, but ensuring the latest occurrence across all pages helps maintain accuracy.

Your approach of queuing the last item per page is reasonable, and if your system can handle duplicate processing efficiently, it should work without major problems. However, if you want to ensure the latest version, grouping by Id and selecting the last occurrence across all pages might be a safer approach.

For more details, you can check the official Microsoft documentation on DriveItem delta endpoint.

Your answer

Ralph 10 Reputation points

2025-06-11T13:52:17.4866667+00:00

Thank you for the reply on all the questions.

So when deleting a folder, files are not marked as deleted. This means that I can not filter on only files otherwise I miss the deleted files under that folder. Do I understand you correctly?

You said that I have to do a Last over all the pages. Is this really necessary? I think that the changes are in order? Reason why I ask this is that we chuck the changes with the top functionality. In the page (result of the top) I can do a last. We then put that last item on a queue. The next page can then again have that same item (or multiple times). I can do a last here again and put that last item also on the queue. I guess it should not really matter that we process those changes twice right?
Sampath 3,750 Reputation points Microsoft External Staff Moderator

2025-06-11T17:44:46.0033333+00:00

Hello @Ralph ,

Yes, your understanding is correct .When a folder is deleted, the delta feed only marks the folder itself as deleted, but not the individual files inside it. This means that if you filter only for files (Where(x => x.File != null)), you might miss detecting deletions of files that were inside the deleted folder.

Regarding processing the last occurrence across all pages:

If your changes are strictly ordered, then performing Last() within each page should work fine.

However, items can appear multiple times across different pages due to metadata updates or modifications during the delta session.

If you process the same item multiple times, it shouldn't cause issues, but ensuring the latest occurrence across all pages helps maintain accuracy.

Your approach of queuing the last item per page is reasonable, and if your system can handle duplicate processing efficiently, it should work without major problems. However, if you want to ensure the latest version, grouping by Id and selecting the last occurrence across all pages might be a safer approach.

For more details, you can check the official Microsoft documentation on DriveItem delta endpoint.

Share via

Documentation clarification for using DriveItem delta endpoint to download SharePoint Document library files

Your answer