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

Explanation:

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.

 Example:

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

See the data returned in JSON response:

OneDrive

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:

Usage:

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

Explanation:

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.

Example:

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:

search.PNG

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.

Usage:

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

Explanation:

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

Example:

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.

Usage:

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

Explanation:

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.

Example:

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.

Usage:

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

 

Limitations/Errors

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.

Background

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 www.odata.org 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 odata.org 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

Explanation

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).

Example

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:

https://graph.microsoft.com/v1.0/me/messages?$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.

Usage

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

Explanation

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.

Example

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.

Usage

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

Explanation

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.

Example

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

Usage

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

Explanation

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.

Example

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

Usage

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

Get Office 365 data in Excel using MS Graph API

Learn how to use MS Graph API in Excel

Objective:

Recently I wrote an article about how you can consume MS Graph API in Power BI (read it here). MS Excel can also consume Microsoft Graph API in the same way.

In this article, I will show how you can quickly fetch Office 365 data of your organization in MS Excel using Microsoft Graph API. We will fetch an organization’s users list in MS Excel with MS Graph. Once you learn to use MS Graph API in MS Excel, you can explore more options by yourself.

To make this article easy to follow, let’s identify a real-world requirement and then see how we are going to solve it using MS Graph API and Excel.

Requirement:

Suppose you are working in the IT department of an organization who employs 500+ users. On weekly basis, new employees join your organization and some leave too. The receptionist needs up-to-date information about all employees and their contact details. You are asked to provide her a simple solution. You create an Excel workbook for her using MS Graph API data feed which will show list of employees which she can refresh anytime to get latest updates.

 Introduction:

What is MS Graph API?

Excerpt from https://developer.microsoft.com/en-us/graph/docs/concepts/overview

You can use the Microsoft Graph API to interact with the data of millions of users in the Microsoft cloud. Use Microsoft Graph to build apps for organizations and consumers that connect to a wealth of resources, relationships, and intelligence, all through a single endpoint: https://graph.microsoft.com

For more on MS Graph API, please go to https://developer.microsoft.com/en-us/graph

There is no coding involved to follow steps of this article. However, if you want to follow along the steps, then it’s better to have Office 365 developer account as mentioned in “Prerequisite” section below.

 Prerequisite:

  • Office 365 developer account

You may have access to Office 365 thru your employer/organization account. However, it is strongly advised that you don’t use your live/organization account to follow steps of this article. Instead, use Office 365 developer account. Use your live/organization account only when working in a production environment.

Read my blog on how to get Office 365 developer account for 1 year free here.

 Getting Started:

I assume you have Office 365 developer account and you also have MS Excel installed on your PC.

Open MS Excel and create new workbook.

Go to “Data” tab in ribbon and click “Get Data” on left side:

GetData1

When “Get Data” menu expands, click on “From Other Sources”, then click “From OData Feed” as shown below:

GetData 2

Once you click on “From OData Feed”, you will see a dialog to enter OData feed URL:

Odata URL

Why we choose this option?

MS Graph API is based on open web standards and it supports OData V4, and MS Graph API accepts and returns data in JSON format, making it easy to integrate with other applications and technologies.

We want to access all the users of an organization. The MS Graph API endpoint https://graph.microsoft.com/v1.0/users returns all users of an organization.

Enter https://graph.microsoft.com/v1.0/users in the textbox under URL and click OK:

Odata URL 2

Once you click on OK, you will see a dialog where you can specify your credentials to connect to MS Graph API:

Odata feed

Click on “Organizational account”, then click on “Sing in” button:

Odata feed 2

You will see “Office 365 Sign in” dialog:

O365 login

Don’t use your organization/live account to sign in. Use your Office 365 developer account to sign in.

After successful login, the “Office 365 Sign in” dialog will close, and your status on OData feed dialog will change to “singed in”:

Odata feed 3 Connect

Click on Connect button to continue.

It may take some time to fetch the result from MS Graph API call depending your internet connection, but it will not be more than a few seconds. Once MS Excel fetches the users using MS Graph API, it will show you result in a dialog.

For demo, I have created some users in Office 365 Admin Portal using my developer account. I suggest you also create some demo users with your Office 365 developer account using Office 365 Admin Portal.

