Using optional query parameters with Microsoft Graph API – Part 2

In this article, I will continue showing how to execute the calls to Microsoft Graph API using some optional OData query parameters.

The part-1 of this article series can be found here. I suggest you read it first, as this article continues from where I stopped in part -1.

Let’s now see the remaining query parameters one by one.

(5) $select


When you fire an API call to MS Graph, it will return the JSON result with all the properties. You may not need all the properties of a result set always. When you want MS Graph API to return only certain properties, then use $select parameter to specify which properties you want in result set.

Please note that the no. of records in the result will not be affected with or without $select parameter, only what’s returned for each record in result will change.


Open MS Graph Explorer here and fire following call to get list of files from OneDrive:

See the data returned in JSON response:


Out of all these properties, what may be most important for you if you wanted to show the user his/her files from OneDrive? Of course, the name of the file/folder.

Fire following call in MS Graph Explorer to get only file name in result:

You will see the following result:

OneDrive name only.PNG

Now MS Graph API returns only file/folder name, instead of all the details. (Of course, “etag” is included but ignore it)

You can also use more than one property separated by comma, e.g.

And you will get following result:

OneDrive name size.PNG

If you type in the property that does not exist in the result set, then it will be ignored.

e.g. fire the following call and see what happens:


In your programming, you can use $select query parameter to:

  • Get only specific property in result set (to make efficient use of bandwidth)
  • Specify those properties not returned in default result set


(6) $search


Using $search query parameter, you can specify free text search criteria for items being returned in result set. Please note that this parameter is currently supported for only “messages” and “person” entities. Microsoft Graph team will cover more entities later.

Some programmers are confused between $search and $filter parameters, because both do similar operations. I will explain the difference briefly in the next section for $filter.

When you specify $search parameter, it tells MS Graph API to include only those entities in result which match the specified expression. Here what to match is left for the implementer, OData specification does not mandate anything. Hence when you specify search criteria with $search query parameter, the result will be dependent on what MS Graph API team has decided to implement. Mostly it works as free text search.


Let’s say you want to find out emails which has “brainstorming” mentioned somewhere.

Open MS Graph Explorer here and fire following call:

See the data returned in JSON response:


Graph API will match the word brainstorming in an email’s from, subject and body fields, and will show the matching messages in the result.

Let’s see another example of using $search with “people” entity.

Open MS Graph Explorer here and fire following call:

See the data returned in JSON response:

people search

MS Graph API will search for the people related to the sample account user, will search for “langer” in display name or email, and will return matching records in result.

There are many more possible calls using the $search parameter, but I will restrict to there two calls only for brevity. I encourage you to explore more by yourself.


In your programming, you can use $search parameter to:

  • perform free text search on messages or people related to user
  • perform fuzzy searches on people


(7) $filter


With $filter parameter, you can specify the filter criteria on a result set using logical operators or string functions. There are fixed logical and string operations which can be performed on a result set using $filter function.

The following extract is taken from the OData specification website here:

The $filter system query option allows clients to filter a collection of resources that are addressed by a request URL. The expression specified with $filter is evaluated for each resource in the collection, and only items where the expression evaluates to true are included in the response.

 Let’s understand the difference between $search and $filter parameters:

$search starts with an empty result set and adds items to it based on criteria that match, while $filter takes full result set, and removes items based on criteria that don’t match.

$search operates like a free text search, while $filter works on predefined logical and string functions.

Which logical and string functions are supported with $filter?

As per current MS Graph API documentation, following functions are supported, but the support varies as per which entity you are dealing with, so always refer to latest documentation on Microsoft site:

  • equals (eq)
  • not equals (ne)
  • greater than (gt)
  • greater than or equals (ge)
  • less than (lt), less than or equals (le)
  • and (and)
  • or (or)
  • not (not)
  • startswith
  • any


Let’s see some examples of how you can use $filter parameter.

Open MS Graph Explorer here and fire following call:

See the data returned in JSON response, it returns all people associated with the sample account whose job title is not set:

filter job title

