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
Comments
- Anonymous
January 01, 2003
Hi Duncan,
The best way to look at this API is that it lists the current incidents, and those incidents have a service category. If there are no incidents for your category, then that particular service category could be considered healthy.
I hope that makes sense. - Anonymous
January 01, 2003
Very useful article. Thank you. - Anonymous
January 01, 2003
Good Article. I installed Office 365 admin in my Windows mobile to check health status as and when required. - Anonymous
October 29, 2014
Thanks for this. Am I right in thinking that if there isn't a Service Incident or Maintenance Event within the past month for a particular service, then there will be no "AffectedServiceHealthStatus" field for that service? I'm trying to adapt your good work into a Python script that we can pull into Nagios - but I imagine that if Lync Online has no issues for a month then the "AffectedServiceHealthStatus" data for this Service will disappear until there is another incident?
Wouldn't it be good if there was a GetStatus task that could just give us the live status of each O365 service? - Anonymous
November 18, 2014
This didn't occur to me - thanks for your advice. - Anonymous
December 04, 2014
Hi,
What does Status value in AffectedServiceHealthStatus means and what are the possible value?
AffectedServiceHealthStatus : {@{InternalName=SharePoint; ServiceFeatureStatus=System.Object[]; ServiceName=SharePoint
Online; Status=2}}
I can not find any information about this in the API documentations.... - Anonymous
January 14, 2015
The comment has been removed - Anonymous
January 20, 2015
Anyone have a script to create an alert if the services are something other than No issue? - Anonymous
February 24, 2015
Hi,
Thanks for the article it was very useful.
I have tried to reuse the cookie, but for some reason after two days, it does not valid any more and need to run the registration again. Is it something I am missing? Have you tried to reuse the cookie?
Thanks,
Akos - Anonymous
April 14, 2015
Akos - I just get a new cookie every time. I run the registration and then the event/status pull as part of the same check (that runs every 5 minutes) - Anonymous
May 15, 2015
So this appears to have broken? I'm not getting any "Exchange Online" or "SharePoint Online" alerts in this feed anymore. They don't seem to have been renamed either..
Cheers - Anonymous
June 02, 2015
Akos - Every time you run a method, a new cookie is generated. That cookie is valid for another 48 hours. I suggest storing this cookie in a text file. So providing that you're running a method atleast once every 48 hours, and storing and re-using the last cookie, you won't need to re-authenticate. - Anonymous
June 02, 2015
Why dont Microsoft create more intuitive cmdlets for direct service status querying? - Anonymous
October 14, 2015
Looks like the goal posts have moved with this method.. I'm not getting accurate statuses for services through this endpoint anymore (compared with O365 dashboard). Are we now supposed to be using this?
https://msdn.microsoft.com/EN-US/library/office/dn707386.aspx - Anonymous
October 15, 2015
GET YOUR PROBLEM SOLVE TODAY WITH MY PROFESSION IN ANY SPIRITUAL SPELL OR ANY KIND OF PHYSICAL BATTLE THAT NEED, MY NAME IS DR SYLVESTER AND THIS IS MY EMAIL FOR CONTACT (stbenson391@gmail.com) OR YOU CAN FOLLOW HIM UP ON FACEBOOK BY MY NAME (SYLVESTER E BENSON) ON FACEBOOK OR CALL ME ON MY MOBILE NUMBER +2348136090988, AM ALWAYS AVAILABLE TO RENDER YOU HELP WITH EXPERIENCE OF 32 YEARS IN SPELL CASTING AND HERBAL MEDICURE TO CURE ANY KIND OF DISEASE THAT YOU MAY HAVE, CONTACT ME ON ANY KIND OF ISSUES. - Anonymous
October 18, 2015
Hi,
Can you please provide me with the steps after '$events.Events | get-member' to fetch the service heath status. - Anonymous
October 26, 2015
The comment has been removed - Anonymous
February 04, 2016
The comment has been removed - Anonymous
February 04, 2016
Thanks for your contribution - Anonymous
February 05, 2016
For those struggling look here for a working example. https://gist.github.com/alexinnes/0b6983c75e30ea7f5e99