You will see a result dialog like this, filled with your organization’s users:

result dialog

Notice the “Load” button has a down arrow, click on it and you will see “Load” and “Load To…” options:

Load

Click on “Load To…” link, you will see an “Import Data” dialog:

import data

This dialog has options for how you want to view the data and where you want to place the data. You can import the data to new worksheet too. We will not do anything special in this dialog, I just wanted to show you the options available in Excel.

Click on OK button and the dialog will close. As “New worksheet” was selected in “Import Data” dialog, you will see a new sheet has been added to Excel and data is populated:

excel result

What has happened here?

MS Excel has received the JSON data result from MS Graph API in response to the call to https://graph.microsoft.com/v1.0/users endpoint, and converted it to a data table for you. What you see here is the list of all properties it got from MS Graph API.

By default, Excel will load all the columns it received from MS Graph API, some columns will not have data and you will not want to display all the columns. We will see in some time how you can choose only some columns to be displayed.

Also, if you note on right side new section “Queries & Connections” has been added:

queries

Right click on “Query1” and click “Edit”:

Query Edit

You will see “Query Editor” is opened in a popup, click on “Choose Columns”:

Choose Columns

You will see “Choose Columns” dialog:

Choose Columns 2

Uncheck the very first “(Select All Columns)” checkbox, then select only below columns, then click OK:

  • displayName
  • jobTitle
  • mail
  • mobilePhone
  • officeLocation

You will see now Query Editor will only show the columns we selected in above step:

Close and load

Click on “Close & Load” button on top left to continue.

The Query Editor will close and you will Excel now shows you only those columns you selected:

excel chosen columns

Good job! You got your organization’s data in Excel using MS Graph API. How simple it was!

Now, let’s come back to the receptionist’s requirement I mentioned at the start of the article. A new employee has just joined office. She needs his details in this Excel too. What should she do?

For the demo to work, I have opened Office 365 Admin Portal and added a new user named “Graph Explorer” to my organization using Office 365 developer account. I suggest you also add a new demo user to your developer account using “Office 365 Admin Portal” -> “Add a user” link.

After adding a new user in Admin Portal, right click on “Query1” in Excel and click “Refresh”:

refresh

Excel will once again connect to MS Graph API and will fetch result and refresh the contents in worksheet:

new user

Do you see the user “Graph Explorer” now in the first row?

So, the reception’s requirement is fulfilled. Every time she wants latest data, she has to just hit “refresh” and MS Graph API will do the rest.

What’s next?

The purpose of this article was only to show you how MS Graph API data can be consumed in MS Excel, which I have shown above. Similarly, you can try by yourself calling some other MS Graph API endpoints.

Meanwhile, if you want to read more of my articles on MS Graph API, please visit https://nilesh.live/blogs/msgraph/.

Display Office 365 data using MS Graph API in Power BI

Learn how you can consume MS Graph API data in Power BI

Objective:

In this article, I will show how you can display Office 365 data of your organization in Power BI report using MS Graph API.

I will show how you can fetch your organization’s users with MS Graph API, and quickly create a report using Power BI Desktop. Once you learn to use MS Graph API in Power BI, you can explore more options to create some interesting reports on your own.

Background:

This article assumes you know something about MS Graph API and Power BI.

What is MS Graph API?

Excerpt from https://developer.microsoft.com/en-us/graph/docs/concepts/overview

You can use the Microsoft Graph API to interact with the data of millions of users in the Microsoft cloud. Use Microsoft Graph to build apps for organizations and consumers that connect to a wealth of resources, relationships, and intelligence, all through a single endpoint: https://graph.microsoft.com

For more on MS Graph API, please go to https://developer.microsoft.com/en-us/graph

What is Power BI?

Excerpt from https://powerbi.microsoft.com/en-us/

Power BI is a suite of business analytics tools that deliver insights throughout your organization. Connect to hundreds of data sources, simplify data prep, and drive ad hoc analysis.”

For more on Power BI, please go to https://powerbi.microsoft.com/en-us/

There is no coding involved to follow steps of this article. However, if you want to follow along the steps, then you will need things mentioned in “Prerequisites” section. If you don’t want to follow along and just want to read, you can jump to “Getting Started” section.

Prerequisites:

  • Office 365 developer account

