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

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

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

Recently, Microsoft has launched the new and updated version of Microsoft Graph Explorer. The concept behind the Microsoft Graph API and the Microsoft Graph Explorer remain the same, but this launch is an effort by the Microsoft Graph team to make developer experience more engaging and to add more functionality to Microsoft Graph Explorer.

I have already written an article on the previous version of Microsoft Graph Explorer here while it was in effect. But with the launch of a new version with new UI, things have changed in Microsoft Graph Explorer. So, I wanted to write an article on it which will guide you through the new version. This article is part 1 of the multipart series I plan to write on the new Microsoft Graph Explorer.

Please note that this article is written in a way that it can be read as an independent article without the need to look at my earlier article.

Remember, there is no way to access the old version of Microsoft Graph Explorer. It has been totally replaced by the current version. My first impression is that you are going to like it much more than the old version.

Before we start with what’s new in Microsoft Graph Explorer, let’s first get a quick introduction of Microsoft Graph.

Microsoft Graph

The official Microsoft documentation defines Microsoft Graph as,

“Microsoft Graph exposes multiple APIs from Office 365 and other Microsoft cloud services through a single endpoint: https://graph.microsoft.com. Microsoft Graph simplifies queries that would otherwise be more complex.”

So, in a nutshell, Microsoft Graph gives you a single REST API endpoint which you can call to interact with “almost anything” in Office365. It delegates calls to different Office 365 cloud services via one single endpoint.

Now, let’s learn about Microsoft Graph Explorer.

Microsoft Graph Explorer

Microsoft Graph Explorer is a fantastic tool if you want to work with Microsoft Graph APIs or if you are learning to develop with Graph APIs. Consider it as a developer sandbox or a playground where a developer can have first-hand experience of Microsoft Graph APIs.

Where can you access Microsoft Graph Explorer?

It can be accessed here – https://developer.microsoft.com/en-us/graph/graph-explorer

Microsoft Graph Explorer

What do you need in order to work with Microsoft Graph Explorer?

Microsoft Graph Explorer provides you default login – a sample account with which you can fire some GET calls using Microsoft Graph APIs.

But if you want to explore more and also want to fire POST, PATCH and DELETE calls to Microsoft Graph API, then you will need to login with Microsoft credentials. I will suggest you get an Office 365 developer account.

Warning

A word of caution here; never play with your live Office 365 data or work account here with Microsoft Graph APIs. You may accidentally update or delete some important information. It is advisable to use a test/demo account.

If you join the Microsoft Office 365 developer program here, Microsoft will give you one year free Office 365 developer subscription for non-commercial use with 5 users. You can read more on it in my related article “Office 365 developer program” here.

What can you do with Microsoft Graph Explorer?

A lot!

Microsoft Graph Explorer gives you a test client to access whatever you can access with Microsoft Graph REST APIs.

Using Microsoft Graph Explorer, you can:

  • Access/Modify data from Office 365 and other cloud services like SharePoint online, OneDrive, etc.
  • Navigate different Office 365 entities and traverse the relationships amongst them
  • Get intelligence and insights from the Microsoft cloud (limited to commercial users only)

In short, with Microsoft Graph Explorer is a one stop shop for everything you want to play with in Graph APIs.

Why should you use Microsoft Graph Explorer?

Microsoft Graph Explorer is a great tool to test how Microsoft Graph APIs work. A developer can use Microsoft Graph Explorer to:

  • Test Graph API calling logic beforehand dealing with any endpoint
  • See what data Graph API gives you back
  • See how the POST, PATCH and DELETE calls work
  • See how an entity in Office 365 can be accessed, using which relationship path

A first look at the new Microsoft Graph Explorer

Microsoft Graph Explorer

The screen shot of the new Microsoft Graph Explorer with some annotations above is mostly self-explanatory.

Some sections are covered in more detail below. I will also cover sections on left side in black background which were not mentioned in above screen shot due to space crunch:

The “Authentication” section

Microsoft Graph Explorer

By default, it launches API calls with the in-built sample account which you can use it to get some data without login in. You can sign-in to your account using the sign in button,

Microsoft Graph Explorer

Please note one thing here. If you go to the “Request Type” drop-down, you will see,

Microsoft Graph Explorer

You are not allowed to change the request type if you are not logged in with your Microsoft account. This is because someone can fire update/delete calls to Microsoft Graph API and change the data in Microsoft sample account. So, for the sanity anything except a “GET” is disabled till your login.

Once your login with your Microsoft credentials is done, then you can fire more queries apart from “GET” request type.

There is one more use of this sample account I have found. It has bulk data for messages and other items. Your newly created Office 365 developer account may not have that much data until you do the laborious task of creating it into your account. So when you want to test paging, delta queries, etc. this sample account comes into help.

The “Sample Queries” section

Microsoft Graph Explorer

In the left side section, just below authentication you will see the “Sample Queries” section,

Microsoft Graph Explorer

Here you will find some frequently used API calls labelled under “Getting Started”.

The purpose of the sample queries section is to provide developers a ready-made API call which can be immediately executed in the Microsoft Graph Explorer without the need for the developer to go and find the API URL and input parameters in documentation.

You can directly click on any link in the “Sample Queries” section and that call will be fired immediately against the Graph API and result will be shown to you.

For example, let’s click on “my photo” link in the Sample Queries” section, you will see on the right-side section, the API call for getting user’s photo is executed and you are shown the result:

Microsoft Graph Explorer

The Graph Explorer automatically changes the API endpoint to https://graph.microsoft.com/v1.0/me/photo/$value, fires the query and shows you user’s photo.

Note the 3 different columns in the “Sample Queries” section for each row

  • Request Type
  • Brief name of API call
  • Link to documentation

Microsoft Graph Explorer

The first column
indicates the type of API call, which is “GET” here.

The second column indicates a brief name for the API call.

e.g. if you move the cursor over the “my profile” text you will see the tooltip,

Microsoft Graph Explorer

The tooltip/hint here indicates the actual API endpoint “https://graph.microsoft.com/v1.0/me“ which will be used in the call and which will be seen later in the API address bar once the call is fired,

Microsoft Graph Explorer

The third column is the link to the relevant Graph API documentation section. If you move mouse over to it, you will see tooltip for documentation,

Microsoft Graph Explorer

If you click on that link, the documentation will load in the new tab,

Microsoft Graph Explorer

Do you want to see some more sample queries?

Click on the “show more samples” link at the bottom of “Sample Queries” section,

Microsoft Graph Explorer

Microsoft Graph Explorer

A “Sample Categories” popup will open with some category/group names and options for each to make the selection ON or OFF,

Microsoft Graph Explorer

Notice that you were already seeing the “Getting Started” section, and here the section’s selection is “On”,

Microsoft Graph Explorer

The (6) at the end of “Getting Started” indicates there are 6 queries/endpoints in this section. This can be verified if you close the pop-up and once again go back to “Sample Queries” section,

Microsoft Graph Explorer

Now back to the “Sample Categories” popup. Let’s now select some more categories and see what happens. I have selected three more categories – Users, Outlook mail and OneDrive,

Microsoft Graph Explorer

Click on the “X” button on top right section to close the pop-up. See the “Sample Categories” section, you will have the selected categories in it,

Microsoft Graph Explorer

You can click on any call to get it fired and see result in Microsoft Graph Explorer.

Notice one thing here that if you are not yet logged in and using the sample account, then you cannot fire the “POST” calls,

Microsoft Graph Explorer

Once again click the “show more samples” link, and make all categories selection “off” and close the pop-up,

Microsoft Graph Explorer

You will see now there are no more  sample queries,

Microsoft Graph Explorer

