Feature: Added cmdlet to retrieve File analytics data.

documentation/Get-PnPFileAnalyticsData.md

@@ -0,0 +1,152 @@
+---
+Module Name: PnP.PowerShell
+schema: 2.0.0
+applicable: SharePoint Online
+online version: https://pnp.github.io/powershell/cmdlets/Get-PnPFileAnalyticsData.html
+external help file: PnP.PowerShell.dll-Help.xml
+title: Get-PnPFileAnalyticsData
+---
+
+# Get-PnPFileAnalyticsData
+
+## SYNOPSIS
+Retrieves analytics data for a file.
+
+## SYNTAX
+
+### Return analytics data
+```powershell
+Get-PnPFileAnalyticsData -Url <String> [-Connection <PnPConnection>]
+```
+
+## DESCRIPTION
+Retrieves file analytics data within a specific date range.
+
+## EXAMPLES
+
+### EXAMPLE 1
+```powershell
+Get-PnPFileAnalyticsData -Url "/sites/project/Shared Documents/Document.docx"
+```
+
+Retrieves all available analytics data for the specified file.
+
+### EXAMPLE 2
+```powershell
+Get-PnPFileAnalyticsData -Url "/sites/project/Shared Documents/Document.docx" -LastSevenDays
+```
+
+Retrieves analytics data for the last seven days of the specified file.
+
+### EXAMPLE 3
+```powershell
+Get-PnPFileAnalyticsData -Url "/sites/project/Shared Documents/Document.docx" -StartDate (Get-date).AddDays(-15) -EndDate (Get-date) -AnalyticsAggregationInterval Day
+```
+
+Retrieves analytics data for the last 15 days of the specified file with aggregation interval as days.
+
+## PARAMETERS
+
+### -Url
+The URL (server or site relative) to the file
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases: ServerRelativeUrl, SiteRelativeUrl
+
+Required: True
+Position: 0
+Default value: None
+Accept pipeline input: True (ByValue)
+Accept wildcard characters: False
+```
+
+### -All
+When specified, it will retrieve all analytics data.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: All analytics data
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -LastSevenDays
+When specified, it will retrieve analytics data for the last seven days.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: Analytics by specific intervals
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -StartDate
+When specified, it will retrieve analytics data starting from the specified start date.
+
+```yaml
+Type: DateTime
+Parameter Sets: Analytics by date range
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -EndDate
+When specified, it will retrieve analytics data ending with specified end date. Should be used along with StartDate parameter
+
+```yaml
+Type: DateTime
+Parameter Sets: Analytics by date range
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -AnalyticsAggregationInterval
+When specified, it will retrieve analytics data with specified aggregation interval. Default is day.
+Allowed values are `Day`,`Week` and `Month`.
+
+```yaml
+Type: DateTime
+Parameter Sets: Analytics by date range
+
+Required: False
+Position: Named
+Default value: Day
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Connection
+Optional connection to be used by the cmdlet. Retrieve the value for this parameter by either specifying -ReturnConnection on Connect-PnPOnline or by executing Get-PnPConnection.
+
+```yaml
+Type: PnPConnection
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+## RELATED LINKS
+
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

src/Commands/Files/GetFileAnalyticsData.cs

@@ -0,0 +1,112 @@
+using Microsoft.SharePoint.Client;
+using PnP.Core.Model.SharePoint;
+using PnP.Framework.Utilities;
+using System;
+using System.Collections.Generic;
+using System.Management.Automation;
+
+namespace PnP.PowerShell.Commands.Files
+{
+    [Cmdlet(VerbsCommon.Get, "PnPFileAnalyticsData", DefaultParameterSetName = ParameterSetName_ALL)]
+    [OutputType(typeof(List<IActivityStat>))]
+    public class GetFileAnalyticsData : PnPWebCmdlet
+    {
+        private const string ParameterSetName_ANALYTICS_BY_DATE_RANGE = "Analytics by date range";
+        private const string ParameterSetName_ALL = "All analytics data";
+        private const string ParameterSetName_LAST_SEVEN_DAYS = "Analytics by specific intervals";
+
+        [Parameter(Mandatory = true, ParameterSetName = ParameterSetName_ALL, Position = 0, ValueFromPipeline = true)]
+        [Parameter(Mandatory = true, ParameterSetName = ParameterSetName_ANALYTICS_BY_DATE_RANGE, Position = 0, ValueFromPipeline = true)]
+        [Parameter(Mandatory = true, ParameterSetName = ParameterSetName_LAST_SEVEN_DAYS, Position = 0, ValueFromPipeline = true)]
+        [Alias("ServerRelativeUrl", "SiteRelativeUrl")]
+        public string Url;
+
+        [Parameter(Mandatory = false, ParameterSetName = ParameterSetName_ALL)]
+        public SwitchParameter All;
+
+        [Parameter(Mandatory = false, ParameterSetName = ParameterSetName_LAST_SEVEN_DAYS)]
+        public SwitchParameter LastSevenDays;
+
+        [Parameter(Mandatory = false, ParameterSetName = ParameterSetName_ANALYTICS_BY_DATE_RANGE)]
+        public DateTime StartDate;
+
+        [Parameter(Mandatory = false, ParameterSetName = ParameterSetName_ANALYTICS_BY_DATE_RANGE)]
+        public DateTime EndDate;
+
+        [Parameter(Mandatory = false, ParameterSetName = ParameterSetName_ANALYTICS_BY_DATE_RANGE)]
+        public AnalyticsAggregationInterval AnalyticsAggregationInterval = AnalyticsAggregationInterval.Day;
+
+        protected override void ExecuteCmdlet()
+        {
+            var serverRelativeUrl = string.Empty;
+
+            // Remove URL decoding from the Url as that will not work. We will encode the + character specifically, because if that is part of the filename, it needs to stay and not be decoded.
+            Url = Utilities.UrlUtilities.UrlDecode(Url.Replace("+", "%2B"));
+
+            var webUrl = CurrentWeb.EnsureProperty(w => w.ServerRelativeUrl);
+
+            if (!Url.ToLower().StartsWith(webUrl.ToLower()))
+            {
+                serverRelativeUrl = UrlUtility.Combine(webUrl, Url);
+            }
+            else
+            {
+                serverRelativeUrl = Url;
+            }
+
+            IFile analyticsFile = PnPContext.Web.GetFileByServerRelativeUrl(serverRelativeUrl, p => p.VroomItemID, p => p.VroomDriveID);
+
+            switch (ParameterSetName)
+            {
+                case ParameterSetName_ALL:
+                    // Get analytics for all time
+                    var analytics = analyticsFile.GetAnalytics();
+                    WriteObject(analytics, true);
+                    break;
+
+                case ParameterSetName_LAST_SEVEN_DAYS:
+                    // Get analytics for last seven days
+                    var analyticsLastSevenDays = analyticsFile.GetAnalytics(new AnalyticsOptions { Interval = AnalyticsInterval.LastSevenDays, CustomAggregationInterval = AnalyticsAggregationInterval.Week });
+                    WriteObject(analyticsLastSevenDays, true);
+                    break;
+
+                case ParameterSetName_ANALYTICS_BY_DATE_RANGE:
+
+                    if (EndDate == DateTime.MinValue)
+                    {
+                        EndDate = DateTime.UtcNow;
+                    }
+
+                    if (StartDate == DateTime.MinValue)
+                    {
+                        StartDate = EndDate.AddDays(-90.0);
+                    }
+
+                    if (EndDate < StartDate)
+                    {
+                        throw new PSArgumentException("Invalid Date Range");
+                    }
+
+                    if ((EndDate.Date - StartDate.Date).TotalDays > 90)
+                    {
+                        throw new PSArgumentException("The maximum allowed difference between start and end date is 90 days");
+                    }
+
+                    var analyticsCustomData = analyticsFile.GetAnalytics(new AnalyticsOptions
+                    {
+                        Interval = AnalyticsInterval.Custom,
+                        CustomAggregationInterval = AnalyticsAggregationInterval,
+                        CustomEndDate = EndDate,
+                        CustomStartDate = StartDate,
+                    });
+                    WriteObject(analyticsCustomData, true);
+                    break;
+                default:
+                    // Get analytics for all time
+                    var allAnalytics = analyticsFile.GetAnalytics();
+                    WriteObject(allAnalytics, true);
+                    break;
+            }
+        }
+    }
+}