You may have access to Office 365 thru your employer/organization account. However, it is strongly advised that you don’t use your live/organization account to follow steps of this article. Instead, use Office 365 developer account.

Read my blog on how to get Office 365 developer account for 1 year free here.

  • Power BI Desktop

You will need Power BI Desktop to create the report which will consume MS Graph API data.

Power BI Desktop can be downloaded free from this link:

https://www.microsoft.com/en-us/download/details.aspx?id=45331

Power BI Desktop getting started guide is here:

https://powerbi.microsoft.com/en-us/documentation/powerbi-desktop-getting-started/

 

Getting Started:

I assume you have Office 365 developer account and you have installed Power BI Desktop on your PC.

Let’s get started.

Open Power BI Desktop.

PowerBI1

Once open, you will see it’s welcome screen:

PowerBI2

Click on “Get Data” just below Power BI Desktop header on top left.

Alternatively, if you close this welcome screen, then you will also see “Get Data” icon at top left:

PowerBI3

Once click on “Get Data”, you will be presented with a “Get Data” dialog. Click on “Other” in left-middle section:

Get data

Once you click on “Other” link, on the right side of dialog you will see some options. Select “OData Feed”, then click on “Connect” button:

Odata Feed

You will see a dialog to enter OData feed URL:

Odata Feed blank

Why we choose this option?

MS Graph API is based on open web standards and it supports OData V4, and MS Graph API accepts and returns data in JSON format, making it easy to integrate with other applications and technologies.

We want to access all the users of an organization. The MS Graph API endpoint https://graph.microsoft.com/v1.0/users returns all users of an organization.

Enter https://graph.microsoft.com/v1.0/users in the textbox under URL and click OK:

Odata Feed2

Once you click on OK, you will see a dialog where you can specify your credentials to connect to MS Graph API.

Odata Feed3

Click on “Organizational account”, then click on “Sing in” button:

Odata Feed4

You will see Office 365 log in dialog:

O365 login

Don’t use your organization/live account to sign in. Use your Office 365 developer account to sign in.

Once you login successfully that dialog will close, and your status on OData feed dialog will change to singed in:

O365 login2

Click on Connect button to continue.

Once Power BI fetches the users using MS Graph API, it will show you in a dialog. For testing purpose, I have created some users using my developer account. I suggest you also create some test users in your Office 365 developer account using Office 365 Portal.

I have masked some sensitive data from my popup:

user data

You should also see your organization’s users here. Click on “Load” to continue.

You will see some messages in a popup while Power BI loads your data using MS Graph API:

loading

Once this dialog closes, on the right side you will see the data table under “Fields” section:

fields

What has happened here?

Power BI Desktop has received the JSON data from MS Graph API in response to the call to https://graph.microsoft.com/v1.0/users endpoint, and converted it to a data table for you. What you see under the Fields -> Query1 section is the list of all properties it got from MS Graph API.

Now we have the data we want from MS Graph API loaded into Power BI. Let’s create a report using it.

Click on “Table” icon under Visualizations on right side of screen:

table

You will see your screen will be loaded with an empty table:

empty table

Now we should select which fields we want to show in table. Under Fields section on right, select displayName, jobTitle and officeLocation fields in that order:

fields selection

As and when you select the fields, you will see the table being loaded with data:

table with data

Hurray, you have created your first Power BI report using MS Graph API!

What’s next?

The purpose of this article was only to show you how MS Graph API data can be consumed in Power BI, which I have shown above. Similarly, you can try by yourself creating some other reports/visualizations and calling some more MS Graph API endpoints.

If you want to share the report, you can do it using the Publish feature of Power BI:

publish

But this requires a Power BI account and it’s out of scope for this article. I suggest trying it on your own.

Meanwhile if you want to read more of my articles on MS Graph API, please go to https://nilesh.live/blogs/msgraph

How to use Microsoft Graph Provider in Visual Studio Connected Services

In this article, I am introducing the newly added Microsoft Graph Provider in Visual Studio 15.3.1. This article demonstrates how a developer can use this feature to work with Microsoft Graph API.

If you don’t know anything about Microsoft Graph API, then I suggest you read something about it here.

To make this article meaningful, I am explaining it using a new Excel add-in project. There is no coding involved though.

