Functions/Get-Clients.ps1
|
function Get-Clients { <# .SYNOPSIS Retrieves all clients or a specific client via the Gorelo API. .DESCRIPTION - If nothing is specified, retrieves all Clients from /Clients - If -ID is specified, retrieves a single Client from /Clients/{ID} - Otherwise, retrieves all Clients and optionally filters by Name, BillingName, or AlternateName (client-side). - Only one filter is allowed at a time (Name, BillingName, or AlternateName). .PARAMETER BaseUrl Base API URL (default: https://api.usw.gorelo.io) .PARAMETER ApiVersion API version (default: v1) .PARAMETER ApiKey API key for authentication. .PARAMETER ID Retrieve a specific client by ID. .PARAMETER Name Filter clients by display name (client-side). .PARAMETER BillingName Filter clients by billing name (client-side). .PARAMETER AlternateName Filter clients by alternate name (client-side). .EXAMPLE Get-Clients -ApiKey "12345" .EXAMPLE Get-Clients -ApiKey "12345" -ID "abc123" .EXAMPLE Get-Clients -ApiKey "12345" -Name "*Acme*" .EXAMPLE Get-Clients -ApiKey "12345" -BillingName "*Holdings*" .EXAMPLE Get-Clients -ApiKey "12345" -AlternateName "*Corp*" #> [CmdletBinding()] param( [string]$BaseUrl = "https://api.usw.gorelo.io", [string]$ApiVersion = "v1", [Parameter(Mandatory = $true)] [string]$ApiKey, [string]$ID, [string]$Name, [string]$BillingName, [string]$AlternateName ) # Count how many filters were supplied $filterCount = 0 foreach ($f in @($ID, $Name, $BillingName, $AlternateName)) { if ($f) { $filterCount++ } } Write-Verbose "Active filters: $filterCount" if ($filterCount -gt 1) { throw "Please specify only one search filter at a time (ID, Name, BillingName, or AlternateName)." } if (-not $ApiKey) { throw "API key not provided. Use -ApiKey" } # Build API endpoint if ($ID) { $uri = "$($BaseUrl.TrimEnd('/'))/$($ApiVersion.Trim('/'))/clients/$ID" } else { $uri = "$($BaseUrl.TrimEnd('/'))/$($ApiVersion.Trim('/'))/clients" } $headers = @{ "X-API-Key" = $ApiKey "Accept" = "application/json" "Content-Type" = "application/json" } try { Write-Verbose "Sending GET request to $uri" $response = Invoke-RestMethod -Uri $uri -Method GET -Headers $headers -ErrorAction Stop } catch { $err = $_ $response = $err.Exception.Response if ($response) { $statusCode = $response.StatusCode.value__ $statusDesc = $response.StatusDescription Write-Warning "API call failed: $statusCode ($statusDesc)" } else { Write-Warning "API call failed: $($err.Exception.Message)" } throw } # Confirm no ID and response received before filtering if (-not $ID -and $response) { switch ($true) { { $Name } { $response = $response | Where-Object { $_.Name -like $Name }; break } { $BillingName } { $response = $response | Where-Object { $_.BillingName -like $BillingName }; break } { $AlternateName } { $response = $response | Where-Object { $_.AlternateName -like $AlternateName }; break } } } return $response } <# $APIKey = 'xxx' Get-Clients -ApiKey $APIKey # Gets all clients Get-Clients -ApiKey $APIKey -ID 'xxx' #Gets Clients by ID Get-Clients -ApiKey $APIKey -Name 'xxx' # Gets Clients by Name Get-Clients -ApiKey $APIKey -BillingName 'xxx' # Gets Clients by BillingName Get-Clients -ApiKey $APIKey -AlternateName 'xxx' # Gets Clietns by AlertnateName #> |