Merge pull request #2673 from KoenZomers/GraphSubscriptions

Added *-PnPGraphSubscription commands
pnp · Jun 6, 2020 · f19948e · f19948e
2 parents fd7912f + 2ef08f9
commit f19948e
Show file tree

Hide file tree

Showing 7 changed files with 214 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -32,11 +32,13 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 ## [3.21.2005.0]
 
 ### Added
+- Added `Add-PnPGraphSubscription`, `Get-PnPGraphSubscription`, `Remove-PnPGraphSubscription` and `Set-PnPGraphSubscription` to work with Microsoft Graph Subscriptions [PR #2673](https://github.com/SharePoint/PnP-PowerShell/pull/2673)
 
 ### Changed
 - Invoke-PnPSearchQuery: Allow SelectProperties to take a comma separated string as well as an array
 
 ### Contributors
+- Koen Zomers [koenzomers]
 
 
 ## [3.20.2004.0]

diff --git a/Commands/Base/PipeBinds/GraphSubscriptionPipeBind.cs b/Commands/Base/PipeBinds/GraphSubscriptionPipeBind.cs
@@ -0,0 +1,36 @@
+using OfficeDevPnP.Core.Framework.Graph.Model;
+using System;
+
+namespace SharePointPnP.PowerShell.Commands.Base.PipeBinds
+{
+    public class GraphSubscriptionPipeBind
+    {
+        private readonly Subscription _subscription;
+        private readonly String _subscriptionId;
+
+        public GraphSubscriptionPipeBind()
+        {
+        }
+
+        public GraphSubscriptionPipeBind(Subscription subscription)
+        {
+            _subscription = subscription;
+        }
+
+        public GraphSubscriptionPipeBind(String input)
+        {
+            if (Guid.TryParse(input, out Guid idValue))
+            {
+                _subscriptionId = input;
+            }
+            else
+            {
+                throw new ArgumentException("Idenity must be a GUID", nameof(input));
+            }
+        }
+
+        public Subscription Subscription => (_subscription);
+
+        public String SubscriptionId => _subscriptionId ?? _subscription?.Id;
+    }
+}
diff --git a/Commands/Graph/GetGraphSubscription.cs b/Commands/Graph/GetGraphSubscription.cs
@@ -0,0 +1,44 @@
+#if !ONPREMISES
+using SharePointPnP.PowerShell.CmdletHelpAttributes;
+using SharePointPnP.PowerShell.Commands.Base;
+using System.Collections.Generic;
+using System.Management.Automation;
+
+namespace SharePointPnP.PowerShell.Commands.Graph
+{
+    [Cmdlet(VerbsCommon.Get, "PnPGraphSubscription", DefaultParameterSetName = ParameterSet_LIST)]
+    [CmdletHelp("Gets subscriptions from Microsoft Graph. Requires the Azure Active Directory application permission 'Subscription.Read.All'.",
+        Category = CmdletHelpCategory.Graph,
+        SupportedPlatform = CmdletSupportedPlatform.Online)]
+    [CmdletExample(
+       Code = "PS:> Get-PnPGraphSubscription",
+       Remarks = "Retrieves all subscriptions from Microsoft Graph",
+       SortOrder = 1)]
+    [CmdletExample(
+       Code = "PS:> Get-PnPGraphSubscription -Identity 328c7693-5524-44ac-a946-73e02d6b0f98",
+       Remarks = "Retrieves the subscription from Microsoft Graph with the id 328c7693-5524-44ac-a946-73e02d6b0f98",
+       SortOrder = 2)]
+    public class GetGraphSubscription : PnPGraphCmdlet
+    {
+        const string ParameterSet_BYID = "Return by specific ID";
+        const string ParameterSet_LIST = "Return a list";
+
+        [Parameter(Mandatory = false, ParameterSetName = ParameterSet_BYID, HelpMessage = "Returns the subscription with the provided subscription id")]
+        public string Identity;
+
+        protected override void ExecuteCmdlet()
+        {
+            if (ParameterSpecified(nameof(Identity)))
+            {
+                OfficeDevPnP.Core.Framework.Graph.Model.Subscription subscription = OfficeDevPnP.Core.Framework.Graph.SubscriptionsUtility.GetSubscription(AccessToken, System.Guid.Parse(Identity));
+                WriteObject(subscription);
+            }
+            else
+            {
+                List<OfficeDevPnP.Core.Framework.Graph.Model.Subscription> subscriptions = OfficeDevPnP.Core.Framework.Graph.SubscriptionsUtility.ListSubscriptions(AccessToken);
+                WriteObject(subscriptions, true);
+            }
+        }
+    }
+}
+#endif
diff --git a/Commands/Graph/NewGraphSubscription.cs b/Commands/Graph/NewGraphSubscription.cs
@@ -0,0 +1,59 @@
+#if !ONPREMISES
+using OfficeDevPnP.Core.Framework.Graph;
+using SharePointPnP.PowerShell.CmdletHelpAttributes;
+using SharePointPnP.PowerShell.Commands.Base;
+using System;
+using System.Management.Automation;
+
+namespace SharePointPnP.PowerShell.Commands.Graph
+{
+    [Cmdlet(VerbsCommon.New, "PnPGraphSubscription")]
+    [CmdletHelp("Creates a new Microsof Graph Subscription which allows your webhook API to be called when a change occurs in Microsoft Graph",
+        DetailedDescription = "Creates a new Microsof Graph Subscription. The required Azure Active Directory application permission depends on the resource creating the subscription for, see https://docs.microsoft.com/graph/api/subscription-post-subscriptions#permissions. For a sample ASP.NET WebApi webhook implementation to receive the notifications from Microsoft Graph, see https://github.com/microsoftgraph/msgraph-training-changenotifications/blob/b8d21ca7aa5feeece336287c9a781e71b7ba01c6/demos/01-create-application/Controllers/NotificationsController.cs#L51.",
+        Category = CmdletHelpCategory.Graph,
+        OutputTypeLink = "https://docs.microsoft.com/graph/api/subscription-post-subscriptions",
+        SupportedPlatform = CmdletSupportedPlatform.Online)]
+    [CmdletExample(
+       Code = "PS:> New-PnPGraphSubscription -ChangeType Create -NotificationUrl https://mywebapiservice/notifications -Resource \"me/mailFolders('Inbox')/messages\" -ExpirationDateTime (Get-Date).AddDays(1) -ClientState [Guid]::NewGuid().ToString()",
+       Remarks = "Creates a new Microsoft Graph subscription listening for incoming mail during the next 24 hours in the inbox of the user under which the connection has been made and will signal the URL provided through NotificationUrl when a message comes in",
+       SortOrder = 1)]
+    [CmdletExample(
+       Code = "PS:> New-PnPGraphSubscription -ChangeType Updates -NotificationUrl https://mywebapiservice/notifications -Resource \"Users\" -ExpirationDateTime (Get-Date).AddHours(1) -ClientState [Guid]::NewGuid().ToString()",
+       Remarks = "Creates a new Microsoft Graph subscription listening for changes to user objects during the next hour and will signal the URL provided through NotificationUrl when a change has been made",
+       SortOrder = 2)]
+    public class NewGraphSubscription : PnPGraphCmdlet
+    {
+        [Parameter(Mandatory = true, HelpMessage = "The event(s) the subscription should trigger on")]
+        public OfficeDevPnP.Core.Enums.GraphSubscriptionChangeType ChangeType;
+
+        [Parameter(Mandatory = true, HelpMessage = "The URL that should be called when an event matching this subscription occurs")]
+        public String NotificationUrl;
+
+        [Parameter(Mandatory = true, HelpMessage = "The resource to monitor for changes. See https://docs.microsoft.com/graph/api/subscription-post-subscriptions#resources-examples for the list with supported options.")]
+        public String Resource;
+
+        [Parameter(Mandatory = false, HelpMessage = "The datetime defining how long this subscription should stay alive before which it needs to get extended to stay alive. See https://docs.microsoft.com/graph/api/resources/subscription#maximum-length-of-subscription-per-resource-type for the supported maximum lifetime of the subscriber endpoints.")]
+        public DateTime ExpirationDateTime;
+
+        [Parameter(Mandatory = false, HelpMessage = "Specifies the value of the clientState property sent by the service in each notification. The maximum length is 128 characters. The client can check that the notification came from the service by comparing the value of the clientState property sent with the subscription with the value of the clientState property received with each notification.")]
+        public String ClientState;
+
+        [Parameter(Mandatory = false, HelpMessage = "Specifies the latest version of Transport Layer Security (TLS) that the notification endpoint, specified by NotificationUrl, supports. If not provided, TLS 1.2 will be assumed.")]
+        public OfficeDevPnP.Core.Enums.GraphSubscriptionTlsVersion LatestSupportedTlsVersion = OfficeDevPnP.Core.Enums.GraphSubscriptionTlsVersion.v1_2;
+
+        protected override void ExecuteCmdlet()
+        {
+            var subscription = SubscriptionsUtility.CreateSubscription(
+                changeType: ChangeType,
+                notificationUrl: NotificationUrl,
+                resource: Resource,
+                expirationDateTime: ExpirationDateTime,
+                clientState: ClientState,
+                accessToken: AccessToken,
+                latestSupportedTlsVersion: ParameterSpecified(nameof(LatestSupportedTlsVersion)) ? LatestSupportedTlsVersion : default);
+
+            WriteObject(subscription);
+        }
+    }
+}
+#endif
diff --git a/Commands/Graph/RemoveGraphSubscription.cs b/Commands/Graph/RemoveGraphSubscription.cs
@@ -0,0 +1,33 @@
+#if !ONPREMISES
+using OfficeDevPnP.Core.Framework.Graph;
+using SharePointPnP.PowerShell.CmdletHelpAttributes;
+using SharePointPnP.PowerShell.Commands.Base;
+using SharePointPnP.PowerShell.Commands.Base.PipeBinds;
+using System.Management.Automation;
+
+namespace SharePointPnP.PowerShell.Commands.Graph
+{
+    [Cmdlet(VerbsCommon.Remove, "PnPGraphSubscription")]
+    [CmdletHelp("Removes an existing Microsoft Graph subscription. Required Azure Active Directory application permission depends on the resource the subscription exists on, see https://docs.microsoft.com/graph/api/subscription-delete#permissions.",
+        Category = CmdletHelpCategory.Graph,
+        OutputTypeLink = "https://docs.microsoft.com/graph/api/subscription-delete",
+        SupportedPlatform = CmdletSupportedPlatform.Online)]
+    [CmdletExample(
+       Code = "PS:> Remove-PnPGraphSubscription -Identity bc204397-1128-4911-9d70-1d8bceee39da",
+       Remarks = "Removes the Microsoft Graph subscription with the id 'bc204397-1128-4911-9d70-1d8bceee39da'",
+       SortOrder = 1)]
+    public class RemoveGraphSubscription : PnPGraphCmdlet
+    {
+        [Parameter(Mandatory = true, ValueFromPipeline = true, HelpMessage = "The unique id or an instance of a Microsoft Graph Subscription")]
+        public GraphSubscriptionPipeBind Identity;
+
+        protected override void ExecuteCmdlet()
+        {
+            if (Identity != null)
+            {
+                SubscriptionsUtility.DeleteSubscription(Identity.SubscriptionId, AccessToken);
+            }
+        }
+    }
+}
+#endif
diff --git a/Commands/Graph/SetGraphSubscription.cs b/Commands/Graph/SetGraphSubscription.cs
@@ -0,0 +1,35 @@
+#if !ONPREMISES
+using OfficeDevPnP.Core.Framework.Graph;
+using SharePointPnP.PowerShell.CmdletHelpAttributes;
+using SharePointPnP.PowerShell.Commands.Base;
+using SharePointPnP.PowerShell.Commands.Base.PipeBinds;
+using System;
+using System.Management.Automation;
+
+namespace SharePointPnP.PowerShell.Commands.Graph
+{
+    [Cmdlet(VerbsCommon.Set, "PnPGraphSubscription")]
+    [CmdletHelp("Updates an existing Microsoft Graph subscription. Required Azure Active Directory application permission depends on the resource the subscription exists on, see https://docs.microsoft.com/graph/api/subscription-delete#permissions.",
+        Category = CmdletHelpCategory.Graph,
+        OutputTypeLink = "https://docs.microsoft.com/graph/api/subscription-update",
+        SupportedPlatform = CmdletSupportedPlatform.Online)]
+    [CmdletExample(
+       Code = "PS:> Set-PnPGraphSubscription -Identity bc204397-1128-4911-9d70-1d8bceee39da -ExpirationDate \"2020-11-22T18:23:45.9356913Z\"",
+       Remarks = "Updates the Microsoft Graph subscription with the id 'bc204397-1128-4911-9d70-1d8bceee39da' to expire at the mentioned date",
+       SortOrder = 1)]
+    public class SetGraphSubscription : PnPGraphCmdlet
+    {
+        [Parameter(Mandatory = true, ValueFromPipeline = true, HelpMessage = "The unique id or an instance of a Microsoft Graph Subscription")]
+        public GraphSubscriptionPipeBind Identity;
+
+        [Parameter(Mandatory = true, HelpMessage = "Date and time to set the expiration to. Take notice of the maximum allowed lifetime of the subscription endponts as documented at https://docs.microsoft.com/graph/api/resources/subscription#maximum-length-of-subscription-per-resource-type")]
+        public DateTime ExpirationDate;
+
+        protected override void ExecuteCmdlet()
+        {
+            var subscription = SubscriptionsUtility.UpdateSubscription(Identity.SubscriptionId, ExpirationDate, AccessToken);
+            WriteObject(subscription);
+        }
+    }
+}
+#endif
diff --git a/Commands/SharePointPnP.PowerShell.Commands.csproj b/Commands/SharePointPnP.PowerShell.Commands.csproj
@@ -634,6 +634,7 @@
     <Compile Include="Base\PipeBinds\ProvisioningSitePipeBind.cs" />
     <Compile Include="Base\PipeBinds\ProvisioningSequencePipebind.cs" />
     <Compile Include="Base\PipeBinds\TenantSiteDesignTaskPipeBind.cs" />
+    <Compile Include="Base\PipeBinds\GraphSubscriptionPipeBind.cs" />
     <Compile Include="Base\RemoveStoredCredential.cs" />
     <Compile Include="Base\PipeBinds\ClientSideWebPartPipeBind.cs" />
     <Compile Include="Base\PipeBinds\HubSitePipeBind.cs" />
@@ -658,10 +659,14 @@
     <Compile Include="Enums\SearchBoxInNavBar.cs" />
     <Compile Include="Enums\StorageEntityScope.cs" />
     <Compile Include="Files\ResetFileVersion.cs" />
+    <Compile Include="Graph\GetGraphSubscription.cs" />
     <Compile Include="Graph\GetDeletedUnifiedGroup.cs" />
+    <Compile Include="Graph\NewGraphSubscription.cs" />
     <Compile Include="Graph\ResetUnifiedGroupExpiration.cs" />
     <Compile Include="Graph\GetAADUser.cs" />
     <Compile Include="Graph\RemoveDeletedUnifiedGroup.cs" />
+    <Compile Include="Graph\SetGraphSubscription.cs" />
+    <Compile Include="Graph\RemoveGraphSubscription.cs" />
     <Compile Include="Graph\RestoreDeletedUnifiedGroup.cs" />
     <Compile Include="InformationManagement\GetLabel.cs" />
     <Compile Include="InformationManagement\ResetLabel.cs" />