public/Get-VSAPatchMissing.ps1
|
function Get-VSAPatchMissing { <# .Synopsis Returns an array of missing patches. .DESCRIPTION Returns an array of missing patches on an agent machine, with denied patches either included or excluded. Takes either persistent or non-persistent connection information. .PARAMETER VSAConnection Specifies existing non-persistent VSAConnection. .PARAMETER URISuffix Specifies URI suffix if it differs from the default. .PARAMETER AgentId Specifies id of agent machine. .PARAMETER Parallel Fetches the remaining pages of a large collection concurrently instead of one after another. Opt-in: without it, behaviour is unchanged. Results are identical either way (same records, merged in $skip order). Only engages once the collection is large enough to be worth it (see -ParallelThreshold). .PARAMETER ThrottleLimit Maximum number of concurrent requests when -Parallel is used (default 8). On shared SaaS you are one tenant among many, so a modest value is a good citizen; the engine also reduces concurrency automatically if the server returns HTTP 429, then recovers. .PARAMETER ParallelThreshold Minimum total record count before -Parallel actually engages. 0 (default) means automatic: two full throttle windows, i.e. 2 * ThrottleLimit * 100 records. Below that the sequential path is used, because it is faster than paying to set up extra connections. .EXAMPLE Get-VSAPatchMissing -AgentId 979868787875855 .PARAMETER Filter Specifies REST API Filter. .PARAMETER Sort Specifies REST API Sorting. .PARAMETER HideDeniedPatches Excludes patches that have been denied from the result. .EXAMPLE Get-VSAPatchMissing -AgentId 979868787875855 -HideDeniedPatches .EXAMPLE Get-VSAPatchMissing -VSAConnection $connection -AgentId 979868787875855 .INPUTS Accepts piped non-persistent VSAConnection .OUTPUTS Array of items that represent missing patches #> [CmdletBinding()] param ( [parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true)] [ValidateNotNull()] [VSAConnection] $VSAConnection, [parameter(DontShow, Mandatory=$false)] [ValidateNotNullOrEmpty()] [string] $URISuffix = 'api/v1.0/assetmgmt/patch/{0}/machineupdate/{1}', [parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [ValidateScript({ if( $_ -notmatch "^\d+$" ) { throw "Non-numeric Id" } return $true })] [string] $AgentID, [parameter(Mandatory=$false, ValueFromPipelineByPropertyName=$true)] [ValidateNotNullOrEmpty()] [string] $Filter, [parameter(Mandatory=$false, ValueFromPipelineByPropertyName=$true)] [ValidateNotNullOrEmpty()] [string] $Sort, [Parameter(Mandatory = $false)] [switch] $HideDeniedPatches, # Opt-in parallel paging for large collections (see Invoke-VSARestMethod). No effect on small # ones: below -ParallelThreshold the sequential path is used. [parameter(Mandatory = $false)] [switch] $Parallel, [parameter(Mandatory = $false)] [ValidateRange(1, 64)] [int] $ThrottleLimit = 8, [parameter(Mandatory = $false)] [ValidateRange(0, [int]::MaxValue)] [int] $ParallelThreshold = 0 ) process { [hashtable]$Params = @{ URISuffix = $( $URISuffix -f $AgentID, $HideDeniedPatches.ToString() ) VSAConnection = $VSAConnection Filter = $Filter Sort = $Sort } foreach ( $key in @($Params.Keys) ) { if ( -not $Params[$key]) { $Params.Remove($key) } } # Forward the opt-in parallel controls to the shared read path, which owns the paging engine. if ($Parallel) { $Params['Parallel'] = $true $Params['ThrottleLimit'] = $ThrottleLimit if ($ParallelThreshold -gt 0) { $Params['ParallelThreshold'] = $ParallelThreshold } } return Invoke-VSARestMethod @Params } } New-Alias -Name Get-VSAMissingPatches -Value Get-VSAPatchMissing Export-ModuleMember -Function Get-VSAPatchMissing -Alias Get-VSAMissingPatches |