public/Get-VSAAuditDocument.ps1
|
function Get-VSAAuditDocument { <# .Synopsis Downloads a specified document or retrieves documents' metadata from the Audit > Documents page. .DESCRIPTION This function retrieves information about documents or downloads a specific document from the Audit > Documents page in a VSA environment. Supports both persistent and non-persistent VSA connections. .PARAMETER AgentID Specifies the ID of the agent. .PARAMETER VSAConnection Specifies an existing non-persistent VSAConnection. .PARAMETER Path Specifies the path to a specific document or folder. .PARAMETER DownloadsFolder Specifies the folder to download files. Defaults to the user's Downloads folder. .PARAMETER Filter Specifies a REST API filter for document retrieval. .PARAMETER Sort Specifies REST API sorting criteria. .PARAMETER DownloadDocument Switch parameter. If present, specifies that a specific document should be downloaded. .EXAMPLE Get-VSAAuditDocument -AgentID 10001 -Path 'Folder/Document.doc' -DownloadDocument .EXAMPLE Get-VSAAuditDocument -AgentID 10001 -Path 'Folder/Document.doc' -VSAConnection $connection -DownloadDocument .EXAMPLE Get-VSAAuditDocument -AgentID 10001 -Filter 'Category eq "Important"' .INPUTS Accepts piped non-persistent VSAConnection. .OUTPUTS Returns a single document or an array of documents based on the provided parameters. #> [CmdletBinding(DefaultParameterSetName='Metadata')] param ( [parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true)] [ValidateScript({ if ($_ -notmatch "^\d+$") { throw "AgentID must be a numeric value." } return $true })] [string] $AgentID, [parameter(Mandatory=$false, ValueFromPipeline=$true)] [ValidateNotNull()] [VSAConnection] $VSAConnection, [parameter(Mandatory=$true)] [ValidateNotNullOrEmpty()] [string] $Path, [parameter(Mandatory=$false)] [ValidateNotNullOrEmpty()] [string] $DownloadsFolder, [parameter(ParameterSetName='Metadata')] [ValidateNotNull()] [string] $Filter, [parameter(ParameterSetName='Metadata')] [ValidateNotNull()] [string] $Sort, [switch] $DownloadDocument ) process { if ( $PSCmdlet.MyInvocation.InvocationName -eq 'Get-VSADocument' ) { $DownloadDocument = $true } if ( $PSCmdlet.MyInvocation.InvocationName -eq 'Get-VSADocuments' ) { $DownloadDocument = $false } if ( [string]::IsNullOrEmpty($Path) -and (-not $DownloadDocument) ) {$Path = '.'} [string] $URISuffix = $(if ( $DownloadDocument ) { 'api/v1.0/assetmgmt/documents/{0}/file/{1}' } else { 'api/v1.0/assetmgmt/documents/{0}/folder/{1}' }) -f $AgentID, (Format-VSAPathSegment ($Path -replace '\\', '/')) $Params = @{ VSAConnection = $VSAConnection URISuffix = $URISuffix } if ($DownloadDocument) { if (-not $DownloadsFolder) { $DownloadsFolder = [System.IO.Path]::Combine([Environment]::GetFolderPath('UserProfile'), 'Downloads') } # Download to a file: Invoke-VSARestMethod forwards -OutFile to the transport, which writes # the response body to disk. It has no -DownloadsFolder parameter, so passing that failed # every document download with "a parameter cannot be found" (F-27). Build the OutFile path # from the folder + the document's leaf name, mirroring Get-VSAStorageContent. $Params['OutFile'] = Join-Path -Path $DownloadsFolder -ChildPath (Split-Path -Path $Path -Leaf) } else { $Params['Filter'] = $Filter $Params['Sort'] = $Sort } #Remove empty keys foreach ( $key in @($Params.Keys) ) { if ( -not $Params[$key] ) { $Params.Remove($key) } } "Get-VSAAuditDocument: $($Params | Out-String)" | Write-Debug "Get-VSAAuditDocument: $($Params | Out-String)" | Write-Verbose return Invoke-VSARestMethod @Params } } # Define aliases Set-Alias -Name Get-VSADocument -Value Get-VSAAuditDocument Set-Alias -Name Get-VSADocuments -Value Get-VSAAuditDocument Export-ModuleMember -Function Get-VSAAuditDocument -Alias Get-VSADocument Export-ModuleMember -Function Get-VSAAuditDocument -Alias Get-VSADocuments |