Prerequisites:

There are some prerequisites if you want to follow the exercise I have shown in this article. If you just want to read and don’t want to follow any steps by yourself, then please jump to Let’s Start section in this article.

  • Visual Studio 15.3.1 with Office Development Tools

On August 18, 2017, Microsoft has released Visual Studio 2017 version 15.3.1. For more on this release see release notes here.

This article assumes that you have already installed Visual Studio 15.3.1, if not then you can download it here.

For more specific content on how to install Visual Studio, please read my article here.

You will also need to have Office Development tools installed while you install Visual Studio. Please read my article on that here.

  • Office 365 Developer account

You may have access to Office 365 thru your corporate account provided by your employer. But it is strongly advised that you don’t use that account. Instead of that, get an Office 365 developer account here for free and enjoy 365 days of Office 365!

For more info on that, please read my article on Office 365 developer program here.

Before moving further, let’s make sure that you are using the correct version of Visual Studio for following instructions in this article, otherwise it will not work. Multiple versions of Visual Studio can be installed side by side, including preview version, so it’s necessary to make sure of correct version you are working with.

In Visual Studio, Open the menu Help -> About Visual Studio:

About Visual Studio

Please make sure 15.3.1 is the version of your visual studio:

VS version

If that’s the version of your Visual Studio, then let’s start.

 

Let’s Start

Open Visual Studio 15.3.1 and click on “Create New Project…”

In the “New Project” window, Select “Visual C#“ -> “Office/SharePoint” -> “Add-ins” -> “Excel Web Add-in”:

new project

Click on “Ok” to create a new project.

In the next window that appears, select the option “Insert content into Excel spreadsheets”, then click “Next”

office addin 1.png

Select “Basic Add-in”, then click “Finish”

office addin 2

Visual Studio will create a new Excel add-in project for you.

Once Visual Studio is ready, open Solution Explorer, find “Connected Services” under your project and double click on it:

connected services 1

You will see the following screen:

connected services 2.png

Click on “Access Office 365 Services with Microsoft Graph” which is the core of this article.

You will be shown a window to configure access to your Office 365 services:

connected services 3

If you have your Office 365 developer account, then enter the domain name you selected in the “Domain” textbox. Don’t forget to add “.onmicrosoft.com” too.

connected services 4

I have entered my developer account domain, but masked it for security.

If that was the correct domain you entered, the you will be shown a sign-in window where you will enter the details you used while registering for Office 365 developer account.

connected services 5

If your login information is correct, you will be shown “Configure Application” section:

connected services 6

Let it be “Create a new Azure AD application”, and click “Next”.

Now the wizard will ask you for permission to different Office 365 sections. It’s up to you what permissions you want to assign. You can change it later.

connected services 7

Following are the permissions I selected under “User” tab:

connected services 8

Similarly, I also selected some permissions in other tabs.

Once you are done selecting permissions, then click “Finish”:

connected services 9

It will take some time for Visual Studio to configure the access. Meanwhile you will see a window like below:

connected services 10

Once Visual Studio is done with configuring access to Office 365, that window will close automatically. If there was any error, it will be reported to you. Otherwise you will see success message in output window:

output window

Also, if you note – under “Connected Services” in Visual Studio, Office 365 Services will have a green tick mark:

green mark

There is also something more which happened.

Go to Solution Explorer. Do you see under “Connected Services” a new folder of “Office365” has been added?

solution explorer

Those two files under Office365 folder are not too important programmatically. One is a link to Microsoft Graph documentation, another is a JSON file with link to getting started documents. But we will leave those untouched as of now.

Open the Web.config file and see what’s changed here. You will see under the appSettings tag, Visual Studio has added some configuration details:

config details

You will see client id, client secret, tenant id and domain are automatically inserted in this file based on the information you provided while configuring access to Office 365.

Visual Studio also created an application under Microsoft Azure Application Registration for you.

To check that, login to portal.azure.com with the same account as you used for configuring access to Office 365 above.

Once logged-in to Azure, under search type “app reg”:

app reg 1

Click on “App registrations” link.

Under “app Registrations” you will see an app with the same name as your project in Visual Studio:

app reg 12

The GUID under application id is what you will see in your web.config file. You will not see the client secret anywhere though.

