Most of you that are familiar with PowerShell are likely aware of the -WhatIf parameter and its usefulness. Or might have at least heard about it, as unfortunately we’ve seen many examples where “official” Microsoft-released modules do not take advantage of said parameter or outright ignore it. If you are one of those unlucky few that never touched a proper cmdlet, the TL;DR description is: the -WhatIf parameter allows you to “preview” the results of executing a given cmdlet, without actually making the changes.
Luckily, it seems like at least some folks within Microsoft continue to appreciate its usefulness and have now brought a (somewhat) similar functionality within the Graph API. Available in both /v1.0 and /beta endpoints, the $whatIf operator allows you to get some insight on what exactly your query will do. Here’s an example:
Of course, GET requests are not that interesting and in most scenarios you will likely want to preview the changes that will be made by a PATCH/POST request. For example, changing the country attribute for a given user can be previewed as follows:
Unlike PowerShell, it looks like invoking the $whatIf operator doesn’t perform an actual validation of the query parameters, which is of course unfortunate. For example, if you enter an invalid value for the country query above, you will still get the exact same result when using the $whatIf operator. Whereas if you remove the $whatIf operator and try to run the erroneous query, you will of course be greeted with an error message. Hopefully, going forward Microsoft will improve on that.
Which of course is not to say the $whatIf operator is without value. It can be used to get some additional insights into your queries, expose the internal logic used by the Graph API, give you a peek behind the curtains. This is best illustrated with more complex queries, such as those fetching a set of objects or using additional operators. For example, the query below, used to fetch a list of all users, their managers, licenses and sign in activity info, will return the following when invoked with the $whatIf opereator:
You will note that two separate requests are being made, against two different endpoints. Interestingly enough, the need for the second requests does not stem from the use of the $expand operator (in order to fetch manager’s details). Instead, the signInActivity parameter is stripped from the original request, its values gathered via a separate request made to the reporting endpoint and the results are later merged together. This is not something you would have guessed by simply looking at the original query, at least not without having some additional insight.
Lastly, you can of course also use the $whatIf operator outside of the Graph explorer tool. Here’s the same query as invoked via PowerShell. Do remember to escape your strings correctly when using special characters such as $!
$uri = 'https://graph.microsoft.com/beta/users?$select=displayName,userPrincipalName,signInActivity,userType,assignedLicenses&$expand=manager($select=displayName,userPrincipalName)&$whatif'
$Gr = Invoke-WebRequest -Headers $AuthHeader1 -Uri $uri -Verbose -Debug
$result = ($gr.Content | ConvertFrom-Json)
$result | fl
Description : Foreach entity obtained from Request1, run Request2 and merge responses:
Request1 : @{Description=Execute HTTP request; Uri=https://graph.windows.net/v2/923712ba-352a-4eda-bece-09d0684d0cfb/users?$select=displayName,userPrincipalName,userType,assignedLicenses,id&$expand=manager($select=displayName,userPrincipalName); HttpMethod=GET; TargetWorkloadId=Microsoft.DirectoryServices}
Request2 : @{Description=Execute HTTP request; Uri=https://reportingservice.activedirectory.windowsazure.com/auditLogs/userSignInActivity/Default.GetByIds?$select=signInActivity,id; HttpMethod=GET; TargetWorkloadId=Microsoft.AAD.Reporting}
And that’s all I can think of on the use of the $whatIf operator, do let me know if you come up with some creative use for it 🙂