This flow is just to show you how you can make category selection “on” or “off”. I will suggest you to check all the categories and all its queries once at least.

That’s it for part 1. I will cover more in part 2 of this series.

See you in the next article. Until then – Happy Learning!

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

Header image courtesy: Microsoft

Introduction To MS Graph Explorer

In this article, I will explain what is MS Graph Explorer and how can a developer use it.

Note: Microsoft has launched a new version of MS Graph Explorer some time after this article was published. For newer version of my article on the new MS Graph Explorer, please visit here.

In this article, I will explain you what is MS Graph Explorer and what you can do with it.

First, let’s start with a quick introduction of MS Graph.

What is MS Graph?

The official MS documentation defines MS Graph as,

“Microsoft Graph exposes multiple APIs from Office 365 and other Microsoft cloud services through a single endpoint, https://graph.microsoft.com. Microsoft Graph simplifies queries that would otherwise be more complex.”

So, in a nutshell, MS Graph gives you a single REST API endpoint which you can call to interact with “almost anything” in Office365. It delegates calls to different Office 365 cloud services via one single endpoint.

Now, let’s learn about MS Graph Explorer.

What MS Graph Explorer is

MS Graph Explorer is a fantastic tool if you want to work with MS Graph APIs or if you are learning to develop with Graph APIs. Consider it as a developer sandbox or a playground where a developer can have firsthand experience of MS Graph APIs.

What you need to work with MS Graph Explorer

MS Graph Explorer provides you default login – a demo tenant with which you can fire some GET calls using MS Graph APIs. But, if you want to explore more and want to also fire POST, PATCH and DELETE calls to MS Graph API, then you will need an Office365 account.

Warning

A word of caution here; never play with your live Office365 data or work account here with MS Graph APIs. You may accidentally update or delete some important information. It is advisable to use a test/demo account.

If you join the MS Office 365 developer program here, Microsoft will give you one year free Office 365 developer subscription for non-commercial use with 5 users. You can read more about it in my related article “Office 365 developer program”.

What you can do with MS Graph Explorer

A lot!

MS Graph Explorer gives you a test client to access whatever you can access with MS Graph REST APIs. Using MS Graph Explorer, you can,

  • Access/Modify data from Office 365 and other cloud services like SharePoint online, OneDrive, etc.
  • Navigate different Office 365 entities and traverse the relationships among them
  • Get intelligence and insights from the Microsoft cloud (limited to commercial users only)

In short, MS Graph Explorer is a one stop shop for everything you want to play with, in Graph APIs.

Why you should use MS Graph Explorer

MS Graph Explorer is a great tool to test how MS Graph APIs work. A developer can use MS Graph Explorer to:

  • Test Graph API calling logic beforehand dealing with any endpoint.
  • See what data Graph API gives you back.
  • See how the POST, PATCH and DELETE calls work.
  • See how an entity in Office 365 can be accessed, using which relationship path.

The first look of MS Graph Explorer

MS Graph

The screenshot of MS Graph Explorer with some annotations above is mostly self-explanatory. API version and Request type selections are covered in below sections. I would like to cover some parts which were not mentioned above.

The “History” button

MS Graph

It maintains the history of the API calls you made to the Graph API, and clicking on the history, you can easily go back to that call. Remember, as you make the Graph API calls, the browser URL does not change, so to get back to any of your previous calls, you need to click this button.

When you click on the “History” button, you will see a section as shown below. You can click on any URL request and it will be re-played.

MS Graph

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

The HTTP request headers can be specified in the “Request Header” area. Once you click on the “REQUEST HEADER” link, a text area will appear below it,

MS Graph

Similarly, the HTTP Request body can be specified in the area which appears once you click on the “REQUEST BODY” link as shown below. But remember you need to be logged in to enable the link, if you are using demo tenant then the link will be disabled,
MS Graph

