Using PowerShell to obtain your Tenants Office365 Health Dashboard

Obtaining the Office 365 Health Status via script has become a lot easier now with the release of the Office 365 Service Communications API. An overview of the Office 365 Service Communications API and the methods can be found on MSDN at the following URL: https://msdn.microsoft.com/en-us/library/office/dn776043(v=office.15).aspx

Because the API is a standard JSON based web api we can leverage in-built functionality in PowerShell 4.0 to convert our request to/from JSON and invoke the API. The PowerShell commands i'll be using in this blog article are the ConvertTo-JSON (for converting our request to JSON format) and the Invoke-RestMethod (for invoking the API itself).

First off, we need to obtain our credentials which we will use for the initial registration.

$cred = get-credential

We now need to obtain our authentication cookie by calling the Register method with our Office 365 username and password. The Register method will return a cookie which can be used to authenticate subsequent requests for up to 2 days. Each additional method will return an updated Cookie, which extends the life of the cookie for another 48 hours.

The Service URL as per the MSDN documentation is "https://api.admin.microsoftonline.com/shdtenantcommunications.svc/". The Method that we are calling to obtain the cookie is the Register method.. To call this method, we add the method name to the URL, so that it is "https://api.admin.microsoftonline.com/shdtenantcommunications.svc/Register". We then invoke the web request with our username and password in JSON format. The method will return several properties, one of which is our RegistrationCookie. We need to store this cookie for future API requests.

$jsonPayload = (@{userName=$cred.username;password=$cred.GetNetworkCredential().password;} | convertto-json).tostring()

$cookie = (invoke-restmethod -contenttype "application/json" -method Post -uri "https://api.admin.microsoftonline.com/shdtenantcommunications.svc/Register" -body $jsonPayload).RegistrationCookie

The cookie above can be stored as an alternative in storing your username & password credentials. You can use the cookie to authenticate to the API for future requests without having to call the Register method again. The cookie is only valid for 48-hours, but a new cookie is provided every time a method is ran on the API, theoretically making it possible never to have to use the actual Office 365 credentials more than once.

Now comes the fun part, we can call any of the methods with our cookie and obtain information from the dashboard. For this example, i'm going to use the GetEvents method to show all current Office 365 events. This method has a preferredEventTypes parameter which allows us to select which type of events to return. In this example, i'm going to use both the event types 0 and 1, which are for Service Incidents and Maintenance Events.

$jsonPayload = (@{lastCookie=$cookie;locale="en-US";preferredEventTypes=@(0,1)} | convertto-json).tostring()
$events = (invoke-restmethod -contenttype "application/json" -method Post -uri "https://api.admin.microsoftonline.com/shdtenantcommunications.svc/GetEvents" -body $jsonPayload)

Now, let's inspect what's returned..

The "LastCookie" is updated with a fresh new cookie which we can use for future authentication requests. It is valid for another 2 days. This is what we can use for theoretically never having to re-run the Register method as this cookie can be used for future authentication.

The "Events"  is a property array of the events returned, lets inspect:

Here we have the main request. In here we have entries for the start and end time of the event, messages, and status and title of the event. The "AffectedServiceHealthStatus" is another property, which includes the effected service name for the event. Below is an example of one of the events returned:

As you can see, polling the API is relatively easy to achieve with in-built commands for web API's in PowerShell 4.0. For full documentation on the Service API, visit MSDN: https://msdn.microsoft.com/en-us/library/office/dn776043(v=office.15).aspx