Also, if you note under package manager, Visual Studio has already added references to MS Graph SDK:

nuget

See how easy it has been made by Visual Studio now to kick start your Office 365 development using Microsoft Graph?

This article’s purpose was only to make developers aware of the addition of Microsoft Graph under connected services in Visual Studio. I will cover the actual code to be written in a project to call Microsoft Graph API in another article some time later.

Meanwhile if you want to see by yourself how you can call Microsoft Graph using Visual Studio, please go to this link.

For my more articles on Microsoft Graph, please visit here. Please also visit my home page nilesh.live for list of all my blogs.

Header image courtesy: Microsoft

A First Look At The New Microsoft Graph Explorer – Part Three

Note: All my blogs on Microsoft Graph API can be found here.

In first two parts of my article series “A First Look at the New Microsoft Graph Explorer”, I explained about different components of Microsoft Graph Explorer. I suggest you to read those two parts first, before reading this third part for better understanding.

You can read the previous parts here:

I will continue the article series with part three where I will explain how to execute the calls to Microsoft Graph API.

The objectives of this article are:

  • Execute some Graph API GET calls using sample account
  • Look at Microsoft Graph API metadata
  • Calling beta API

Execute Graph API GET calls using sample account

Let’s look at some simple GET calls to Microsoft Graph API using the Graph Explorer.

Open the Microsoft Graph Explorer by clicking here.

Check the left section under “Authentication”.

Office Development

It says currently a sample account provided by Microsoft with some test data is being used. You can fire GET calls using this account right away.

If you see the API endpoint address bar you will notice,

Office Development

API endpoint for getting user’s profile is already loaded.

Simply click on “Run Query” button to execute the API call.

Office Development

You will see that the response area of the page is updated with something, like below.

Office Development

The status in the green background indicates that the call was successful with HTTP status code of 200 and executed in 869 mill seconds.

Look at the JSON data in “Response Preview” section.

It has some data of “user” which is the current user provided by Microsoft sample account. If you are logged in with your account, then you will see your data. I will cover the calls after login with your account later.

There is also something more.

Microsoft Graph API metadata

You might be wondering how to find out what data to expect in an API GET call response or what data to pass in an API call POST request. You can read the Graph API documentation or look at the sample queries on left side section, but there is also another way.

Look at the first line of the JSON response,

Office Development

You will see a URL for “@odata.context” property.

Copy the URL and paste in a new tab.

Office Development

You will see it loads an XML file. A big XML file. That’s the OData documentation of the Microsoft Graph API. Microsoft Graph API metadata in other words.

It specifies the different entities and actions along with properties and parameters.

Search for the following in the page- EntityType Name=”user”.

Office Development

You will find the user entity along with its properties and navigation properties. You will also find some more entities, more actions, functions. You can also see the Graph API metadata page directly here,

The following lines are taken from the Microsoft Graph website as it is:

“The metadata allows you to see and understand the Microsoft Graph data model, including the entity types, complex types, and Enums that make up the resources represented in the request and response packets.

You can use the metadata to understand the relationships between entities in Microsoft Graph and establish URLs that navigate between those entities.

Path URL resource names, query parameters, and action parameters and values are not case sensitive. However, values you assign, entity IDs, and other base64-encoded values are case sensitive.”

For the scope of this article, I will not go deeper inside this XML file and will leave it to you to explore more.

Back to the Graph Explorer

If you place your mouse cursor in the API address bar and press back space key and remove everything till “v1.0/” you will see the Graph Explorer will hint you possible API endpoints you can fire,

Office Development

Similarly, if you start typing “me/” then it will show you possible endpoints after “me”

Office Development

Now, type https://graph.microsoft.com/v1.0/organization in the address bar and press “Run Query” button, you will see the logged in user’s organization info,

Office Development

Please note that in Microsoft Graph API “me” and “organization” are the only two aliases in Microsoft Graph API i.e. these two are not the actual objects in Office 365.

If you want to test more GET calls, then you can see list of some GET calls in left section under “Sample Queries”.

Office Development

More GET calls featured scenarios can be found here on Microsoft Graph website,

Office Development

Calling API in preview

Now, let’s see how to call some Graph API endpoints which are still in preview i.e. in beta.

Change the API version to “Beta” in the version lookup,

