diff --git a/documentation/Get-PnPFileAnalyticsData.md b/documentation/Get-PnPFileAnalyticsData.md new file mode 100644 index 000000000..1daceed43 --- /dev/null +++ b/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 [-Connection ] +``` + +## 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) diff --git a/src/Commands/Files/GetFileAnalyticsData.cs b/src/Commands/Files/GetFileAnalyticsData.cs new file mode 100644 index 000000000..5366d04e5 --- /dev/null +++ b/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))] + 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; + } + } + } +}