Similarly, if you want to see only those records where job title is set, then simply change the operator “eq” (for equal to) to “ne” (for not equal to)

You will see the following response which will list all users who has job title assigned:

filter job title not null

Please note here that you see only 2 properties in the response, because I also used the $select parameter in the API call. You can use “&” in an API call when you want to use more than one optional query parameter: two parameters.PNG

There are many more uses of $filter parameter possible, but I will restrict to only two examples for brevity. I suggest you read more on Microsoft Graph API documentation page here.


Use the $filter parameter in your programming to:

  • make API calls with logical operations for checking equality, greater than, less than, etc. operations


(8) $skipToken


When a response from MS Graph API does not contain all the available records (due to user explicitly specifying to select only some top records or due to server-side paging implemented in Graph API to limit response size), then you will see the response contains a server generated value with $skipToken parameter.

This value is to be specified in the next call to MS Graph API so that it will return the next set of records. The value of $skipToken is generated by server, it can not be specified by you as a consumer.


Fire the following call to get only top 10 files stored on user’s OneDrive:

See the result, note the value in @odata.nextLink property:

skip token value

The @odata.nextLink property contains the call which should be fired to get the next set of result. For identifying what should be returned, it has a skip token generated from server-side with some logic to skip those records in current response.

Simply fire the query mentioned in the @odata.nextLink property, and you will get next set of values.


  • In your programming, you can use $skipToken to get paginated data (implement paging).



Not all query parameters are supported for all entities. Always refer to latest Microsoft documentation for what’s supported. I also suggest firing the call in MS Graph Explorer first and see if you are getting the expected result or not, before starting any programming and later having any surprise.

If you include some query parameter for a non-supported entity, then MS Graph API will throw appropriate error.

Let’s understand with an example.

Fire following call in MS Graph Explorer:

You will get error 400:

 filter 123


Using query parameter without ‘$’ prefix in beta version of MS Graph API

With beta version of MS Graph API, using “$” prefix before a query parameter is optional.

Fire following call in MS Graph Explorer to get top 2 recently accessed files in result:

You will see the following result:

beta top

Note that the “top” query parameter is used without any “$” prefix here and still you get only 2 records in result.

This concludes my 2-part article series on MS Graph API query parameters. I hope you enjoyed learning about how to use query parameters in the MS Graph API call.

I suggest you keep reading more about MS Graph API until my next article.

You can read some of my articles on MS Graph API here.


Header image courtesy: Microsoft

This article may be published by me on other websites too.


Using optional query parameters with Microsoft Graph API – Part 1

How to use optional OData query parameters while working with MS Graph API

In this article, I will explain how to execute the calls to Microsoft Graph API using some optional OData query parameters.

The objectives of this article are:

  • What are the optional OData query parameters?
  • List of supported OData query parameters, when to use which one
  • Execute some Graph API calls using query parameters

While Microsoft already has the documentation to cover all its technology, in this article, I will try to explain these OData query parameters with some different angles and usage scenarios. I’m sure you will enjoy reading this article and learn something new.


This article shows how you can fire some calls to MS Graph API using optional query parameters with the MS Graph Explorer available here:

Office Development

In my previous articles, I explained the different components of Microsoft Graph Explorer and showed how to execute MS Graph API calls using the sample account. I suggest you read those articles too for better understanding MS Graph API Explorer.

You can read my previous articles on MS Graph API Explorer here:

What are the Optional Query Parameters?

The current version of Microsoft Graph API supports the OData version 4.0 standard. This OData standard defines how the data is exchanged between the originator and the consumer of the REST APIs.

Look at the format of an API endpoint in Microsoft Graph API:

Office Development

Here “query-parameters” is an optional set of parameters to modify the response/output of API calls. It always starts with $ sign. (Please note here that in the beta version of MS Graph API, using $ is now optional. We will see that later in the article). Query parameters start after “?” sign.

The Microsoft Graph API documentation here describes the optional query parameters as:

“You can use optional query parameters to customize the response in your Microsoft Graph app. Use query parameters to include more or fewer properties than the default response, filter the response for items that match a custom query, or provide additional parameters for a method.”

