Invoke-ClientRequest
SYNOPSIS​
Send a rest request using the c8y
SYNTAX​
Invoke-ClientRequest
[-Uri] <String>
[-Method <WebRequestMethod>]
[-Headers <Hashtable>]
[-InFile <String>]
[-QueryParameters <Hashtable>]
[-ContentType <String>]
[-Accept <String>]
[-HostName <String>]
[-Data <Object>]
[-NoAccept]
[-ProcessingMode <String>]
[-Force]
[-Template <String>]
[-TemplateVars <String>]
[-Raw]
[-OutputFile <String>]
[-OutputFileRaw <String>]
[-OutputTemplate <String>]
[-Proxy]
[-NoProxy]
[-Timeout <String>]
[-NoProgress]
[-Session <String>]
[-SessionUsername <String>]
[-SessionPassword <String>]
[-SessionMode <String>]
[-Output <String>]
[-View <String>]
[-AsHashTable]
[-AsPSObject]
[-Flatten]
[-Compact]
[-NoColor]
[-Cache]
[-NoCache]
[-CacheTTL <String>]
[-Insecure]
[-Help]
[-Examples]
[-Confirm]
[-ConfirmText <String>]
[-WithError]
[-SilentStatusCodes <String>]
[-SilentExit]
[-Dry]
[-DryFormat <String>]
[-Workers <Int32>]
[-Delay <String>]
[-DelayBefore <String>]
[-MaxJobs <Int32>]
[-Progress]
[-AbortOnErrors <Int32>]
[-NoLog]
[-LogMessage <String>]
[-Select <String[]>]
[-Filter <String[]>]
[-Header <String[]>]
[-CustomQueryParam <String[]>]
[<CommonParameters>]
DESCRIPTION​
Send a custom rest request to Cumulocity using all of the options found on other command lets. This is useful if you are extending PSc8y and want to send custom microservice requests, or send requests which are not yet provided in the PSc8y module.
Example:
The following function sends a POST request to predefined microservice endpoint. It accepts an input Body argument which will be used in the request.
The response is also converted from raw json (string) to Powershell objects so that advanced
filtering can be done on the response (i.e.
using Where-Object)
Function Invoke-MyMicroserviceEndpoint {
[cmdletbinding()]
Param(
[hashtable] $Body
)
$options = @{
Method = "POST"
Uri = "/service/mymicroservice"
Data = $Body
}
# Send request
$response = Invoke-ClientRequest @options
# Convert response from json to Powershell objects
ConvertFrom-Json $response
}
EXAMPLES​
EXAMPLE 1​
Invoke-ClientRequest -Uri "/inventory/managedObjects" -Method "post" -Data "name=test"
Create a new managed object with the name "test"
EXAMPLE 2​
Invoke-ClientRequest -Uri "/alarm/alarms" -QueryParameters @{ pageSize = "100" }
Get a list of alarms with page size of 100
EXAMPLE 3​
Invoke-ClientRequest -Uri "/alarm/alarms?pageSize=100"
Get a list of alarms with page size of 100
EXAMPLE 4​
Invoke-ClientRequest -Uri "/inventory/managedObjects" -Method "post" -Data "name=test" -Headers @{ Custom-Value = "myValue"}
Create a new managed object but add a custom accept header value
PARAMETERS​
-Uri​
Uri (or partial uri). i.e. /application/applications
Type: String
Parameter Sets: (All)
Aliases:
Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Method​
Rest Method. Defaults to GET
Type: WebRequestMethod
Parameter Sets: (All)
Aliases:
Accepted values: Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Required: False
Position: Named
Default value: GET
Accept pipeline input: False
Accept wildcard characters: False
-Headers​
Add custom headers to the rest request
Type: Hashtable
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-InFile​
Input file to be uploaded as FormData
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-QueryParameters​
Uri query parameters
Type: Hashtable
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ContentType​
(Body) Content Type
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Accept​
Accept header
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-HostName​
HostName to use which overrides the given host
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-AbortOnErrors​
Abort batch when reaching specified number of errors
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-AsHashTable​
Return output as PowerShell Hashtables
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-AsPSObject​
Return output as PowerShell PSCustomObjects
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Cache​
Enable cached responses
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-CacheTTL​
Cache time-to-live (TTL) as a duration, i.e. 60s, 2m
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Compact​
Compact instead of pretty-printed output when using json output. Pretty print is the default if output is the terminal
Type: SwitchParameter
Parameter Sets: (All)
Aliases: Compress
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Confirm​
Prompt for confirmation
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ConfirmText​
Custom confirmation text
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-CustomQueryParam​
add custom URL query parameters. i.e. --customQueryParam 'withCustomOption=true,myOtherOption=myvalue'
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Data​
static data to be applied to body. accepts json or shorthand json, i.e. --data 'value1=1,my.nested.value=100'
Type: Object
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Delay​
delay after each request. It accepts a duration, i.e. 1ms, 0.5s, 1m etc.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-DelayBefore​
delay before each request. It accepts a duration, i.e. 1ms, 0.5s, 1m etc.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Dry​
Dry run. Don't send any data to the server
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-DryFormat​
Dry run output format. i.e. json, dump, markdown or curl
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Examples​
Show examples for the current command
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Filter​
Apply a client side filter to response before returning it to the user
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Flatten​
flatten json output by replacing nested json properties with properties where their names are represented by dot notation
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Force​
Do not prompt for confirmation. Ignored when using --confirm
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Header​
custom headers. i.e. --header 'Accept: value, AnotherHeader: myvalue'
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Help​
Show command help
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Insecure​
Allow insecure server connections when using SSL
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-LogMessage​
Add custom message to the activity log
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-MaxJobs​
Maximum number of jobs. 0 = unlimited (use with caution!)
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-NoAccept​
Ignore Accept header will remove the Accept header from requests, however PUT and POST requests will only see the effect
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-NoCache​
Force disabling of cached responses (overwrites cache setting)
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-NoColor​
Don't use colors when displaying log entries on the console
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-NoLog​
Disables the activity log for the current command
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-NoProgress​
Disable progress bars
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-NoProxy​
Ignore the proxy settings
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Output​
Output format i.e. table, json, csv, csvheader
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-OutputFile​
Save JSON output to file (after select/view)
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-OutputFileRaw​
Save raw response to file (before select/view)
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-OutputTemplate​
jsonnet template to apply to the output
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ProcessingMode​
Cumulocity processing mode
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Progress​
Show progress bar. This will also disable any other verbose output
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Proxy​
Proxy setting, i.e. http://10.0.0.1:8080
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Raw​
Show raw response. This mode will force output=json and view=off
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Select​
Comma separated list of properties to return. wildcards and globstar accepted, i.e. --select 'id,name,type,**.serialNumber'
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Session​
Session configuration
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-SessionMode​
Override default session mode for a single command which would normally be disabled
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-SessionPassword​
Override session password
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-SessionUsername​
Override session username. i.e. peter or t1234/peter (with tenant)
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-SilentExit​
Silent status codes do not affect the exit code
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-SilentStatusCodes​
Status codes which will not print out an error message
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Template​
Body template
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-TemplateVars​
Body template variables
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Timeout​
Request timeout. It accepts a duration, i.e. 1ms, 0.5s, 1m etc.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-View​
Use views when displaying data on the terminal. Disable using --view off
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-WithError​
Errors will be printed on stdout instead of stderr
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Workers​
Number of workers
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters​
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.