Skip to main content

A walk-though using the Graph API Mailbox reports in Powershell

Quite recently the Reporting side of the Graph API has moved in GA from beta, there are quite a number of reports that can be run across various Office365 surfaces but in this post I'm going to focus on the Mailbox related ones.

Accessing Office365 Reports using Powershell is nothing new and has been available in the previous reporting endpoint https://msdn.microsoft.com/en-us/library/office/jj984326.aspx however from the end of January many of these cmdlets are now being depreciated in favour of the Graph API https://msdn.microsoft.com/en-us/library/office/dn387059.aspx .

Prerequisites 

 In comparison to using the Remote PowerShell cmdlets where only the correct Office365 Admin permissions where needed, to use the new Graph API reports endpoint you need to use OAuth for authentication so this requires an Application Registration https://developer.microsoft.com/en-us/graph/docs/concepts/auth_overview  that is then given the correct oAuth Grants to use the Reports EndPoint. Only one particular grant is need for this eg



This is a big advantage over the previous Web Service along with the benefits of using Token based authentication and different App usage scenarios it limits access to just what is needed to read reports which help limit the security risks associated.

Accessing the Reporting Endpoint

 To access and Run the reports you will need code that first Authenticates and generates an oAuth Token based on your App registration. My Exch-Rest module can be used for this (Connect-EXRMailbox will imitate the token Authentication) or there are other scripts people have posted that can also do this https://gallery.technet.microsoft.com/Get-Office365-usage-f955ade4 .

Inputs and Outputs

 Compared to the  Remote PowerShell cmdlets the richness of Input parameters for the reports at GA is limited (even when compared to the beta which was more a little rich). For most of the Mailbox Reports the only input parameter is the Period best explained in the documentation
"Specifies the length of time over which the report is aggregated. The supported values for {period_value} are: D7, D30, D90, and D180. These values follow the format Dn where n represents the number of days over which the report is aggregated" ref https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/api/reportroot_getmailboxusagedetail
So if your trying to feature match your current scripts against the new Graph API you may need to look at restructuring or rethinking your process a little, at the end of the day the data is same but you may need to post process it more at the client side.

On the Output side a CSV is generated by the Graph API and returned to the user, currently because the endpoint doesn't yet support the Filter Query parameter if you want to perform any filtering you will need to do it post process once the CSV is downloaded. (I would expect that in future updates the other QueryStrings will be supported which will improve the flexibility for those working with very larger result sets in Larger tenants.

The Actual Reports 

Given the refresh time of the Graph API it mostly likely this list is already out of date by the time you read this. All the screenshots are from the reporting Cmdlets in lastest version of my Exch-Rest Module which you can get from the PowerShell gallery https://www.powershellgallery.com/packages/Exch-Rest  to use the cmdlets you need to first authenticate using Connect-ExrMailbox with an app registration that has been granted the "Read Usage Report" permission.


GetMailboxUsageDetails https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/api/reportroot_getmailboxusagedetail

This report returns mailbox usage information or in plane English how big your Mailbox is and what the Quotas are. eg

 The Remote PowerShell cmdlet Get-MailboxUsageDetailReport returned the same information with a few extra fields but these fields are retrievable via other Graph endpoints

Eg MailboxPlan is returned via the users endpoint eg https://graph.microsoft.com/v1.0/users('user@mailbox.com')/assignedLicenses if needed etc. Other information that is missing like percentage used can be calculated from other values in the data provided.