The OData standards specification on defines the optional query parameters as “System Query Options” which are explained in great detail here.

The ODATA standards specification explains these query parameters as:

“System Query Options are query string parameters a client may specify to control the amount and order of the data that an OData service returns for the resource identified by the URI. The names of all System Query Options are prefixed with a “$” character.

An OData service may support some or all of the System Query Options defined. If a data service does not support a System Query Option, it must reject any requests which contain the unsupported option…”

In short, using these optional query parameters in the API endpoint query string you can define the criteria applicable on the result. And these parameters are optional meaning if you don’t mention any of them in the query string, then also the API call works fine.

If you are not aware of OData standard, then I suggest you to spend some time on reading about the OData specification on the website here for better understanding of OData concepts.

List of supported query parameters in Microsoft Graph API

The following query parameters are supported in the current version of Microsoft Graph API:

  • $count
  • $expand
  • $filter
  • $orderby
  • $search
  • $select
  • $skip
  • $skipToken
  • $top

A complete list with details can be found on Microsoft Graph API documentation website here.

Let’s now see each of the above query parameters one by one in detail and fire queries in Microsoft Graph API Explorer.

I will explain them in increasing order of complexity of understanding.

(1) $top


This parameter will fetch only certain number of data items as specified along with $top.

At times, you will not need to fetch all the items from the result set, but only first few of them. In this case, $top query parameter is used to specify how many items should be returned in the result.

Usually, $top query parameter is used with $orderby query parameter (Read more about $orderby in section 3 below).


Open MS Graph Explorer here and fire following calls

Notice the amount of data being returned in results in the above calls. In real life API call execution, it will return the current user’s emails and all files on his/her OneDrive. This may not be required always, and returning these many items may not be best suited option performance-wise too.

When you want to see only some limited number of records, at that time you can use $top.

Go to MS Graph Explorer here and fire the following call:$top=2 or click here, then press “Run Query”.

You will see only two result items, not the list of all messages,

Office Development
Note: I have collapsed the JSON result in above screenshot to show items fit in one screen.


In your programming, you can use $top query parameter to:

  • Show recent/latest/top items from a list of items
  • Implement paging (often used with $skip and $orderby)

(2) $count


This parameter will fetch the total number/count of data items in the specified API endpoint along with the result.

Note that the API call will return the result “as it is” without this query parameter, but if this parameter is specified, then in addition to the result, a number indicating the result count is also returned.

You will see the result count in @odata.count property in response JSON.


Open MS Graph Explorer here and fire following call to get list of emails

It will show the following result,

Office Development

Notice here as highlighted in above screenshot, MS Graph API will return to you the count of emails as the value of property @odata.count.

Fire more calls in MS Graph Explorer to understand the $count parameter as shown below

You will see MS Graph Explorer does not return any count or does not return any error, it simply returns a valid result. If the $count parameter is not applicable on the API endpoint it will ignore it.

I leave it to you now to try and explore the $count parameter with different Graph API calls.


In your programming, you can use $count query parameter to:

  • Get the no. of result items in the result, along with result item(s)

(3) $orderby


This parameter will make the Graph API return the result in a specific sorting order. Sometimes, you will want your result from MS Graph API to be sorted in a certain order depending on the date or name or some other property of the resource being returned. Use $orderby parameter in those cases to get your result sorted in certain order.


Open MS Graph Explorer here and fire following call to get all users.

You will see all the organization’s users are returned here. They are in the order of email address. You may want to have the result ordered by another property, let’s say display name.

Execute the following call

You will see the list of users is ordered by the display name of user,

Office Development
Note: In above screenshot only one result fits in the screen. Try scrolling the response view by yourself to see all the items.

The default order by is done in ascending order. If you want to order by descending order, then specify “desc” in the URL separated by a space.

Execute the following call,

You will see the list is now ordered descending by the display name:

Office Development


In your programming, you can use $orderby query parameter to:

  • Get an ordered list of result items, based on certain property
  • Get emails, events, other items in ascending or descending sort order

