top of page
  • Writer's pictureFrank

Getting Started with MS Graph, Step-by-Step (Part 3) - Simple API Request Examples

In Part 1 and Part 2 of this series you learned how to connect to MS Graph using PowerShell and we concluded with your first query into Azure AD. In this part you will learn techniques to make your MS Graph interactions significantly more effective.




Let’s start with the Graph Explorer. Graph Explorer is a free tool provided by Microsoft. It is totally free to use and your best friend when developing Graph automation.


The first thing you need to do is sign in to the Azure AD tenant you want to work with. This is located in the top right corner.



Once signed in take a look at the Method drop down, Version drop down, and Uniform Resource Identifier (URI) box.


The Method determines the action you want to do. The options are:

Method

Description

GET

Read data from a resource.

POST

Create a new resource, or perform an action.

PATCH

Update a resource with new values.

PUT

Replace a resource with a new one.

DELETE

Remove a resource.


In PowerShell this is reflected in the Invoke-RestMethod command


$Response = Invoke-RestMethod -Uri $URI -Headers $authHeader -Method Get

The Version dropdown reflects production V1.0 and beta (preview). Picking the version here automatically changes the URI.



The difference between v1.0 and beta is essentially that beta has exposed new properties that aren’t yet available in production.


In many cases these new fields are very useful so you will need to decide which endpoint best meets your requirements. There is a risk to use the beta endpoint as changes may occur without notice. In my experience the beta endpoint is reliable enough to justify its use if the data isn’t available in v1.0.


Example 1: Getting Information about Yourself


The URI box is where you put string that tells MS Graph what you are looking for. The default string is https://graph.microsoft.com/v1.0/me


This queries information about you. Press the Run Query button to see it work.


In PowerShell this query would look like this:


$URI = https://graph.microsoft.com/v1.0/me
$Response = Invoke-RestMethod -Uri $URI -Headers $authHeader -Method Get
$Response

NOTE: Don’t forget to construct the $authheader which you learned in Part 2 of this series.



Example 2: Getting Information about Other Users in your Directory


Now lets try something more interesting. Change the URI in Graph Explorer to https://graph.microsoft.com/v1.0/users and press Run Query


A list of users in Azure AD should be returned. Let’s try that in PowerShell:


$URI = https://graph.microsoft.com/v1.0/users
$Response = Invoke-RestMethod -Uri $URI -Headers $authHeader -Method Get
$Response.value

NOTE: We have to query the value property of the response since an array is returned with multiple users. We can see how many by typing:

$Response.value.count

IMPORTANT GOTCHA

If your environment has more than 100 users, did you notice the response only contains 100 records?


The reason?


Pagination

which is the breakup of a record set into discrete pages of data.


Most REST API endpoints that return a list of entities will need to have some sort of pagination. Without it, a simple search could return millions or even billions of hits causing extraneous network traffic. In the case of the MS Graph API the default value is 100 records. This can be modified but I generally see no reason to do so.


For more information regarding paging in MS Graph see Paging Microsoft Graph data in your app.


Let’s try a query against the SiFr Demo tenant which has 3535 users to demonstrate this concept.

$Response = Invoke-RestMethod -Uri $URI -Headers $authHeader -Method Get
$Response.value.count

How do you deal with this limitation? Fortunately, Microsoft makes things easy by including the URL of the next page with each response.

$Response.'@odata.nextLink'

This means all you need to do is a simple loop to collect all the pages. This example code will loop until there are no more pages. Make sure you transfer each page of data to a separate variable. I used $Users.

$URI = https://graph.microsoft.com/v1.0/users
Do{
  $Response = Invoke-RestMethod -Uri $URI -Headers $authHeader -Method Get
  $URI = $Response.'@odata.nextLink'
  $Users += $Response.value
} While ($Response.'@odata.nextLink')

In essence what has happened is the response is broken into 36 separate pages of data with a new query required for each subsequent page.


Now switch back to the Graph Explorer. On the left are several useful tabs including “Sample queries”. This can be helpful when learning as numerous queries are provided to test and practice with. Spend some time playing with the samples.


Try to transpose the samples to your PowerShell code as practice.


Another important tab is the “Modify permissions” tab. If you don’t have sufficient permission to execute the request you’ve sent this will help you sort it out. This can help with determining the Scope for you PowerShell automation as well.



Further Reading


Last, but certainly not the least, the MS Graph documentation is very good so you should definitely bookmark this for the future. Microsoft Graph overview - Microsoft Graph | Microsoft Docs In particular, you'll likely refer to the “API v1.0 reference” and “API beta reference” all the time when developing MS Graph automation.


In Part 4 of this series, I will show you more advanced requests that include filters and request specific properties. In addition, I will cover creating and modifying objects as well as sending an email via MS Graph.

 

Hope you've found this post helpful. If you did, please share it with your admin friends so they can benefit too! Sharing is caring.


Be sure to subscribe, or follow us on our social channels to be notified when the next part is published.


If you need some additional support on automation, we're very good at this stuff. So contact us to see if we can help support your business goals.

 

The content on this web site is provided for general information purposes only and does not constitute professional advice. Users of this web site are advised to seek specific technical advice by contacting SiFr or their own IT resource regarding any specific technical issues. SiFr does not warrant or guarantee the quality, accuracy or completeness of any information on this web site. The articles published on this web site are current as of their original date of publication, but should not be relied upon as accurate, timely or fit for any particular purpose.


This web site may contain links to third party web sites. Links are provided for convenience only and SiFr does not endorse the information contained in linked web sites nor guarantee its accuracy, timeliness or fitness for a particular purpose.


SiFr is a Microsoft Partner.

Comments


bottom of page