Add Support for the Github Traffic APIs

GitHubTraffic.ps1

@@ -0,0 +1,344 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+function Get-GitHubReferrerTraffic
+{
+<#
+    .SYNOPSIS
+        Get the top 10 referrers over the last 14 days for a given GitHub repository.
+
+    .DESCRIPTION
+        Get the top 10 referrers over the last 14 days for a given GitHub repository.
+
+        The Git repo for this module can be found here: http://aka.ms/PowerShellForGitHub
+
+    .PARAMETER OwnerName
+        Owner of the repository.
+        If not supplied here, the DefaultOwnerName configuration property value will be used.
+
+    .PARAMETER RepositoryName
+        Name of the repository.
+        If not supplied here, the DefaultRepositoryName configuration property value will be used.
+
+    .PARAMETER Uri
+        Uri for the repository.
+        The OwnerName and RepositoryName will be extracted from here instead of needing to provide
+        them individually.
+
+    .PARAMETER AccessToken
+        If provided, this will be used as the AccessToken for authentication with the
+        REST Api.  Otherwise, will attempt to use the configured value or will run unauthenticated.
+
+    .PARAMETER NoStatus
+        If this switch is specified, long-running commands will run on the main thread
+        with no commandline status update.  When not specified, those commands run in
+        the background, enabling the command prompt to provide status information.
+        If not supplied here, the DefaultNoStatus configuration property value will be used.
+
+    .EXAMPLE
+        Get-GitHubReferrerTraffic -OwnerName Powershell -RepositoryName PowerShellForGitHub
+
+        Get the top 10 referrers over the last 14 days from the PowerShell\PowerShellForGitHub project.
+#>
+    [CmdletBinding(
+        SupportsShouldProcess,
+        DefaultParametersetName='Elements')]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")]
+    param(
+        [Parameter(ParameterSetName='Elements')]
+        [string] $OwnerName,
+
+        [Parameter(ParameterSetName='Elements')]
+        [string] $RepositoryName,
+
+        [Parameter(
+            Mandatory,
+            ParameterSetName='Uri')]
+        [string] $Uri,
+
+        [string] $AccessToken,
+
+        [switch] $NoStatus
+    )
+
+    Write-InvocationLog -Invocation $MyInvocation
+
+    $elements = Resolve-RepositoryElements -BoundParameters $PSBoundParameters
+    $OwnerName = $elements.ownerName
+    $RepositoryName = $elements.repositoryName
+
+    $telemetryProperties = @{
+        'OwnerName' = (Get-PiiSafeString -PlainText $OwnerName)
+        'RepositoryName' = (Get-PiiSafeString -PlainText $RepositoryName)
+    }
+
+    $params = @{
+        'UriFragment' = "repos/$OwnerName/$RepositoryName/traffic/popular/referrers"
+        'Method' = 'Get'
+        'Description' =  "Get top 10 referrers for $RepositoryName"
+        'AcceptHeader' = 'application/vnd.github.symmetra-preview+json'
+        'AccessToken' = $AccessToken
+        'TelemetryEventName' = $MyInvocation.MyCommand.Name
+        'TelemetryProperties' = $telemetryProperties
+        'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -BoundParameters $PSBoundParameters -Name NoStatus -ConfigValueName DefaultNoStatus)
+    }
+
+    return Invoke-GHRestMethod @params
+}
+
+function Get-GitHubPathTraffic
+{
+<#
+    .SYNOPSIS
+        Get the top 10 popular contents over the last 14 days for a given Github repository.
+
+    .DESCRIPTION
+        Get the top 10 popular contents over the last 14 days for a given GitHub repository.
+
+        The Git repo for this module can be found here: http://aka.ms/PowerShellForGitHub
+
+    .PARAMETER OwnerName
+        Owner of the repository.
+        If not supplied here, the DefaultOwnerName configuration property value will be used.
+
+    .PARAMETER RepositoryName
+        Name of the repository.
+        If not supplied here, the DefaultRepositoryName configuration property value will be used.
+
+    .PARAMETER Uri
+        Uri for the repository.
+        The OwnerName and RepositoryName will be extracted from here instead of needing to provide
+        them individually.
+
+    .PARAMETER AccessToken
+        If provided, this will be used as the AccessToken for authentication with the
+        REST Api.  Otherwise, will attempt to use the configured value or will run unauthenticated.
+
+    .PARAMETER NoStatus
+        If this switch is specified, long-running commands will run on the main thread
+        with no commandline status update.  When not specified, those commands run in
+        the background, enabling the command prompt to provide status information.
+        If not supplied here, the DefaultNoStatus configuration property value will be used.
+
+    .EXAMPLE
+        Get-GitHubPathTraffic -OwnerName Powershell -RepositoryName PowerShellForGitHub
+
+        Get the top 10 popular contents over the last 14 days from the PowerShell\PowerShellForGitHub project.
+#>
+    [CmdletBinding(
+        SupportsShouldProcess,
+        DefaultParametersetName='Elements')]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")]
+    param(
+        [Parameter(ParameterSetName='Elements')]
+        [string] $OwnerName,
+
+        [Parameter(ParameterSetName='Elements')]
+        [string] $RepositoryName,
+
+        [Parameter(
+            Mandatory,
+            ParameterSetName='Uri')]
+        [string] $Uri,
+
+        [string] $AccessToken,
+
+        [switch] $NoStatus
+    )
+
+    Write-InvocationLog -Invocation $MyInvocation
+
+    $elements = Resolve-RepositoryElements -BoundParameters $PSBoundParameters
+    $OwnerName = $elements.ownerName
+    $RepositoryName = $elements.repositoryName
+
+    $telemetryProperties = @{
+        'OwnerName' = (Get-PiiSafeString -PlainText $OwnerName)
+        'RepositoryName' = (Get-PiiSafeString -PlainText $RepositoryName)
+    }
+
+    $params = @{
+        'UriFragment' = "repos/$OwnerName/$RepositoryName/traffic/popular/paths"
+        'Method' = 'Get'
+        'Description' =  "Get top 10 popular contents for $RepositoryName"
+        'AcceptHeader' = 'application/vnd.github.symmetra-preview+json'
+        'AccessToken' = $AccessToken
+        'TelemetryEventName' = $MyInvocation.MyCommand.Name
+        'TelemetryProperties' = $telemetryProperties
+        'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -BoundParameters $PSBoundParameters -Name NoStatus -ConfigValueName DefaultNoStatus)
+    }
+
+    return Invoke-GHRestMethod @params
+}
+
+function Get-GitHubViewTraffic
+{
+<#
+    .SYNOPSIS
+        Get the total number of views and breakdown per day or week for the last 14 days for the given Github Repository.
+
+    .DESCRIPTION
+        Get the total number of views and breakdown per day or week for the last 14 days.
+        Timestamps are aligned to UTC midnight of the beginning of the day or week. Week begins on Monday.
+
+        The Git repo for this module can be found here: http://aka.ms/PowerShellForGitHub
+
+    .PARAMETER OwnerName
+        Owner of the repository.
+        If not supplied here, the DefaultOwnerName configuration property value will be used.
+
+    .PARAMETER RepositoryName
+        Name of the repository.
+        If not supplied here, the DefaultRepositoryName configuration property value will be used.
+
+    .PARAMETER Uri
+        Uri for the repository.
+        The OwnerName and RepositoryName will be extracted from here instead of needing to provide
+        them individually.
+
+    .PARAMETER AccessToken
+        If provided, this will be used as the AccessToken for authentication with the
+        REST Api.  Otherwise, will attempt to use the configured value or will run unauthenticated.
+
+    .PARAMETER NoStatus
+        If this switch is specified, long-running commands will run on the main thread
+        with no commandline status update.  When not specified, those commands run in
+        the background, enabling the command prompt to provide status information.
+        If not supplied here, the DefaultNoStatus configuration property value will be used.
+
+    .EXAMPLE
+        Get-GitHubViewTraffic -OwnerName Powershell -RepositoryName PowerShellForGitHub
+
+        Get the total number of views and breakdown per day or week for the last 14 days from the PowerShell\PowerShellForGitHub project.
+#>
+    [CmdletBinding(
+        SupportsShouldProcess,
+        DefaultParametersetName='Elements')]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")]
+    param(
+        [Parameter(ParameterSetName='Elements')]
+        [string] $OwnerName,
+
+        [Parameter(ParameterSetName='Elements')]
+        [string] $RepositoryName,
+
+        [Parameter(
+            Mandatory,
+            ParameterSetName='Uri')]
+        [string] $Uri,
+
+        [string] $AccessToken,
+
+        [switch] $NoStatus
+    )
+
+    Write-InvocationLog -Invocation $MyInvocation
+
+    $elements = Resolve-RepositoryElements -BoundParameters $PSBoundParameters
+    $OwnerName = $elements.ownerName
+    $RepositoryName = $elements.repositoryName
+
+    $telemetryProperties = @{
+        'OwnerName' = (Get-PiiSafeString -PlainText $OwnerName)
+        'RepositoryName' = (Get-PiiSafeString -PlainText $RepositoryName)
+    }
+
+    $params = @{
+        'UriFragment' = "repos/$OwnerName/$RepositoryName/traffic/views"
+        'Method' = 'Get'
+        'Description' =  "Get the total number of views and breakdown per day or week for the last 14 days for $RepositoryName"
+        'AcceptHeader' = 'application/vnd.github.symmetra-preview+json'
+        'AccessToken' = $AccessToken
+        'TelemetryEventName' = $MyInvocation.MyCommand.Name
+        'TelemetryProperties' = $telemetryProperties
+        'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -BoundParameters $PSBoundParameters -Name NoStatus -ConfigValueName DefaultNoStatus)
+    }
+
+    return Invoke-GHRestMethod @params
+}
+
+function Get-GitHubCloneTraffic
+{
+<#
+    .SYNOPSIS
+        Get the total number of clones and breakdown per day or week for the last 14 days for the given Github Repository.
+
+    .DESCRIPTION
+        Get the total number of clones and breakdown per day or week for the last 14 days.
+        Timestamps are aligned to UTC midnight of the beginning of the day or week. Week begins on Monday.
+
+        The Git repo for this module can be found here: http://aka.ms/PowerShellForGitHub
+
+    .PARAMETER OwnerName
+        Owner of the repository.
+        If not supplied here, the DefaultOwnerName configuration property value will be used.
+
+    .PARAMETER RepositoryName
+        Name of the repository.
+        If not supplied here, the DefaultRepositoryName configuration property value will be used.
+
+    .PARAMETER Uri
+        Uri for the repository.
+        The OwnerName and RepositoryName will be extracted from here instead of needing to provide
+        them individually.
+
+    .PARAMETER AccessToken
+        If provided, this will be used as the AccessToken for authentication with the
+        REST Api.  Otherwise, will attempt to use the configured value or will run unauthenticated.
+
+    .PARAMETER NoStatus
+        If this switch is specified, long-running commands will run on the main thread
+        with no commandline status update.  When not specified, those commands run in
+        the background, enabling the command prompt to provide status information.
+        If not supplied here, the DefaultNoStatus configuration property value will be used.
+
+    .EXAMPLE
+        Get-GitHubCloneTraffic -OwnerName Powershell -RepositoryName PowerShellForGitHub
+
+        Get the total number of clones and breakdown per day or week for the last 14 days from the PowerShell\PowerShellForGitHub project.
+#>
+    [CmdletBinding(
+        SupportsShouldProcess,
+        DefaultParametersetName='Elements')]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")]
+    param(
+        [Parameter(ParameterSetName='Elements')]
+        [string] $OwnerName,
+
+        [Parameter(ParameterSetName='Elements')]
+        [string] $RepositoryName,
+
+        [Parameter(
+            Mandatory,
+            ParameterSetName='Uri')]
+        [string] $Uri,
+
+        [string] $AccessToken,
+
+        [switch] $NoStatus
+    )
+
+    Write-InvocationLog -Invocation $MyInvocation
+
+    $elements = Resolve-RepositoryElements -BoundParameters $PSBoundParameters
+    $OwnerName = $elements.ownerName
+    $RepositoryName = $elements.repositoryName
+
+    $telemetryProperties = @{
+        'OwnerName' = (Get-PiiSafeString -PlainText $OwnerName)
+        'RepositoryName' = (Get-PiiSafeString -PlainText $RepositoryName)
+    }
+
+    $params = @{
+        'UriFragment' = "repos/$OwnerName/$RepositoryName/traffic/clones"
+        'Method' = 'Get'
+        'Description' =  "Get the total number of clones and breakdown per day or week for the last 14 days for $RepositoryName"
+        'AcceptHeader' = 'application/vnd.github.symmetra-preview+json'
+        'AccessToken' = $AccessToken
+        'TelemetryEventName' = $MyInvocation.MyCommand.Name
+        'TelemetryProperties' = $telemetryProperties
+        'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -BoundParameters $PSBoundParameters -Name NoStatus -ConfigValueName DefaultNoStatus)
+    }
+
+    return Invoke-GHRestMethod @params
+}

