Public/Get-RyverHistory.ps1
|
function Get-RyverHistory { <# .SYNOPSIS Get history from a Ryver public forum or private team channel. .DESCRIPTION Get history from a Ryver public forum or private team channel. .INPUTS System.UInt64 .INPUTS System.Management.Automation.PSCustomObject .NOTES - Troy Lindsay - Twitter: @troylindsay42 - GitHub: tlindsay42 .EXAMPLE Get-RyverHistory -ID 12345678 -Type 'Team' Queries for the chat history of the private team channel with ID 12345678. .EXAMPLE Get-RyverHistory -ID 12345678 -Type 'Forum' -Credential ( Get-Credential ) Updates the $Script:PSRyver.Authorization value storing the basic authentication authorization header to use for all requests and then queries for the chat history of the public forum channel with ID 12345678. .EXAMPLE 12345678 | Get-RyverHistory -Type 'User' -Raw Queries for the chat history with the user with ID 12345678 via pipeline value, and returns the raw, unformatted output. .EXAMPLE [PSCustomObject] @{ ID = 12345678; Type = 'Team' } | Get-RyverHistory Queries for the chat history with the user with ID 12345678 via pipeline parameter names. .EXAMPLE Get-RyverHistory 12345678 'Forum' $true Queries for the chat history of the public forum channel with ID 12345678 via positional parameter and returns the raw, unformatted output. .LINK https://tlindsay42.github.io/PSRyver/Public/Get-RyverHistory/ .LINK https://github.com/tlindsay42/PSRyver/blob/master/PSRyver/Public/Get-RyverHistory.ps1 .FUNCTIONALITY Ryver #> [CmdletBinding( HelpUri = 'https://tlindsay42.github.io/PSRyver/Public/Get-RyverHistory/', SupportsPaging = $true )] param ( <# Specifies the ID of the public forum channel, private team channel, or user direct message to download the chat history from. #> [Parameter( Mandatory = $true, Position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true )] [UInt64] $ID, <# Specifies the type of channel to post the message in: - Public forum - Private team - User direct message #> [Parameter( Mandatory = $true, Position = 1, ValueFromPipelineByPropertyName = $true )] [ValidateSet( 'Forum', 'Team', 'User' )] [String] $Type, # Specifies that objects should not be formatted. [Parameter( Position = 2 )] [Switch] $Raw, <# Credentials to use for the Ryver API. Default value is the value set by Set-PSRyverConfig. #> [Parameter( Position = 3 )] [PSCredential] $Credential ) begin { $function = $MyInvocation.MyCommand.Name Write-Verbose -Message "Beginning: '${function}'." #region init $return = @() $first = $PSCmdlet.PagingParameters.Skip $last = $first + $PSCmdlet.PagingParameters.First #endregion Write-Verbose -Message "First index position: '${first}'." if ( $PSBoundParameters.ContainsKey( 'Credential' ) ) { $Script:PSRyver.Authorization = ConvertTo-Authorization -Credential $Credential Remove-Variable -Name 'Credential' } Assert-RyverApiConfig if ( $PSCmdlet.PagingParameters.First -eq 0 ) { Write-Verbose -Message "The 'First' parameter is set to accept zero results- terminating." break } } process { Write-Verbose -Message ( "Processing: '${function}' with ParameterSetName '$( $PSCmdlet.ParameterSetName )' and Parameters: " + ( $PSBoundParameters | Remove-SensitiveData | Format-Table -AutoSize -Wrap | Out-String ) ) #region init $path = '/' $skip = 0 $count = [UInt64]::MaxValue $objects = @() #endregion switch ( $Type ) { 'Forum' { $path += "forums(${ID})" } 'Team' { $path += "workrooms(${ID})" } 'User' { $path += "users(${ID})" } } #region Build the URI path $path += ( '/Chat.History()?' + "`$top=$( $Script:PSRyver.MaxPageSize )" + "&`$skip=${skip}" + '&$orderby=when+asc' + '&$inlinecount=allpages' ) #endregion $splat = @{ Method = 'Get' Path = $path ErrorAction = 'Stop' } while ( $return.Count -lt $last -and $skip -lt $count ) { $response = Invoke-RyverRestMethod @splat [UInt64] $count = $response.D.__Count Write-Verbose -Message "Found '${count}' objects." Write-Verbose -Message "Queried for objects '${skip}-$( $skip + $Script:PSRyver.MaxPageSize )'." $tempObjects = $response | Select-Object -ExpandProperty 'D' | Select-Object -ExpandProperty 'Results' if ( $Name ) { Write-Verbose -Message "Received '$( ( $tempObjects | Measure-Object ).Count )' objects with server-side filtering." $tempObjects = $tempObjects | Where-Object -FilterScript { $_.Name -like $Name } Write-Verbose -Message "Filtered to '$( ( $tempObjects | Measure-Object ).Count )' objects after client-side filtering." } $objects += $tempObjects $skip += $Script:PSRyver.MaxPageSize $splat.Path = $path -replace '\$skip=\d+', "`$skip=${skip}" $return += $objects } Write-Verbose -Message "Added '$( ( $objects | Measure-Object ).Count )' objects in this Process cycle." } end { $count = ( $return | Measure-Object ).Count if ( $count -gt 0 ) { if ( $PSCmdlet.PagingParameters.Skip -ge $count ) { Write-Verbose -Message "Insufficient results: '${count}' to satisfy the 'Skip' parameter value: '${first}'." $return = $null } else { $last = $first + [Math]::Min( $PSCmdlet.PagingParameters.First, $count - $PSCmdlet.PagingParameters.Skip ) - 1 Write-Verbose -Message "Last index position: '${last}'." if ( $first -le $last ) { $return = $return[$first..$last] if ( $Raw -eq $true ) { $return } else { $return | Format-RyverMessageObject } } else { $return = $null } } } $count = ( $return | Measure-Object ).Count Write-Verbose -Message "Returned '${count}' objects." if ( $PSCmdlet.PagingParameters.IncludeTotalCount ) { $PSCmdlet.PagingParameters.NewTotalCount( $count, 1.0 ) } Write-Verbose -Message "Ending: '${function}'." } } |