PowerShell - Using Office 365 REST API to get Calendar Events
A couple of weeks ago I was looking at a way to find the Calendar Events of an Office365 shared mailbox using PowerShell. Unfortunately I was not able to find a way to accomplished this task using the O365 Cmdlets. (Let me know in the comments if you know how…)
Update 2016/04/19: Function updated to support PageResult
parameter
So I turned to the PowerShell Community and posted tweet about it.
Quickly I got an answer from @Mjolinor and @Glenscales who sent me some great stuff by using REST API. Thanks again guys!!
This is the example Glen sent me:
Invoke-RestMethod `
-Uri "https://outlook.office365.com/api/v1.0/users/[email protected]/calendarview?startDateTime=$(Get-Date)&endDateTime=$((Get-Date).AddDays(7))"`
-Credential (Get-Credential) |
foreach-object{ $_.Value }
This example shows how to list the calendar events for the next week. This is great and exactly what I needed, plus this run super fast compared to using the PowerShell module.
Of course you will need to have permissions on the specified mailbox.
Even though it show this as a CustomObject, the object type is Microsoft.OutlookServices.Event
, see this MSDN page to find all the properties and methods available: https://msdn.microsoft.com/office/office365/APi/complex-types-for-mail-contacts-calendar#EventResource
My obvious next step was to create a function to handle different mailbox with different parameters such as startdatetime
, enddatetime
or alternative credentials
. See at the end of this post.
But before we go there, let’s see how we can interact with Office 365 API.
How to interact with the Office 365 API
The MSDN documentation on how to use the Office365 API is very well done, clear and complete, you can take a look at it here: https://msdn.microsoft.com/en-us/office/office365/api/api-catalog
In our case, we are interested by the Outlook Calendar.
Using the Calendar API
In the Overview Page, you will find information on how to query this API.
All Calendar API requests use the following root URL: https://outlook.office365.com/api/{version}/{user_context}
{user_context}
is the current user, as Calendar API requests are always performed on behalf of the current user.
You can specify the user context in one of two ways:</b
- Current User: With the
me
shortcut:/api/v1.0/me
Invoke-RestMethod `
-Uri "https://outlook.office365.com/api/v1.0/me" `
-Credential $cred
- A Specific user: With the
users/{upn}
format to pass the UPN or a proxy address, such as:
Invoke-RestMethod `
-Uri "https://outlook.office365.com/api/v1.0/users/[email protected]" `
-Credential $cred
Get the Calendar Events
We can now retrieve the events using one the following:
- Against the primary calendar
../me/calendarview?startDateTime={ start_datetime }&endDateTime={ end_datetime }
Invoke-RestMethod `
-Uri "https://outlook.office365.com/api/v1.0/me/calendarview?startDateTime=$(Get-Date)&endDateTime=$((Get-Date).AddDays(7))" `
-Credential $cred |
ForEach-Object { $_.value } |
Select-Object -Property Subject
- Against a specific calendar
../me/calendars/{calendar_id}/calendarview?startDateTime={ start_datetime }&endDateTime={ end_datetime }
Invoke-RestMethod `
-Uri "https://outlook.office365.com/api/v1.0/me/calendars/$id/calendarview?startDateTime=$(Get-Date)&endDateTime=$((Get-Date).AddDays(7))" `
-Credential $cred |
ForEach-Object { $_.value } |
Select-Object -Property subject
Get the Calendars
The $ID
variable in the above example can be retrieve using /Calendars
This will list all the calendars present in the mailbox
Invoke-RestMethod `
-Uri "https://outlook.office365.com/api/v1.0/me/calendars" `
-Credential $cred |
ForEach-Object { $_.Value } |
Select-Object -Property Name, ID
PageResult
You can limit the number of item to output using the $top
query parameter. If not specified only 10 items will be returned. You can specify up to 50 items to be returned.
This was implemented in the function below using the -PageResult
parameter.
For more information about the other filters available see the following page:
https://msdn.microsoft.com/office/office365/APi/complex-types-for-mail-contacts-calendar#UseODataqueryparametersPageresults
Function Get-O365CalendarEvent
Finally, here is the function I built to query the calendar events. You can find it on my GitHub here: https://github.com/lazywinadmin/PowerShell/blob/master/O365-Get-O365CalendarEvent/O365-Get-O365CalendarEvent.ps1
Leave a comment