public/Get-VSADepartment.ps1
|
function Get-VSADepartment { <# .Synopsis Returns Department Data. .DESCRIPTION Returns Department Data. Takes either persistent or non-persistent connection information. .PARAMETER VSAConnection Specifies a non-persistent VSAConnection. .PARAMETER URISuffix Specifies URI suffix if it differs from the default. .PARAMETER OrgID Specifies Organization ID. Not Compatible with -DepartmentId parameter. .PARAMETER DepartmentId Specifies Department Id. Not Compatible with -OrgID parameter. .PARAMETER Filter Specifies REST API Filter. .PARAMETER Sort Specifies REST API Sorting. .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-VSADepartment -OrgID 10001 -VSAConnection $VSAConnection .EXAMPLE Get-VSADepartment -DepartmentId 10001 -VSAConnection $VSAConnection .INPUTS Accepts piped non-persistent VSAConnection .OUTPUTS Array of objects that represent Departments' Data. #> [CmdletBinding(DefaultParameterSetName = 'Department')] param ( [parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true, ParameterSetName = 'Organization')] [parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true, ParameterSetName = 'Department')] [ValidateNotNull()] [VSAConnection] $VSAConnection, [parameter(DontShow, Mandatory = $false, ParameterSetName = 'Organization')] [parameter(DontShow, Mandatory = $false, ParameterSetName = 'Department')] [ValidateNotNullOrEmpty()] [string] $URISuffix, [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = 'Organization')] [ValidateScript({ if( $_ -notmatch "^\d+$" ) { throw "Non-numeric Id" } return $true })] [string] $OrgId, [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = 'Department')] [ValidateScript({ if( $_ -notmatch "^\d+$" ) { throw "Non-numeric Id" } return $true })] [string] $DepartmentId, [parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true, ParameterSetName = 'Organization')] [parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true, ParameterSetName = 'Department')] [ValidateNotNullOrEmpty()] [string] $Filter, [parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true, ParameterSetName = 'Organization')] [parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true, ParameterSetName = 'Department')] [ValidateNotNullOrEmpty()] [string] $Sort, # 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 { $ItemId = [string]::Empty $Message = [string]::Empty if ( -not [string]::IsNullOrEmpty($OrgId) ) { #Departments for a specific organization if( [string]::IsNullOrEmpty($URISuffix) ) { $URISuffix = "api/v1.0/system/orgs/{0}/departments" } $ItemId = $OrgId $Message = "Look for departments in the Organization with ID: '$ItemId'" } else { #Specific department if( [string]::IsNullOrEmpty($URISuffix) ) { $URISuffix= "api/v1.0/system/departments/{0}" } $ItemId = $DepartmentId $Message = "Look for the Department with ID: '$ItemId'" } $URISuffix = $URISuffix -f $ItemId #region messages to verbose and debug streams $Message | Write-Debug $Message | Write-Verbose #endregion messages to verbose and debug streams [hashtable]$Params = @{ VSAConnection = $VSAConnection URISuffix = $URISuffix Filter = $Filter Sort = $Sort } #Remove empty keys foreach ( $key in @($Params.Keys) ) { if ( -not $Params[$key]) { $Params.Remove($key) } } $Message = "$($MyInvocation.MyCommand.Name):`n$($Params | Out-String)" #region messages to verbose and debug streams $Message | Write-Debug $Message | Write-Verbose #endregion messages to verbose and debug streams # 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 } } Export-ModuleMember -Function Get-VSADepartment |