(What's missing which was also absent in the Office 365 Reporting Web Service is the ability to report on the size of the Archive Mailbox. I hope this feature will appear in the future as its a critical data point to track for people using Archives).

 getMailboxUsageMailboxCounts https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/api/reportroot_getmailboxusagemailboxcounts

This report gives you daily tracking numbers of Active Mailbox use in your org eg



getMailboxUsageQuotaStatusMailboxCounts https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/api/reportroot_getmailboxusagequotastatusmailboxcounts

This report returns information about the Mailbox size status to the quotas that are configured, you want to use this in conjunction with GetMailboxUsageDetails which will allow you to pinpoint the actual mailboxs this summary reports are referring to.


getMailboxUsageStorage https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/api/reportroot_getmailboxusagestorage

This report returns the aggregated storage usage across the tenant (?? does it include archives ??)



This report is one of the more useful report as it gives you Message activity of a particular user eg the following is the last 30 days of my usage


This is also one of the reports that takes a parameter other then the Period eg you can enter a particular date value for the date you want to report activity on. eg tracking over a period of time


getEmailActivityUserCounts https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/api/reportroot_getemailactivityUserCounts

This reports give you the Activity counts of you users doing particular activities (my tenant is kind of a lonely one)


getEmailAppUsageUserDetail https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/api/reportroot_getemailappusageuserdetail

This gives you details of the Client application use



This gives you summary information on App usages 



This gives summary information on Client App version usage



Labels:

Popular posts from this blog

The MailboxConcurrency limit and using Batching in the Microsoft Graph API

If your getting an error such as Application is over its MailboxConcurrency limit while using the Microsoft Graph API this post may help you understand why. Background   The Mailbox  concurrency limit when your using the Graph API is 4 as per https://docs.microsoft.com/en-us/graph/throttling#outlook-service-limits . This is evaluated for each app ID and mailbox combination so this means you can have different apps running under the same credentials and the poor behavior of one won't cause the other to be throttled. If you compared that to EWS you could have up to 27 concurrent connections but they are shared across all apps on a first come first served basis. Batching Batching in the Graph API is a way of combining multiple requests into a single HTTP request. Batching in the Exchange Mail API's EWS and MAPI has been around for a long time and its common, for email Apps to process large numbers of smaller items for a variety of reasons.  Batching in the Gr...
Read more

Exporting and Uploading Mailbox Items using Exchange Web Services using the new ExportItems and UploadItems operations in Exchange 2010 SP1

Two new EWS Operations ExportItems and UploadItems where introduced in Exchange 2010 SP1 that allowed you to do a number of useful things that where previously not possible using Exchange Web Services. Any object that Exchange stores is basically a collection of properties for example a message object is a collection of Message properties, Recipient properties and Attachment properties with a few meta properties that describe the underlying storage thrown in. Normally when using EWS you can access these properties in a number of a ways eg one example is using the strongly type objects such as emailmessage that presents the underlying properties in an intuitive way that's easy to use. Another way is using Extended Properties to access the underlying properties directly. However previously in EWS there was no method to access every property of a message hence there is no way to export or import an item and maintain full fidelity of every property on that item (you could export the...
Read more

EWS Create Mailbox folder Powershell module for Exchange and Office365 Mailboxes

This is a rollup post for a couple of scripts I've posted in the past for creating folders using EWS in an Exchange OnPremise or Exchange online Cloud mailbox. It can do the following Create a Folder in the Root of the Mailbox Create-Folder -Mailboxname mailbox@domain.com -NewFolderName test Create a Folder as a SubFolder of the Inbox Create-Folder -Mailboxname mailbox@domain.com -NewFolderName test -ParentFolder '\Inbox' Create a Folder as a SubFolder of the Inbox using EWS Impersonation Create-Folder -Mailboxname mailbox@domain.com -NewFolderName test -ParentFolder '\Inbox' -useImpersonation Create a new Contacts Folder as a SubFolder of the Mailboxes Contacts Folder Create-Folder -Mailboxname mailbox@domain.com -NewFolderName test -ParentFolder '\Contacts' -FolderClass IPF.Contact Create a new Calendar Folder as a SubFolder of the Mailboxes Calendar Folder Create-Folder -Mailboxname mailbox@domain.com -NewFolderName test -Parent...
Read more
All sample scripts and source code is provided by for illustrative purposes only. All examples are untested in different environments and therefore, I cannot guarantee or imply reliability, serviceability, or function of these programs.

All code contained herein is provided to you "AS IS" without any warranties of any kind. The implied warranties of non-infringement, merchantability and fitness for a particular purpose are expressly disclaimed.