Office 365 Service Communications API PowerShell Script

Office 365 Service Communications API PowerShell Script

  •  
  •  
  •  
  •  
  •  
  •  

In light of some recent events, I thought I’d build on another project I have going on and drop this quick script here for talking to the Office 365 Service Communications API.

Background

The Office 365 Service Communications API is a REST-based interface to retrieve data from the service.  You can read more about access it here: https://docs.microsoft.com/en-us/office/office-365-management-api/office-365-service-communications-api-reference.

Prerequisites

So, in order to achieve a result for customer with a project a few months ago, I started tinkering with the idea of being able to retrieve statuses via Invoke-WebRequest in PowerShell. In order to do this, you’ll need to create an app registration and grant it the appropriate permissions.

The App ID and Client Secret parts might be a little foreign to some people, so we’ll go through those steps here.  It’s going to involve three parts:

  • Creating an App registration
  • Creating a client secret
  • Setting permissions

Creating an app registration

  1. Log into the Azure Portal (https://portal.azure.com) and search for Azure Active Directory.  Or, if you’re already there from the last prerequisite step, don’t do anything.
  2. Under Manage, select App registrations.
    Office 365 Service Communications API PowerShell Script
  3. Click + New registration.
    Office 365 Service Communications API PowerShell Script
  4. Configure the app:
    – Enter a name for the application.
    – Ensure the Accounts in this organizational directory only (first) radio button is selected.
    – Under Redirect URI, select Web in the drop-down and enter http://localhost in the text box.
    Office 365 Service Communications API PowerShell Script
  5. Click Register.
  6. Click the copy link next to Application (client) ID.  Copy the value and paste it in your scratch pad (be sure to identify that it’s the client ID).
    Office 365 Service Communications API PowerShell Script

Next, we’ll create the secret.

Creating a client secret

  1. Under Manage, select Certificates & secrets.
  2. Click + New client secret.
    Office 365 Service Communications API PowerShell Script
  3. Enter a description for this particular client secret and select an expiration date.
    Office 365 Service Communications API PowerShell Script
  4. Click Add.
  5. Copy the value for the newly created client secret.  Once you navigate from this page, you won’t be able to see the value anymore and will have to start over at step 8.
    Office 365 Service Communications API PowerShell Script

Next up–permissions!

Configuring permissions

Now that you have an app id and a client secret, you need to grant the app id permissions to see certain data inside the tenant.  For the purposes of this Flow, you need to be able to read content from the Message Center.

  1. Under the Manage section of the app registration, select API permissions.
    Office 365 Service Communications API PowerShell Script
  2. Click + Add a permission.
    Office 365 Service Communications API PowerShell Script
  3. Select the Office 365 Management APIs tile.
    Office 365 Service Communications API PowerShell Script
  4. Select the Delegated permissions box select Add permissions at the bottom (you can deselect the ActivityFeed.ReadDlp and ActivityFeed.Read if you’d like, since we’re not really going to be using it for this explicit purpose).
    Office 365 Service Communications API PowerShell Script
  5. Click Add permissions.
  6. Repeat steps 2-5, selecting Application permissions.
    Office 365 Service Communications API PowerShell Script
  7. Select Grant admin consent for <tenant>.
    Office 365 Service Communications API PowerShell Script
  8. Click Yes to confirm granting consent.
    Office 365 Service Communications API PowerShell Script

Now, with the app registration done and permissions set, you can use the script!

The Script

The best place to get the script is from the PowerShell Gallery (https://www.powershellgallery.com/packages/Get-Office365ServiceAPIStatus/).

It supports all four service endpoint types defined by the API (Services, CurrentStatus, HistoricalStatus, Messages).  The default is CurrentStatus, but you can use any of them.  Here are some examples:

CurrentStatus

Current status returns the workload display name, status display name, the time the status was updated.

Office 365 Service Communications API PowerShell Script

Services

The Services parameter returns all of the services you have subscribed to in your tenant.

Office 365 Service Communications API PowerShell Script

HistoricalStatus

This parameter can be used to return the the historical statuses for the past 7 days for each service.

Office 365 Service Communications API PowerShell Script

Messages

The Messages parameter returns the last n message center postings with basic information including the title, affected workload, time/date, severity, and message type.

Office 365 Service Communications API PowerShell Script

Final Notes

Just wanted to reiterate this–when using the ClientID parameter, be sure to use the client ID of your App Registration.  ClientSecret is the value that gets hidden after you create the specific client ID/client secret entry.  Since the ClientSecret is only ever displayed when you create it, you’ll want to store it in a safe place so you can use it when you need to.  You could, alternatively, update the script parameters directly with those values (but I wouldn’t necessarily recommend that).

It’s obviously a rough script, but it gives you some ideas of what you might be able to achieve.

Published by Aaron Guilmette

Helping companies conquer inferior technology since 1997. I spend my time developing and implementing technology solutions so people can spend less time with technology. Specialties: Active Directory and Exchange consulting and deployment, Virtualization, Disaster Recovery, Office 365, datacenter migration/consolidation, cheese.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.