Merge pull request #2684 from KoenZomers/GetO365Status

Added cmdlets for Office 365 Management API

CHANGELOG.md

@@ -21,6 +21,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Added `Get-PnPIsSiteAliasAvailable` which allows checking if a certain alias is still available to create a new site collection with [PR #2698](https://github.com/pnp/PnP-PowerShell/pull/2698)
 - Added `Get-PnPFooter` and `Set-PnPFooter` to work with the footer shown on Modern Communication pages [PR #2634](https://github.com/pnp/PnP-PowerShell/pull/2634)
 - Added ability to getting and setting the title and logo shown in the footer of a Modern Communication site [PR #2715](https://github.com/pnp/PnP-PowerShell/pull/2715)
+- Added `Get-PnPOffice365CurrentServiceStatus`, `Get-PnPOffice365HistoricalServiceStatus`, `Get-PnPOffice365ServiceMessage` and `Get-PnPOffice365Services` to retrieve information from the Office 365 Management API regarding the Office 365 services [PR #2684](https://github.com/pnp/PnP-PowerShell/pull/2684)
 
 ### Changed
 - Fixed uploading a file using `Add-PnPFile` using `-ContentType` throwing an exception [PR #2619](https://github.com/pnp/PnP-PowerShell/pull/2619)

Commands/Enums/Office365Workload.cs

@@ -0,0 +1,30 @@
+namespace SharePointPnP.PowerShell.Commands.Enums
+{
+    /// <summary>
+    /// The types of workloads available within Office 365
+    /// </summary>
+    /// <remarks>Documented at https://docs.microsoft.com/en-us/office/office-365-management-api/office-365-service-communications-api-reference </remarks>
+    public enum Office365Workload : int
+    {
+        Bookings,
+        Exchange,
+        Forms,
+        kaizalamessagingservices,
+        Lync,
+        MicrosoftFlow,
+        MicrosoftFlowM365,
+        microsoftteams,
+        MobileDeviceManagement,
+        O365Client,
+        officeonline,
+        OneDriveForBusiness,
+        OrgLiveID,
+        OSDPPlatform,
+        OSub,
+        Planner,
+        PowerAppsM365,
+        PowerBIcom,
+        SharePoint,
+        SwayEnterprise
+    }
+}

Commands/ManagementApi/GetOffice365CurrentServiceStatus.cs

@@ -0,0 +1,42 @@
+#if !ONPREMISES
+using System.Collections.Generic;
+using System.Management.Automation;
+using Newtonsoft.Json.Linq;
+using OfficeDevPnP.Core.Framework.Graph;
+using SharePointPnP.PowerShell.CmdletHelpAttributes;
+using SharePointPnP.PowerShell.Commands.Base;
+using SharePointPnP.PowerShell.Commands.Model;
+
+namespace SharePointPnP.PowerShell.Commands.ManagementApi
+{
+    [Cmdlet(VerbsCommon.Get, "PnPOffice365CurrentServiceStatus")]
+    [CmdletHelp(
+        "Gets current service status of the Office 365 Services from the Office 365 Management API",
+        Category = CmdletHelpCategory.ManagementApi,
+        OutputTypeLink = "https://docs.microsoft.com/office/office-365-management-api/office-365-service-communications-api-reference#get-current-status",
+        SupportedPlatform = CmdletSupportedPlatform.Online)]
+    [CmdletExample(
+       Code = "PS:> Get-PnPOffice365CurrentServiceStatus",
+       Remarks = "Retrieves the current service status of all Office 365 services",
+       SortOrder = 1)]
+    [CmdletExample(
+       Code = "PS:> Get-PnPOffice365CurrentServiceStatus -Workload SharePoint",
+       Remarks = "Retrieves the current service status of SharePoint Online",
+       SortOrder = 2)]
+    [CmdletOfficeManagementApiPermission(OfficeManagementApiPermission.ServiceHealth_Read)]
+    public class GetOffice365CurrentServiceStatus : PnPOfficeManagementApiCmdlet
+    {
+        [Parameter(Mandatory = false, HelpMessage = "Allows retrieval of the current service status of only one particular service. If not provided, the current service status of all services will be returned.")]
+        public Enums.Office365Workload? Workload;
+
+        protected override void ExecuteCmdlet()
+        {
+            var response = GraphHttpClient.MakeGetRequestForString($"{ApiRootUrl}ServiceComms/CurrentStatus{(ParameterSpecified(nameof(Workload)) ? $"?$filter=Workload eq '{Workload.Value}'" : "")}", AccessToken);
+            var serviceStatusesJson = JObject.Parse(response);
+            var serviceStatuses = serviceStatusesJson["value"].ToObject<IEnumerable<ManagementApiServiceStatus>>();
+
+            WriteObject(serviceStatuses, true);
+        }
+    }
+}
+#endif

Commands/ManagementApi/GetOffice365HistoricalServiceStatus.cs

@@ -0,0 +1,42 @@
+#if !ONPREMISES
+using System.Collections.Generic;
+using System.Management.Automation;
+using Newtonsoft.Json.Linq;
+using OfficeDevPnP.Core.Framework.Graph;
+using SharePointPnP.PowerShell.CmdletHelpAttributes;
+using SharePointPnP.PowerShell.Commands.Base;
+using SharePointPnP.PowerShell.Commands.Model;
+
+namespace SharePointPnP.PowerShell.Commands.ManagementApi
+{
+    [Cmdlet(VerbsCommon.Get, "PnPOffice365HistoricalServiceStatus")]
+    [CmdletHelp(
+        "Gets the historical service status of the Office 365 Services of the last 7 days from the Office 365 Management API",
+        Category = CmdletHelpCategory.ManagementApi,
+        OutputTypeLink = "https://docs.microsoft.com/office/office-365-management-api/office-365-service-communications-api-reference#get-historical-status",
+        SupportedPlatform = CmdletSupportedPlatform.Online)]
+    [CmdletExample(
+       Code = "PS:> Get-PnPOffice365HistoricalServiceStatus",
+       Remarks = "Retrieves the historical service status of all Office 365 services",
+       SortOrder = 1)]
+    [CmdletExample(
+       Code = "PS:> Get-PnPOffice365HistoricalServiceStatus -Workload SharePoint",
+       Remarks = "Retrieves the historical service status of SharePoint Online",
+       SortOrder = 2)]
+    [CmdletOfficeManagementApiPermission(OfficeManagementApiPermission.ServiceHealth_Read)]
+    public class GetOffice365HistoricalServiceStatus : PnPOfficeManagementApiCmdlet
+    {
+        [Parameter(Mandatory = false, HelpMessage = "Allows retrieval of the historical service status of only one particular service. If not provided, the historical service status of all services will be returned.")]
+        public Enums.Office365Workload? Workload;
+
+        protected override void ExecuteCmdlet()
+        {
+            var response = GraphHttpClient.MakeGetRequestForString($"{ApiRootUrl}ServiceComms/HistoricalStatus{(ParameterSpecified(nameof(Workload)) ? $"?$filter=Workload eq '{Workload.Value}'" : "")}", AccessToken);
+            var serviceStatusesJson = JObject.Parse(response);
+            var serviceStatuses = serviceStatusesJson["value"].ToObject<IEnumerable<ManagementApiServiceStatus>>();
+
+            WriteObject(serviceStatuses, true);
+        }
+    }
+}
+#endif

Commands/ManagementApi/GetOffice365ServiceMessage.cs

@@ -0,0 +1,38 @@
+#if !ONPREMISES
+using System.Collections.Generic;
+using System.Management.Automation;
+using Newtonsoft.Json.Linq;
+using OfficeDevPnP.Core.Framework.Graph;
+using SharePointPnP.PowerShell.CmdletHelpAttributes;
+using SharePointPnP.PowerShell.Commands.Base;
+using SharePointPnP.PowerShell.Commands.Model;
+
+namespace SharePointPnP.PowerShell.Commands.ManagementApi
+{
+    [Cmdlet(VerbsCommon.Get, "PnPOffice365ServiceMessage")]
+    [CmdletHelp(
+        "Gets the service messages regarding services in Office 365 from the Office 365 Management API",
+        Category = CmdletHelpCategory.ManagementApi,
+        OutputTypeLink = "https://docs.microsoft.com/office/office-365-management-api/office-365-service-communications-api-reference#get-messages",
+        SupportedPlatform = CmdletSupportedPlatform.Online)]
+    [CmdletExample(
+       Code = "PS:> Get-PnPOffice365ServiceMessage",
+       Remarks = "Retrieves the service messages regarding services in Office 365",
+       SortOrder = 1)]
+    [CmdletOfficeManagementApiPermission(OfficeManagementApiPermission.ServiceHealth_Read)]
+    public class GetOffice365ServiceMessage : PnPOfficeManagementApiCmdlet
+    {
+        [Parameter(Mandatory = false, HelpMessage = "Allows retrieval of the service messages for only one particular service. If not provided, the service messages of all services will be returned.")]
+        public Enums.Office365Workload? Workload;
+
+        protected override void ExecuteCmdlet()
+        {
+            var response = GraphHttpClient.MakeGetRequestForString($"{ApiRootUrl}ServiceComms/Messages{(ParameterSpecified(nameof(Workload)) ? $"?$filter=Workload eq '{Workload.Value}'" : "")}", AccessToken);
+            var servicesJson = JObject.Parse(response);
+            var services = servicesJson["value"].ToObject<IEnumerable<ManagementApiServiceMessage>>();
+
+            WriteObject(services, true);
+        }
+    }
+}
+#endif

Commands/ManagementApi/GetOffice365Services.cs

@@ -0,0 +1,35 @@
+#if !ONPREMISES
+using System.Collections.Generic;
+using System.Management.Automation;
+using Newtonsoft.Json.Linq;
+using OfficeDevPnP.Core.Framework.Graph;
+using SharePointPnP.PowerShell.CmdletHelpAttributes;
+using SharePointPnP.PowerShell.Commands.Base;
+using SharePointPnP.PowerShell.Commands.Model;
+
+namespace SharePointPnP.PowerShell.Commands.ManagementApi
+{
+    [Cmdlet(VerbsCommon.Get, "PnPOffice365Services")]
+    [CmdletHelp(
+        "Gets the services available in Office 365 from the Office 365 Management API",
+        Category = CmdletHelpCategory.ManagementApi,
+        OutputTypeLink = "https://docs.microsoft.com/office/office-365-management-api/office-365-service-communications-api-reference#get-services",
+        SupportedPlatform = CmdletSupportedPlatform.Online)]
+    [CmdletExample(
+       Code = "PS:> Get-PnPOffice365Services",
+       Remarks = "Retrieves the current services available in Office 365",
+       SortOrder = 1)]
+    [CmdletOfficeManagementApiPermission(OfficeManagementApiPermission.ServiceHealth_Read)]
+    public class GetOffice365Services : PnPOfficeManagementApiCmdlet
+    {
+        protected override void ExecuteCmdlet()
+        {
+            var response = GraphHttpClient.MakeGetRequestForString($"{ApiRootUrl}ServiceComms/Services", AccessToken);
+            var servicesJson = JObject.Parse(response);
+            var services = servicesJson["value"].ToObject<IEnumerable<ManagementApiService>>();
+
+            WriteObject(services, true);
+        }
+    }
+}
+#endif

Commands/Model/ManagementApiFeature.cs

@@ -0,0 +1,16 @@
+using Newtonsoft.Json;
+
+namespace SharePointPnP.PowerShell.Commands.Model
+{
+    /// <summary>
+    /// Information regarding one Office 365 service feature
+    /// </summary>
+    public class ManagementApiFeature
+    {
+        [JsonProperty("Name")]
+        public string Name { get; set; }
+
+        [JsonProperty("DisplayName")]
+        public string DisplayName { get; set; }
+    }
+}

Commands/Model/ManagementApiFeatureStatus.cs

@@ -0,0 +1,22 @@
+using Newtonsoft.Json;
+
+namespace SharePointPnP.PowerShell.Commands.Model
+{
+    /// <summary>
+    /// Information regarding the current status of a specific feature in an Office 365 service
+    /// </summary>
+    public class ManagementApiFeatureStatus
+    {
+        [JsonProperty("FeatureDisplayName")]
+        public string FeatureDisplayName { get; set; }
+
+        [JsonProperty("FeatureName")]
+        public string FeatureName { get; set; }
+
+        [JsonProperty("FeatureServiceStatusDisplayName")]
+        public string FeatureServiceStatusDisplayName { get; set; }
+
+        [JsonProperty("FeatureServiceStatus")]
+        public string FeatureServiceStatus { get; set; }
+    }
+}

Commands/Model/ManagementApiService.cs

@@ -0,0 +1,20 @@
+using Newtonsoft.Json;
+using System.Collections.Generic;
+
+namespace SharePointPnP.PowerShell.Commands.Model
+{
+    /// <summary>
+    /// Information regarding one Office 365 service
+    /// </summary>
+    public class ManagementApiService
+    {
+        [JsonProperty("Id")]
+        public string Id { get; set; }
+
+        [JsonProperty("DisplayName")]
+        public string DisplayName { get; set; }
+
+        [JsonProperty("Features")]
+        public IEnumerable<ManagementApiFeature> Features { get; set; }
+    }
+}

Commands/Model/ManagementApiServiceMessage.cs

@@ -0,0 +1,123 @@
+using Newtonsoft.Json;
+using System;
+using System.Collections.Generic;
+
+namespace SharePointPnP.PowerShell.Commands.Model
+{
+    /// <summary>
+    /// Information regarding a message concerning a service in Office 365
+    /// </summary>
+    public class ManagementApiServiceMessage
+    {
+        [JsonProperty("Id")]
+        public string Id { get; set; }
+
+        [JsonProperty("ActionType")]
+        public string ActionType { get; set; }
+
+        [JsonProperty("ActionDetails")]
+        public string ActionDetails { get; set; }
+
+        [JsonProperty("AffectedTenantCount")]
+        public int? AffectedTenantCount { get; set; }
+
+        [JsonProperty("AffectedUserCount")]
+        public int? AffectedUserCount { get; set; }
+
+        [JsonProperty("AffectedWorkloadDisplayNames")]
+        public IEnumerable<string> AffectedWorkloadDisplayNames { get; set; }
+
+        [JsonProperty("AffectedWorkloadNames")]
+        public IEnumerable<string> AffectedWorkloadNames { get; set; }
+
+        [JsonProperty("AnnouncementId")]
+        public string AnnouncementId { get; set; }
+
+        [JsonProperty("AppliesTo")]
+        public string AppliesTo { get; set; }
+
+        [JsonProperty("BlogLink")]
+        public string BlogLink { get; set; }
+
+        [JsonProperty("Category")]
+        public string Category { get; set; }
+
+        [JsonProperty("Classification")]
+        public string Classification { get; set; }
+
+        [JsonProperty("EndTime")]
+        public DateTime? EndTime { get; set; }
+
+        [JsonProperty("ExternalLink")]
+        public string ExternalLink { get; set; }
+
+        [JsonProperty("FeatureDisplayName")]
+        public string FeatureDisplayName { get; set; }
+
+        [JsonProperty("Feature")]
+        public string Feature { get; set; }
+
+        [JsonProperty("FlightName")]
+        public string FlightName { get; set; }
+
+        [JsonProperty("HelpLink")]
+        public string HelpLink { get; set; }
+
+        [JsonProperty("ImpactDescription")]
+        public string ImpactDescription { get; set; }
+
+        [JsonProperty("IsDismissed")]
+        public bool? IsDismissed { get; set; }
+
+        [JsonProperty("IsMajorChange")]
+        public bool? IsMajorChange { get; set; }
+
+        [JsonProperty("IsRead")]
+        public bool? IsRead { get; set; }
+
+        [JsonProperty("LastUpdatedTime")]
+        public DateTime? LastUpdatedTime { get; set; }
+
+        [JsonProperty("Messages")]
+        public IEnumerable<ManagementApiServiceMessageText> Messages { get; set; }
+
+        [JsonProperty("MessageTagNames")]
+        public IEnumerable<string> MessageTagNames { get; set; }
+
+        [JsonProperty("MessageType")]
+        public string MessageType { get; set; }
+
+        [JsonProperty("Milestone")]
+        public string Milestone { get; set; }
+
+        [JsonProperty("MilestoneDate")]
+        public DateTime? MilestoneDate { get; set; }
+
+        [JsonProperty("PostIncidentDocumentUrl")]
+        public string PostIncidentDocumentUrl { get; set; }
+
+        [JsonProperty("PreviewDuration")]
+        public string PreviewDuration { get; set; }
+
+        [JsonProperty("Severity")]
+        public string Severity { get; set; }
+
+        [JsonProperty("StartTime")]
+        public DateTime? StartTime { get; set; }
+
+        [JsonProperty("Status")]
+        public string Status { get; set; }
+
+        [JsonProperty("Title")]
+        public string Title { get; set; }
+
+        [JsonProperty("UserFunctionalImpact")]
+        public string UserFunctionalImpact { get; set; }
+
+        [JsonProperty("Workload")]
+        public string Workload { get; set; }
+
+        [JsonProperty("WorkloadDisplayName")]
+        public string WorkloadDisplayName { get; set; }
+    }
+}