Also, in the case of “POST” and “PATCH” verbs selection only, the request body link will be enabled, otherwise it will be disabled. Once you click on the enabled “REQUEST BODY” link, then a text area below it will appear,

MS Graph

Now, go to the service endpoint address bar and type the following URL:

 https://graph.microsoft.com/v1.0/organization/users

You will see the MS Graph Explorer that will show you a link “INSERT USERS TEMPLATE”.

MS Graph

When you click on the “INSERT USERS TEMPLATE” link, MS Graph Explorer will insert JSON for creating a user.

MS Graph

Do you see now how much MS Graph Explorer makes it easier for you to play with the API calls?

You can change some data from the default text and then hit the “GO” button for the user to be created in your organization’s Office 365 account. Remember to use a test/demo account and not the live account.

If you really pressed the “GO” button, then the Graph Explorer will show you the result in the “RESPONSE” section.

How to fire actual API calls is covered in the section “Let’s try it out” below.

API versions supported by MS Graph Explorer

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

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

MS Graph

HTTP request types/verbs/actions that are supported in MS Graph Explorer

MS Graph Explorer supports the following HTTP actions/HTTP verbs.

MS Graph

Let’s try it out

Below, I will explain how some calls to MS Graph API can be made using the Graph Explorer.

Calls with demo tenant

The following calls can be executed using the demo tenant.

Also notice, as you type in the address bar, the Graph Explorer will show you the possible endpoints (just like intelliSense).

MS Graph

Click on the “GO” button and you will see the result in the “RESPONSE” area.

MS Graph

  • Now, type https://graph.microsoft.com/v1.0/organization in the address bar and press “GO” button. You will see the logged in user’s organization info.MS Graph
  • The following call will return the files stored in user’s OneDrive account.MS Graph

Try some more “GET” calls on your own using the Graph Explorer. The list of more such calls can be found here.

MS Graph

Calls with your Office 365 account

The following calls will require you to login with an Office 365 account. Remember to use demo/test account and not the live account, because it may result in some live data loss.

Click on the “SIGN IN” link and login with your Office 365 test account.

Click on the “INSERT USERS TEMPLATE” link inside “REQUEST BODY” area. Once MS Graph Explorer populates some default JSON data, change it as you like and click on the “GO” button.

MS Graph

Hopefully, a new user will be created in Office 365 and Graph API will respond with HTTP Status Code 201, meaning user is created.

MS Graph

Note the id of the user which can be used in subsequent calls to edit/delete the record.

  • Let’s now try to update the user’s value e.g. surname. Let’s update the value from current “Darrow” in above screenshot to “Sharp”.
  • Copy the JSON value from the response area (i.e. values inside and including the curly brackets).
  • Remove everything else but surname field, change the surname value to “Sharp”.
  • Change the request type to “PATCH”.
  • Change the API endpoint to include the above created user
  • Click on the “GO” button.MS Graph

Graph API will process the request and update the user’s last name to “Sharp”. It will respond with the HTTP Status Code 204.

Change the request type to “GET” and fire the same call again, you will see the last name is changed to “Sharp” now.

MS Graph

  • Now, let’s fire a delete call and delete the above generated user. Use caution here not to delete any of your live users!

Change the request type to “DELETE”, keep the API endpoint same as last call and click on “GO”

MS Graph

You will see that Graph API responds with HTTP Status Code 204 again. The user is deleted from Office 365.

You can make sure the user is deleted by firing a GET on all users,

MS Graph

Check the response JSON, above user will not be in the response.

What’s next

After reading this introduction to MS Graph Explorer, I think you must be interested to know more about MS Graph API. Wait for my next article on MS Graph API, and until it is published you can go to internet and,

  • Create an Office365 developer account here.
  • Learn more about MS Graph API here.
  • Try MS Graph Explorer here.
  • Learn more about Office 365 development here.

See you in the next article, until then – Happy Learning!

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

Image courtesy: Microsoft