Office Development

Copy and paste https://graph.microsoft.com/beta/me/insights/trending in the API endpoint address bar and press “Run Query” button,

Office Development

You will see the names of some documents are returned with their “weight”. These are the “trending” documents around the user and you need to write some code to convert the “weight” of each document to some meaningful representation to end user.

But the purpose of making this call is to make you understand how to fire a beta API call in Microsoft Graph Explorer.

Now change the API version to V1.0, keep the API endpoint URL same and fire the call,

Office Development

You will see it returns an error, because this endpoint is only in beta version and not yet in V1.0.

I hope you will play with Microsoft Graph Explorer and fire some more GET calls until I write the next article and we continue the journey of learning with the new Microsoft Graph Explorer.

Note: This article was first published by me on C# Corner website here.

Header image courtesy: Microsoft

A First Look At The New Microsoft Graph Explorer – Part Two

Note: All my blogs on Microsoft Graph API can be found here.

Part-1 of the my series “A first look at the new Microsoft Graph Explorer” can be accessed here. If you have not read it yet, I suggest you read it first to maintain continuity of your reading.

I will continue from where I left off in the last article. We will see the remaining sections of the Microsoft Graph Explorer in some detail.

The objective of this article is to cover the following topics, among others:

  • History section
  • Request & Response sections
  • Share Query section

For a quick note; you can see Microsoft Graph Explorer here.

The “History” section

Office Development

Scroll down on the left section to see the History section.

You can collapse “Sample Queries” section if it has some sample queries in it, to see the History section quickly.

Office Development

If the “History” section is already collapsed, expand it.

Office Development

Upon expanding, or if it is already expanded, you will see it like below.

Office Development

If you haven’t executed any Graph API at all, then the section will be empty.

Office Development

The “History” section maintains the history of the Graph API calls you executed and by clicking on the links in this section, you can easily re-play those calls. A fresh request will be made to the Graph API when you click on a link from history.

Note that the “History” section maintains only the history of the request, and not the response. This means, the request will be fired again and you will always see the latest response from Graph API. There is no way to see what the response was originally when you fired that query  the first time.

As you make the Graph API calls, the browser URL does not change, so to get back to any of your previous calls, you can use this “History” section.

Let’s see now what’s there for each row in the “History” section.

Office Development

  • “GET” and “PATCH” indicates the request type
  • The “/v1.0/me/” indicates the API endpoint. It is equivalent of the full endpoint https://graph.microsoft.com/v1.0/me/, but for brevity it is displayed like this.
  • “200”, “204”, “400” are the HTTP response codes of the API call indicating what happened at that time
  • “3 minutes ago” displays the time at which that call was made
  • “146 ms” is the time taken by the Graph Explorer to execute the request.

The “History” section data is stored in cookies in your local machine and it is browser specific.

If you were working on Internet Explorer and if you open Firefox or vice versa, then you will not see the same history. This is true even if you are logged in using your Microsoft account.

Do you want to see more history? Click on the “show more” link at the bottom right of the history section.

Office Development

Office Development

Once you click on the “show more” link, Graph Explorer will open “History” popup.

Office Development

The contents of the popup are self-explanatory. You can either remove individual entry by taking the mouse over to a row and clicking “x” button at the end of the row, or remove all entries by clicking “Remove All” button.

If you click on any row, then the popup will close and the API call will be fired again.

“Request Header” and “Request Body” section

Along with the API endpoint and passing parameters in query string, sometimes you will also need to pass more data to the Graph API.

It is possible to pass additional data to MS Graph API thru the “Request Headers” and “Request Body” sections which can be found just below the API address bar,

Office Development

“Request Header” section

The HTTP request headers can be specified in the “Request Headers” area in form of key-value pairs. If you see by default there will be one textbox for the “Key” entry, on value side there is no textbox,

Office Development

The textbox on the “Value” side will appear once you start typing something in the “Key” textbox.

Let’s write “Accept” in the “Key” textbox,

Office Development

Immediately you will see there will be a textbox beneath the “Value” header, and a new row for “Key” textbox will be added as well.

Note that you must “type” something in the “Key” textbox for the “Value” textbox to be visible. If you copy and paste something inside the textbox, then the “Value” textbox will not appear.

