Delta Queries In Microsoft Graph API Using C#

Overview

 

Microsoft Graph is the gateway to data and intelligence in Microsoft 365. Using Microsoft Graph API it is easy to retrieve the entire set of data of a resource e.g: all the users or all the groups in an organization using simple get API calls. However, in certain business scenarios, you would like to see the new changes only - the Delta. This can be accomplished using the delta queries.

 

Delta query is very similar to a get API call but it is a separate function and it will get you all the current state so all the groups or all the emails in your mailbox Also at the end, it will give you what is called a Delta link and you can persist that link and you decide when you want to call again and you use the link to call again after a few seconds, few minutes, few days and the API is only going to return the new changes - the additions, the removal's, the modifications to the collection. So I call in a set of resources and after I finish paginating on the results I get a Delta link and with that Delta link after some time I can come back and get only the things that have changed since the last time the call was made.

 

In this article, I will walk you through the steps to execute delta queries in Microsoft using C# code. For the demo, code in this article tracks the changes made to user's profile properties in Azure Active Directory.

 

Prerequisites

• App registered in Azure active directory(AAD) with necessary permissions granted to make a call.  

Package Dependency

 

Include below packages in your application to make a call to Graph API. 

dotnet add package Microsoft.Identity.Client
dotnet add package Microsoft.Graph

 Create GetGraphClient method to get the access token,

private GraphServiceClient GetGraphClient()
    {
      var graphClient = new GraphServiceClient(new DelegateAuthenticationProvider((requestMessage) => {
        // get an access token for Graph
        var accessToken = GetAccessToken().Result;

        requestMessage
            .Headers
            .Authorization = new AuthenticationHeaderValue("bearer", accessToken);

        return Task.FromResult(0);
      }));

      return graphClient;
    }

 Add below method to retrieve the users with using delta query,

private async Task<IUserDeltaCollectionPage> GetUsers(GraphServiceClient graphClient, object deltaLink)
{
  IUserDeltaCollectionPage page;

  if (lastPage == null)
  {
    page = await graphClient.Users
                            .Delta()
                            .Request()
                            .GetAsync();
      }
  else
  {
    lastPage.InitializeNextPageRequest(graphClient, deltaLink.ToString());
    page = await lastPage.NextPageRequest.GetAsync();
  }

  lastPage = page;
  return page;
}

Add below method to display the users in the console with user Id, Name and Surname,

private void OutputUsers(IUserDeltaCollectionPage users)
{
  foreach(var user in users)
  {
    var message = $"User: {user.Id}, {user.GivenName} {user.Surname}";
    Console.WriteLine(message);
  }
}

 Add below method to retrieve the changes made to users profile properties and display it on the screen,

private async Task CheckForUpdates()
{
  var graphClient = GetGraphClient();

  // get a page of users
  var users = await GetUsers(graphClient, DeltaLink);

  OutputUsers(users);

  // go through all of the pages so that we can get the delta link on the last page.
  while (users.NextPageRequest != null)
  {
    users = users.NextPageRequest.GetAsync().Result;
    OutputUsers(users);
  }

  object deltaLink;

  if (users.AdditionalData.TryGetValue("@odata.deltaLink", out deltaLink))
  {
    DeltaLink = deltaLink;
  }
}

Call Pattern for Delta Query

• Step 1: Initiate a GET request with the delta function for the expected data from Microsoft 365
• Step 2: Response is received with the relevant data and a state token. The response has either of the two parameters :
• nextLink - There is additional data to be retrieved in the session. you would need to continue making requests using the nextLink to retireve all the pages of data until deltaLink is returned in the response.
• deltaLink - It means that there is no more data, a complete set of data is retrieved. For future requests, use this link for the changes in the resource.
• Step 3: When you need to retrieve the latest changes in the resource, use the deltaLink retrieved in Step 2. Response to this call will have delta changes and either of the parameters nextLink ordeltaLink.

Summary

 

Microsoft Graph API offers a wide range of resource collections through its endpoint. Based on the business scenario, the application might or might not need a complete set of data of a resource collection. In the scenarios of incremental data requests, delta queries are the best option to get only the necessary latest changes.