In today’s Microsoft Graph Mailbag post we will cover features of Graph Explorer to help you be as effective as possible when querying Microsoft Graph. For those unfamiliar, Graph Explorer is a tool that lets you make requests and see responses against Microsoft Graph. The latest release has added many improvements to help you develop queries and explore requests and responses. Additionally, you can also see ways to leverage your queries in our Microsoft Graph SDKs, adaptive cards, or Microsoft Graph Toolkit components.
Please be sure to follow this blog series using https://aka.ms/MSGraphMailbag or with RSS using https://developer.microsoft.com/en-us/graph/blogs/feed/?tag=MSGraphMailbag.
Whatif query parameter
Microsoft Graph is an API gateway that calls underlying APIs when running a query. In general, you do not need to be concerned about the underlying API that is called, but at times it can be helpful for troubleshooting or understanding how your query is processed.
Recently a partner shared the following 2 queries:
- “/users/me/joinedTeams” returned a successful result
- “/users/me” returned an error
By adding the “$whatif” query parameter you can see that the first query is routed through the underlying Teams APIs while the second query is routed through Azure AD (Directory Services). As it turns out “/users/me” is an invalid query (“/me” is the appropriate request) and hence fails. On the other hand “/users/me/joinedTeams” is valid because the initial lookup for the user on the Teams endpoint does resolve. This isn’t readily apparent when first looking at the syntax but a quick check with $whatif helps see how the seemingly similar requests are processed differently.
Share a link to Graph Explorer query
After you run a query in Graph Explorer it is possible to share a link to the query, including any request body and headers. In the lower half response section of Graph Explorer click the Share button, then copy the link that is generated.
Try out this link for an example of a request that contains a request body and headers.
Access tokens
When you log into Graph Explorer, Graph Explorer will request an access token on your behalf which will then be used for any queries sent to Microsoft Graph. Click the Access token button below the request URI box to show this access token.
A recently added feature (PR 754) from Sébastien Levert (newest Microsoft Graph CPx team member) allows you to click the “{}” button to open this access token in the https://jwt.ms tool (provided by the Microsoft Identity team.) Note that decoding access tokens with this tool is only supported for work and school accounts (not consumer Microsoft accounts, also called MSAs). This is due to MSAs using a compact format for the access token.
The following screenshot shows a subset of claims decoded from the access token when using https://jwt.ms. Read more about Authentication and authorization basics for Microsoft Graph in our documentation.
Microsoft 365 Developer Program
When you first navigate to Graph Explorer you query a demo tenant. You can log into one of your own tenants but if you would like a sandbox tenant you can sign up for the Microsoft 365 Developer Program. One of the benefits is a free, renewable 90-day Microsoft 365 E5 developer subscription that includes 25 users.
Click the gear icon in the upper left authentication box then select “Get a sandbox with sample data”.
Permissions
If you do not have permissions required to run a given query you get the below error message (HTTP 403 Forbidden).
You can view and consent to a required permission(s) by clicking the “Modify permissions” tab under the request URL.
Separately, if you are logged in to Graph Explorer you can click the gear icon in the upper left authentication box then select “Select permissions”.
On the flyout menu to the right you can select and consent individual permissions. Use the search box to filter for specific permissions, select them, and then click the Consent button at bottom.
Conclusion
In today’s post we looked at ways to use many of the new features in Graph Explorer for access tokens, sharing queries, permissions, sandbox tenants, and more. If you have any feedback or suggested features for Graph Explorer please open an issue on the GitHub repo microsoftgraph/microsoft-graph-explorer-v4.
Today’s post was written by Brian T. Jackett, Sr. Customer and Partner Experience (CPx) PM with the Microsoft Graph Team. You can follow Brian on his blog or on Twitter @BrianTJackett. Join us for our next post Jan 12, 2021.
