Make API calls using the Microsoft Graph SDKs

The Microsoft Graph SDK service libraries provide a client class that you can use as the starting point for creating all API requests. There are two styles of client class: one uses a fluent interface to create the request (for example, client.Me.Manager) and the other accepts a path string (for example, api("/me/manager")). When you have a request object, you can specify a variety of options such as filtering and sorting, and finally, you select the type of operation you want to perform.

Read information from Microsoft Graph

To read information from Microsoft Graph, you first need to create a request object and then run the GET method on the request.

    // GET https://graph.microsoft.com/v1.0/me

     User user = await graphClient.Me  
                .Request()
                .GetAsync();  

Use $select to control the properties returned

When retrieving an entity, not all properties are automatically retrieved; sometimes they need to be explicitly selected. Also, in some scenarios it isn't necessary to return the default set of properties. Selecting just the required properties can improve the performance of the request. You can customize the request object to emit the $select query parameter with a list of properties.

    // GET https://graph.microsoft.com/v1.0/me?$select=displayName,jobTitle

     User user = await graphClient.Me
                .Request()
                .Select(u => new
                {
                    u.DisplayName,
                    u.JobTitle
                })
                .GetAsync(); 

Retrieve a list of entities

Retrieving a list of entities is similar to retrieving a single entity except there a number of other options for configuring the request. The $filter query parameter can be used to reduce the result set to only those rows that match the provided condition. The $orderBy query parameter will request that the server provide the list of entities sorted by the specified properties.

    // GET https://graph.microsoft.com/v1.0/me/messages?$select=subject,sender&$filter=<some condition>&orderBy=receivedDateTime

    IUserMessagesCollectionPage messages = await graphClient.Me.Messages
                .Request()
                .Select(m => new
                {
                    m.Subject,
                    m.Sender
                })
                .Filter("<filter condition>")
                .OrderBy("receivedDateTime")
                .GetAsync();

The object returned when retrieving a list of entities is likely to be a paged collection. For details about how to get the complete list of entities, see paging through a collection.

Access an item of a collection

For SDKs that support a fluent style, collections of entities can be accessed using an array index. For template-based SDKs, it is sufficient to embed the item identifier in the path segment following the collection.

    // GET https://graph.microsoft.com/v1.0/me/messages/<guid>

     string messageId = "<guid>";
     Message message = await graphClient.Me.Messages[messageId]
                .Request()
                .GetAsync();

You can use the $expand filter to request a related entity, or collection of entities, at the same that you request the main entity. The Expand() function on the request object adds the necessary query parameter.

    // GET https://graph.microsoft.com/v1.0/me/messages/<guid>?$expand=attachments

     string messageId = "<guid>";
     Message message = await graphClient.Me.Messages[messageId]
                .Request()
                .Expand("attachments")
                .GetAsync();

Delete an entity

To delete an entity, construct the request in the same way that you do to retrieve an entity. The delete method on the request object indicates the desire to delete the entity.

    // DELETE https://graph.microsoft.com/v1.0/me/messages/<guid>

     string messageId = "<guid>";
     Message message = await graphClient.Me.Messages[messageId]
                .Request()
                .DeleteAsync();

Make a POST request to create a new entity

To create a new entity in a collection, call an add or post method and pass in an object that contains the information to be used to create the new entity. An updated version of the created entity is usually returned from the call.

    GraphServiceClient graphClient = new GraphServiceClient( authProvider );
    
    var calendar = new Calendar
    {
    	Name = "Volunteer"
    };
    
    newCalendar = await graphClient.Me.Calendars
    	.Request()
    	.AddAsync(calendar);

Updating an existing entity with PATCH

Most updates in Microsoft Graph are performed using a PATCH method and therefore it is only necessary to include the properties that you want to change in the object you pass.

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var team = new Team
{
	FunSettings = new TeamFunSettings
	{
		AllowGiphy = true,
		GiphyContentRating = GiphyRatingType.Strict
	}
};

await graphClient.Teams["{id}"]
	.Request()
	.UpdateAsync(team);

Use HTTP headers to control request behavior

You can use a header() function to attach custom headers to a request. A number of Microsoft Graph scenarios use custom headers to adjust the behavior of the request.

    GraphServiceClient graphClient = new GraphServiceClient( authProvider );
    
    var events = await graphClient.Me.Events
    	.Request()
    	.Header("Prefer","outlook.body-content-type=\"text\"")
    	.Select( e => new {
    			 e.Subject,
    			 e.Body,
    			 e.BodyPreview
    			 })
    	.GetAsync();

Provide custom query parameters

In situations where an API call allows custom query parameters, you can provide those parameter values by using a list of QueryOptions objects.

    var queryOptions = new List<QueryOption>()
    {
        new QueryOption("startdate", "2016-12-01T00:00:00Z"),
        new QueryOption("enddate", "2016-12-30T00:00:00Z")
    };
    
    var calendar = await graphClient.Me.CalendarView()
        .Request( queryOptions )
        .GetAsync();