(4) $skip


This query parameter tells the MS Graph API to omit the number of records as specified along with $skip from the result set. MS Graph API will follow the same sorting order it follows (if $orderby is not specified) and will omit that many number of records from the result as specified in the query string.


Open MS Graph Explorer here and fire following call to get the list of contacts:

It will show the result with all contacts of sample account. Note the result’s “displayName” values for first 4 records (they start with “A”).

Now run the following query to skip first 4 records from result

You will see the result without those first 4 contacts,

Office Development

MS Graph API has omitted first 4 records from the result set.

What happens when we specify a skip count greater than no. of records in the result? Let’s find out.

Run the following query to skip 10000 records from result

We know there are no more than 10000 contacts in the sample account. This is the result you will get, it simply returns an empty set

Office Development


In your programming, you can use $skip query parameter to:

  • Omit the first few items from a list of items
  • Implement paging (often used with $top and $orderby)

We will see the rest of the parameters in next article. Until then you can go to MS Graph Explorer and try the above examples by yourself.

You can also read more of my MS Graph API articles here.


This article was first published by me on C# Corner Website here.

Header image courtesy: Microsoft

Office 365 Development with Visual Studio 2017 – Part 2

When Visual Studio 2017 was launched earlier this year, I wrote an article to provide a glimpse of how to get started with Office 365 development with VS 2017 and different project templates available in VS 2017. You can read it here.

Let’s continue our journey of Office 365 development with VS 2017 in this article.


In this article, we will walk through creating and running Office 365 projects in VS 2017. Along with that, I will explain Office 365 Add-in concepts side by side.

We will learn the following in this article.

  • Creation of Excel add-in projects
  • Brief intro of Office 365 Add-in
  • When you should choose which type of project


This article assumes that you already have installed Visual Studio 2017 with Office 365 development option on your PC. If not, then please read part-1 and follow the installation steps. You will not see the project templates mentioned in this article if you don’t have the correct version of Visual Studio with Office 365 development option.

To make sure which version of Visual Studio you are using, go to “Help” menu and select “About Microsoft Visual Studio” sub-menu in Visual Studio.

Make sure you are using Visual Studio 2017.

Office Development

I’m using Community edition of VS 2017 which is “Free, fully-featured IDE for students, open-source and individual developers”.

Office Development
Image credit: Microsoft

You can download VS 2017 Community edition here.

The Office 365 development options are same in all editions of VS 2017, namely Community, Professional, and Enterprise. So, it will not matter whichever edition of VS 2017 you have for following the steps of this article.

Getting Started

Let’s start with creating a new Office 365 project for the add-in.

Either click on the menu “File” -> “New” -> “Project” or on the “Start Page” under “New Project” section, click on “Create new project…”:

Office Development

In the “New Project” popup, expand “Office/SharePoint” category under Visual C# and click on “Add-ins”.

Office Development

You will see project templates for Word, Excel, PowerPoint, Outlook, and SharePoint add-in.

Let’s briefly understand about Office 365 add-ins.

What is Office 365 add-in?

With Office 365 add-in or Office add-in, you can build program/solution that extends Office applications and interacts with the content in Office documents. You can add new functionality to Microsoft Office clients or create new rich, interactive objects that can be embedded in Microsoft Office documents. Office add-in runs in Microsoft Office across multiple platforms, including Office for Windows, Office Online, Office for the Mac, and Office for the iPad.

For more information on Office 365 add-ins, read on Microsoft website here. I will cover more on Office 365 add-ins in a separate article later.

In the New Project popup, select “Excel Web Add-in”, then click OK.

You will see a “Create Office Add-in” dialog with following two options:

  • Add new functionalities to Excel.
  • Insert content into Excel spreadsheets.

    Office Development

Let’s quickly see what this means. We will understand by inserting some add-in in Excel.

Open Excel and create a new workbook. Go to “Insert” -> “My Add-ins” -> “See All…”:

Office Development

