{"id":6468,"date":"2021-06-08T07:38:58","date_gmt":"2021-06-08T15:38:58","guid":{"rendered":"https:\/\/officedevblogs.wpengine.com\/?p=6468"},"modified":"2021-06-08T07:38:58","modified_gmt":"2021-06-08T15:38:58","slug":"microsoft-graph-mailbag-a-deeper-look-into-the-microsoft-graph-powershell-sdk","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/microsoft-graph-mailbag-a-deeper-look-into-the-microsoft-graph-powershell-sdk\/","title":{"rendered":"Microsoft Graph Mailbag \u2013 A deeper look into the Microsoft Graph PowerShell SDK"},"content":{"rendered":"

In today\u2019s Microsoft Graph Mailbag post,\u00a0we\u2019ll\u00a0continue our dive into the Microsoft Graph PowerShell SDK.<\/span>\u00a0<\/span><\/p>\n

Please be sure to follow this blog series using\u202f<\/span>https:\/\/aka.ms\/MSGraphMailbag<\/span><\/a>\u202for with RSS using\u202f<\/span>https:\/\/developer.microsoft.com\/graph\/blogs\/feed\/?tag=MSGraphMailbag<\/span><\/a>.<\/span><\/p>\n

Introduction<\/span>\u00a0<\/span><\/h4>\n

In\u00a0my\u00a0<\/span>last post<\/span><\/a>, we started\u00a0to look\u00a0at the\u00a0Microsoft Graph PowerShell SDK<\/a>\u00a0and\u00a0<\/span>using it to<\/span>\u00a0interact\u00a0with Microsoft Graph using some\u00a0simple examples.\u00a0In this post we\u2019ll familiarize ourselves with\u00a0navigating\u00a0the SDK and\u00a0<\/span>using\u00a0<\/span>core\u00a0Microsoft Graph\u00a0functionality.<\/span><\/p>\n

Navigation<\/span>\u00a0<\/span><\/h4>\n

The Microsoft Graph API surface is very large with thousands of endpoints. \u00a0Hence, the PowerShell SDK contains thousands of cmdlets (or commandlets) split between dozens of modules. Because of this, it can be difficult to identify the correct cmdlet needed to perform a specific query.<\/span>\u00a0<\/span><\/p>\n

We can use the PowerShell\u00a0Get-Command cmdlet\u00a0<\/span>to\u00a0<\/span>search against the\u00a0PowerShell SDK\u00a0<\/span>to\u00a0<\/span>get a list of available commands. Additionally, we can search for specific words to help narrow our search. For example, we may want to look up all calendar events for a specific user. We can search for all commands that include the word\u00a0<\/span>\u201ccalendar\u201d<\/span>\u00a0from the\u00a0PowerShell SDK:<\/span>\u00a0<\/span><\/p>\n

Get-Command -Module Microsoft.Graph* *calendar*<\/pre>\n
\"Get-Command<\/p>\n
This\u00a0limits\u00a0the number of commands\u00a0we need to review\u00a0from thousands to\u00a0a more manageable number, making it easier\u00a0to find the applicable cmdlet.<\/span>\u00a0<\/span><\/p>\n
For those not familiar, PowerShell\u00a0cmdlets\u00a0use a format of\u00a0‘verb-[optionalPrefix]noun’. The Microsoft Graph PowerShell API has followed this naming convention as well, mapping the http request methods to the verb portion of the PowerShell command. A GET method maps to\u00a0a\u00a0‘Get’\u00a0PowerShell command. POST and PUT methods map to\u00a0a\u00a0‘New’\u00a0or \u2018Add\u2019\u00a0PowerShell command. The PATCH method maps to\u00a0an\u00a0‘Update’\u00a0or \u2018Set\u2019\u00a0command. And the DELETE method maps to\u00a0a\u00a0‘Remove’ command.<\/span>\u00a0<\/span><\/p>\n
We can use Get-Command to further filter results\u00a0by verb and \/ or noun.\u00a0\u00a0Wildcards can be used with an asterisk (*).<\/span>\u00a0<\/span><\/p>\n
Get-Command -Module Microsoft.Graph -Verb \u201cGet\u201d<\/pre>\n
Get-Command -Module Microsoft.Graph -Noun \u201cDrive*\u201d<\/pre>\n
Once\u00a0we’ve\u00a0found the correct command, we can use the PowerShell Get-Help cmdlet to see what parameters are available to perform the desired request.<\/span>\u00a0<\/span><\/p>\n
Get-Help Get-MgUserCalendarEvent -Detailed<\/pre>\n
\"Get-Help<\/p>\n
With the help\u00a0of the\u00a0<\/span>Microsoft Graph\u00a0API documentation<\/span><\/a>\u00a0and a tool like\u00a0<\/span>Graph Explorer<\/span><\/a>\u00a0or\u00a0<\/span>Postman<\/span><\/a>,\u00a0we can use this information to determine the correct command\u00a0and syntax\u00a0to use\u00a0within our script.<\/span>\u00a0<\/span><\/p>\n
Now that we are familiar with navigating the SDK, let\u2019s look at using the SDK for some of the core features available with Microsoft Graph.<\/span><\/p>\n
Query\u00a0Parameters<\/span>\u00a0<\/span><\/h4>\n
A powerful feature of the Microsoft Graph API is the ability to use OData system query\u00a0parameters\u00a0to control the data that is returned. In a RESTful request, these are built as\u00a0part of the URI that is submitted. The\u00a0\u00a0PowerShell SDK makes these query options available through\u00a0command parameters like\u00a0-Filter\u00a0or -Search. For example, if we want\u00a0to return\u00a0a message based on an email\u00a0message\u00a0ID,\u00a0we can run the following command<\/span>\u00a0which makes use of\u00a0the\u00a0-Filter parameter (similar to\u00a0the $filter query parameter)<\/span>:<\/span>\u00a0<\/span><\/p>\n
Get-MgUserMessage -UserId meganb@contoso.onmicrosoft.com -Filter \"InternetMessageId eq '<860c02d9-abd8-4943-9116-e64745cc6840@az.southcentralus.production.microsoft.com>'\"<\/pre>\n
\"Example<\/p>\n
Now<\/span>,<\/span>\u00a0instead of returning all messages in a mailbox,\u00a0we\u00a0return<\/span>\u00a0only messages that\u00a0match the filter (in this case<\/span>\u00a0one specific message<\/span>)<\/span>.\u00a0Scoping\u00a0our request\u00a0to a specific need and making it\u00a0more efficient at the same time.<\/span><\/p>\n
Paging<\/span>\u00a0<\/span><\/h4>\n
For anyone who has submitted a Microsoft Graph API request, you are likely familiar with\u00a0<\/span>paging<\/span>. Some queries return a great deal of information\u00a0so\u00a0the data is returned using multiple\u00a0pages.Or,\u00a0perhaps\u00a0you’ve\u00a0used the $top query parameter to specify the number of results returned\u00a0causing\u00a0manual\u00a0paging\u00a0of\u00a0the results.\u00a0Either way,\u00a0to ensure we get\u00a0all\u00a0the data from our query, we need to make sure we process\u00a0all\u00a0the\u00a0returned\u00a0pages.<\/span>\u00a0<\/span><\/p>\n
Typically, we\u00a0would\u00a0look for an @odata.nextlink\u00a0property in the response and follow the contained URL to view the next page of results.\u00a0And if\u00a0we\u00a0are building a RESTful query,\u00a0we\u00a0would need to build that\u00a0logic\u00a0into our script.<\/span>\u00a0<\/span><\/p>\n
With the\u00a0\u00a0PowerShell SDK, however, paging\u00a0is\u00a0much simpler to deal with. Just like with the RESTful request, we can specify the $top query by using the -Top parameter. We can use -Top with\u00a0the\u00a0-Skip parameter to\u00a0build logic for\u00a0manually paging\u00a0results. Additionally, there is a -PageSize\u00a0parameter\u00a0that\u00a0controls the number of results returned per page.<\/span>\u00a0<\/span><\/p>\n
The real power, in my opinion, is the -All parameter. This allows queries made with the\u00a0\u00a0PowerShell SDK to automatically process paging and return all the results of the query\u00a0with no need to build logic around the @odata.nextlink\u00a0property\u00a0creating a simpler scripting experience.<\/span><\/p>\n
Throttling<\/span>\u00a0<\/span><\/h4>\n
Like most\u00a0cloud-based\u00a0services, there are safeguards put in place to protect the services and Microsoft Graph is no exception. Throttling protects the service by limiting the number of requests that can be performed\u00a0within a specific timeframe \/ concurrently \/\u00a0etc.<\/span>\u00a0<\/span><\/p>\n
Microsoft Graph documentation shows\u00a0<\/span>service specific limits<\/span><\/a>\u00a0and\u00a0as well as\u00a0<\/span>best practices to handle throttling<\/span><\/a>.\u00a0When throttling occurs,\u00a0Microsoft\u00a0Graph\u00a0sends\u00a0HTTP status code 429 (Too many requests)\u00a0in\u00a0the\u00a0response.\u00a0Many service APIs also provide a Retry-After response header that provides a wait time to be used for delaying\u00a0our\u00a0requests.\u00a0Luckily, the Microsoft\u00a0Graph PowerShell SDK\u00a0implements\u00a0retry logic\u00a0for us. It will automatically handle\u00a0429 status code\u00a0responses\u00a0as well as the Retry-After response header, saving us the need to manually process those responses\u00a0and adjust requests.<\/span><\/p>\n
Manual Requests<\/span>\u00a0<\/span><\/h4>\n
Despite the\u00a0coverage of the Microsoft Graph PowerShell SDK, there may be instances where we need to send a specific Microsoft Graph request that is not covered by the SDK. \u00a0In this case, we still\u00a0have the ability to\u00a0perform a RESTful web request using the SDK. The Invoke-MgGraphRequest\u00a0cmdlet\u00a0(similar to\u00a0Invoke-RestMethod\u00a0command), provides us the ability to specify a URI,\u00a0Method,\u00a0Headers,\u00a0and Body\u00a0to submit a request.\u00a0Since it\u00a0is an SDK cmdlet, we\u00a0can\u00a0utilize\u00a0the\u00a0authentication,\u00a0access token\u00a0management, and more.<\/span>\u00a0<\/span><\/p>\n
An example of where this functionality might be useful is performing a batch request. Currently, there is no batch\u00a0command\u00a0within the SDK, but with Invoke-MgGraphRequest, we can utilize that functionality\u00a0if we desire.\u00a0By building an\u00a0HTTP\u00a0request and submitting it via Invoke-MgGraphRequest, we\u00a0are able to\u00a0perform a batch request:<\/span>\u00a0<\/span><\/p>\n
Invoke-MgGraphRequest -Method POST -Uri \u201chttps:\/\/graph.microsoft.com\/v1.0\/$batch\u201d -Body $body | ConvertTo-Json)<\/pre>\n
In this case we are submitting a\u00a0POST\u00a0request\u00a0for a batch process\u00a0and\u00a0passing in\u00a0the\u00a0JSON\u00a0formatted\u00a0batch commands\u00a0to the body of the request.\u00a0This gives us the Microsoft Graph API batching\u00a0functionality through the PowerShell SDK.<\/span><\/p>\n
Conclusion<\/span>\u00a0<\/span><\/h4>\n
In this post, we took a step further into the Microsoft Graph PowerShell SDK\u00a0including\u00a0finding\u00a0the correct\u00a0cmdlet,\u00a0using query parameters,\u00a0paging results, handling throttling, and issuing manual requests.\u00a0With this we\u00a0can begin to utilize\u00a0the Microsoft Graph PowerShell SDK<\/a>\u00a0in our scripts and applications. Until next time!<\/span>\u00a0<\/span><\/p>\n
Today\u2019s post was written by\u00a0<\/span>Matt Krause, Customer Engineer (CE) at Microsoft.\u202fYou can follow Matt on\u202f<\/span>Twitter @mattckrause<\/span><\/a>. Join us for our next post\u00a0on June 22, 2021.<\/span>\u00a0<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"
Learn how to navigate the Microsoft Graph Powershell SDK and how to use the SDK for some of the core features available with Microsoft Graph.<\/p>\n","protected":false},"author":69075,"featured_media":25159,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[3],"tags":[15,149,17],"class_list":["post-6468","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-microsoft-graph","tag-graph-explorer","tag-microsoft-graph-powershell-sdk","tag-msgraphmailbag"],"acf":[],"blog_post_summary":"
Learn how to navigate the Microsoft Graph Powershell SDK and how to use the SDK for some of the core features available with Microsoft Graph.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/6468","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/users\/69075"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/comments?post=6468"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/6468\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/25159"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=6468"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=6468"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=6468"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}