PowerShellForGitHub.psd1

@@ -30,6 +30,7 @@
         'GitHubRepositories.ps1',
         'GitHubRepositoryForks.ps1',
         'GitHubTeams.ps1',
+        'GitHubTraffic.ps1',
         'GitHubUsers.ps1',
         'NugetTools.ps1',
         'Telemetry.ps1')
@@ -42,6 +43,7 @@
         'Backup-GitHubConfiguration',
         'Clear-GitHubAuthentication',
         'ConvertFrom-Markdown',
+        'Get-GitHubCloneTraffic',
         'Get-GitHubCodeOfConduct',
         'Get-GitHubConfiguration',
         'Get-GitHubEmoji',
@@ -51,8 +53,10 @@
         'Get-GitHubLabel',
         'Get-GitHubLicense',
         'Get-GitHubOrganizationMember',
+        'Get-GitHubPathTraffic',
         'Get-GitHubPullRequest',
         'Get-GitHubRateLimit',
+        'Get-GitHubReferrerTraffic',
         'Get-GitHubRepository',
         'Get-GitHubRepositoryBranch',
         'Get-GitHubRepositoryCollaborator',
@@ -66,6 +70,7 @@
         'Get-GitHubTeamMember',
         'Get-GitHubUser',
         'Get-GitHubUserContextualInformation',
+        'Get-GitHubViewTraffic',
         'Group-GitHubIssue',
         'Invoke-GHRestMethod',
         'Invoke-GHRestMethodMultipleResult',