“Office Add-ins” dialog will open. Click on “STORE”, enter “Wikipedia” in search, once Wikipedia add-in appears, click on “Add” button next to it.

Office Development

The dialog box will close and you will see now that the “Wikipedia” add-in is added under “Add-ins” ribbon.

Office Development

Click on it and on the right side, you will see a new section.

Office Development

Anything you can do on Wikipedia website, now you can do from inside Excel only using this add-in.

This is an example of “Extend functionality” type of add-in. These types of add-ins let you do some work right from Office applications without opening any other application. If you want to create this type of add-in, you should select “Add new functionalities to Excel” option in “Create Office add-in” dialog.

Now, let’s see some other add-in examples. Once again in Excel, go to “Insert” -> “My Add-ins” -> “See All…”. In the “Office Add-ins” popup, click on “STORE” tab and search on “bubbles”,

Office Development

Click on the first row “Add” button. You will see in the top right under “Insert” ribbon, a new “Excel Bubbles” add-in is available now.

Office Development

Click on it and a section with bubbles is added into current worksheet.

Office Development

Click on the “Sample Table” bubble in this section. It will add some sample data in worksheet and populate bubbles as per data,

Office Development

This is an example of “Content” type of add-in which adds some content inside an Office application. If you want to create this type of add-in then you should select “Insert content into Excel spreadsheets” option in “Create Office add-in” dialog.

Let’s go back to Visual Studio now. We were on this popup,

Office Development

Let the selection be “Add new functionalities to Excel”. Click “Finish”.

VS will create a new Excel add-in solution with 2 projects,

Office Development

Before understanding “what” these projects are and “why” they are created, let’s first understand the composition of an Office 365 add-in.

An Office 365 add-in consists of two components,

Office Development
Image credit: Microsoft

  • XML manifest file
    specifies settings and capabilities of the add-in
  • Web application
    interacts with Office clients and documents

Now coming back to Visual Studio, in VS 2017 Solution Explorer, you will see these two projects:

  • ExcelWebAddIn1
    This is the manifest project containing the XML add-in configuration/settings
  • ExcelWebAddIn1Web
    This is the project which has all code defining the add-in & its interaction with Office document. It has JavaScript and HTML files which define the UI of the add-in.

    To provide same look and feel in the add-in as Office 365 clients, it uses Office UI Fabric JavaScript. I will cover more on Office UI Fabric JS in separate article later.

Let’s now run the project to see it working. Press F5, VS will build the solution and launch Excel to make your add-in available inside it.

In Excel, “Show Taskpane” button will be focused with a tool tip message,

Office Development

Click on the “Show Taskpane” button. The task pane area will be loaded on the right side of Excel worksheet.

Office Development

Please note that when you created a new Excel add-in project, VS 2017 has included some sample code in it. That’s why you see the text and button here. Also, if you note the worksheet has been loaded with some sample data,

Office Development

This sample add-in is for finding and highlighting highest value cell among the selected ones. To see it in action, select the sample data and click on “Highlight” button,

Office Development

The JS code will get executed and highest value cell among the selected cells will be highlighted.

Stop the running project from Visual Studio and let’s now see the code which made it work.

In the Solution Explorer, double click the “Home.html” file.

This is the file which contains all UI elements. The texts and button you saw in Excel add-in are defined here,

Office Development

In the Solution Explorer, double click on home.js file.

This is the file which contains all code to interact with Excel.

Office Development

It sets the button text to “Highlight” and also sets the JS function which should be executed when someone clicks on it, among other things.

The load sample data JS function which populates the worksheet with some random numbers,

Office Development

The code for finding the highest value cell and highlighting it,

Office Development

See how simple it is to get started with Office 365 add-in development? You must give it a try yourself using VS 2017.

The purpose of this article was to make developers aware of Office 365 add-in development using VS 2017 which I have done above. You have to come up with the idea of your add-in to create a real-life Office 365 add-in which adds some value to the Office clients.

That’s it for this article. I will cover more add-in options in next article.

Note: This article was originally published by me on C# corner website here.

Featured image courtesy: C# Corner