How to pass some value in request header, how to execute the call and how to interpret the result will be covered later.

“Request Body” section

Let’s now see the “Request Body” section.

Click on the “Request Body” link just besides “Request Header” link.

Office Development

You will see a text area in which you can enter free-form text,

Office Development

“GET” requests will not have a request body, but to show you a demo I have copied one JSON result body and pasted it in the request body text area,

Office Development

You see it has little bit of “intellisense” too! It identifies the matching starting “{“ bracket when your cursor moves to the ending “}” bracket.

You can fire any “GET” call with anything in the request body, Graph API will just ignore it,

Office Development

How to pass some value in request body, how to execute the call, and how to interpret the result will be covered later.

“Response” sections

The response section is just below the requests section and it shows you the response you get back from the Microsoft Graph API call.

There are three sections here: “Response Message”, “Response Preview” and “Response Headers”,

Office Development

“Response Message” section is visible only after you fire an API call.

“Response Preview” and “Response Headers” both are read-only text areas because you are not supposed to write anything inside it.

For the demo, just click on “my profile” link in the “Getting Started” section inside “Sample Queries” on left side,

Office Development

Immediately you will see the API call result in the results section,

Office Development

“Response Message” section

The “Response Message” section is highlighted above.

It indicates,

Office Development

  • Success: the API call executed without any errors
  • Status Code 200: HTTP response code
    • For the understanding of HTTP status codes, click here.
  • 139ms: request execution time taken by Graph Explorer

In case of some failure, it will be like,

Office Development

“Response Preview” section

Office Development

It shows the Graph API call’s result body in JSON format.

“Response Headers” section

Click on the “Response Headers” section to see the HTTP response headers values,

Office Development

You will see here values for content-Type, request-id, duration, etc. among others. The response header values prove very handy sometimes in debugging API call errors.

Which API versions are supported in Microsoft Graph Explorer?

As of now, Microsoft Graph APIs are only in two versions: V1.0 for general availability, and “beta” for preview. Microsoft Graph Explorer supports both these versions.

You can see the supported API versions in Microsoft Graph Explorer when you expand the “API Version” selection as shown below,

Office Development

When to change the version and how to execute the API calls is covered later.

Which HTTP request types/verbs/actions are supported in Microsoft Graph Explorer?

Microsoft Graph Explorer supports the following HTTP actions/HTTP verbs as shown below. Remember you must be logged in for the dropdown to be enabled,

Office Development

“PUT” has been added now which did not exist in earlier version of MS Graph Explorer.

When to change the request type and how to execute the API calls is covered later.

“Run Query” button

Office Development

This one is obvious, but I thought my article would not be complete without mentioning each part of the MS Graph Explorer!

You press it to execute the call to the Graph API. If the API endpoint is not specified or some garbage value is entered, then it will simply ignore and will not execute anything. Cool!

“Share Query” link

Office Development

It’s the little link on the right side on top of response text area.

Office Development

Using this link, you can share your queries with others. It will allow others to execute the same query as you did in the MS Graph Explorer.

For the demo, click on the “my mail” link on left side,

Office Development

The API endpoint will be changed to https://graph.microsoft.com/v1.0/me/messages and the result will be shown to you.

Now click on the “Share Query” link,

Office Development

You will see the following pop-up,

Office Development

The textbox has following link inside it:

https://developer.microsoft.com/en-us/graph/graph-explorer?request=me/messages&method=GET&version=v1.0

It is formatted such that the link can be fired from any browser and the API call will be setup.

To test it, copy the link and click on “Close” to close the dialog.

Open another browser and paste the link in its address bar and press Enter,

Office Development

You will see that the API endpoint, HTTP request type and API version are set. You must press the “Run Query” button to execute the call.

What’s next

I will cover execution of some queries with sample account and Office 365 developer account in the next article.

Moreover, after reading this introduction to Microsoft Graph Explorer, I think you might be interested to know more about Microsoft Graph API.

Wait for my next article in this series, until it is published you can:

  • Read my article on Office365 developer program here.
  • Create an Office365 developer account here.
  • Learn more about Microsoft Graph API here.
  • Try Microsoft Graph Explorer here.
  • Learn more about Office 365 development here.

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

Header image courtesy: Microsoft