< Back
Invoke-GHRestMethod
Post
NAME Invoke-GHRestMethod
SYNOPSIS
A wrapper around Invoke-WebRequest that understands the Store API.
SYNTAX
Invoke-GHRestMethod [-UriFragment] <String> [-Method] <String> [[-Description] <String>] [[-Body] <String>]
[[-AcceptHeader] <String>] [-ExtendedResult] [[-AccessToken] <String>] [[-TelemetryEventName] <String>]
[[-TelemetryProperties] <Hashtable>] [[-TelemetryExceptionBucket] <String>] [-NoStatus] [-WhatIf] [-Confirm]
[<CommonParameters>]
DESCRIPTION
A very heavy wrapper around Invoke-WebRequest that understands the Store API and
how to perform its operation with and without console status updates. It also
understands how to parse and handle errors from the REST calls.
The Git repo for this module can be found here: http://aka.ms/PowerShellForGitHub
PARAMETERS
-UriFragment <String>
The unique, tail-end, of the REST URI that indicates what Store REST action will
be peformed. This should not start with a leading "/".
Required? true
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Method <String>
The type of REST method being peformed. This only supports a reduced set of the
possible REST methods (delete, get, post, put).
Required? true
Position? 2
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Description <String>
A friendly description of the operation being performed for logging and console
display purposes.
Required? false
Position? 3
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Body <String>
This optional parameter forms the body of a PUT or POST request. It will be automatically
encoded to UTF8 and sent as Content Type: "application/json; charset=UTF-8"
Required? false
Position? 4
Default value
Accept pipeline input? false
Accept wildcard characters? false
-AcceptHeader <String>
Specify the media type in the Accept header. Different types of commands may require
different media types.
Required? false
Position? 5
Default value $script:defaultAcceptHeader
Accept pipeline input? false
Accept wildcard characters? false
-ExtendedResult [<SwitchParameter>]
If specified, the result will be a PSObject that contains the normal result, along with
the response code and other relevant header detail content.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-AccessToken <String>
If provided, this will be used as the AccessToken for authentication with the
REST Api as opposed to requesting a new one.
Required? false
Position? 6
Default value
Accept pipeline input? false
Accept wildcard characters? false
-TelemetryEventName <String>
If provided, the successful execution of this REST command will be logged to telemetry
using this event name.
Required? false
Position? 7
Default value
Accept pipeline input? false
Accept wildcard characters? false
-TelemetryProperties <Hashtable>
If provided, the successful execution of this REST command will be logged to telemetry
with these additional properties. This will be silently ignored if TelemetryEventName
is not provided as well.
Required? false
Position? 8
Default value @{}
Accept pipeline input? false
Accept wildcard characters? false
-TelemetryExceptionBucket <String>
If provided, any exception that occurs will be logged to telemetry using this bucket.
It's possible that users will wish to log exceptions but not success (by providing
TelemetryEventName) if this is being executed as part of a larger scenario. If this
isn't provided, but TelemetryEventName *is* provided, then TelemetryEventName will be
used as the exception bucket value in the event of an exception. If neither is specified,
no bucket value will be used.
Required? false
Position? 9
Default value
Accept pipeline input? false
Accept wildcard characters? false
-NoStatus [<SwitchParameter>]
If this switch is specified, long-running commands will run on the main thread
with no commandline status update. When not specified, those commands run in
the background, enabling the command prompt to provide status information.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-WhatIf [<SwitchParameter>]
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Confirm [<SwitchParameter>]
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
[PSCutomObject] - The result of the REST operation, in whatever form it comes in.
NOTES
This wraps Invoke-WebRequest as opposed to Invoke-RestMethod because we want access to the headers
that are returned in the response (specifically 'MS-ClientRequestId') for logging purposes, and
Invoke-RestMethod drops those headers.
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>Invoke-GHRestMethod -UriFragment "applications/" -Method Get -Description "Get first 10 applications"
Gets the first 10 applications for the connected dev account.
-------------------------- EXAMPLE 2 --------------------------
PS C:\\>Invoke-GHRestMethod -UriFragment "applications/0ABCDEF12345/submissions/1234567890123456789/" -Method
Delete -Description "Delete Submission" -NoStatus
Deletes the specified submission, but the request happens in the foreground and there is
no additional status shown to the user until a response is returned from the REST request.
RELATED LINKS
SYNOPSIS
A wrapper around Invoke-WebRequest that understands the Store API.
SYNTAX
Invoke-GHRestMethod [-UriFragment] <String> [-Method] <String> [[-Description] <String>] [[-Body] <String>]
[[-AcceptHeader] <String>] [-ExtendedResult] [[-AccessToken] <String>] [[-TelemetryEventName] <String>]
[[-TelemetryProperties] <Hashtable>] [[-TelemetryExceptionBucket] <String>] [-NoStatus] [-WhatIf] [-Confirm]
[<CommonParameters>]
DESCRIPTION
A very heavy wrapper around Invoke-WebRequest that understands the Store API and
how to perform its operation with and without console status updates. It also
understands how to parse and handle errors from the REST calls.
The Git repo for this module can be found here: http://aka.ms/PowerShellForGitHub
PARAMETERS
-UriFragment <String>
The unique, tail-end, of the REST URI that indicates what Store REST action will
be peformed. This should not start with a leading "/".
Required? true
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Method <String>
The type of REST method being peformed. This only supports a reduced set of the
possible REST methods (delete, get, post, put).
Required? true
Position? 2
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Description <String>
A friendly description of the operation being performed for logging and console
display purposes.
Required? false
Position? 3
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Body <String>
This optional parameter forms the body of a PUT or POST request. It will be automatically
encoded to UTF8 and sent as Content Type: "application/json; charset=UTF-8"
Required? false
Position? 4
Default value
Accept pipeline input? false
Accept wildcard characters? false
-AcceptHeader <String>
Specify the media type in the Accept header. Different types of commands may require
different media types.
Required? false
Position? 5
Default value $script:defaultAcceptHeader
Accept pipeline input? false
Accept wildcard characters? false
-ExtendedResult [<SwitchParameter>]
If specified, the result will be a PSObject that contains the normal result, along with
the response code and other relevant header detail content.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-AccessToken <String>
If provided, this will be used as the AccessToken for authentication with the
REST Api as opposed to requesting a new one.
Required? false
Position? 6
Default value
Accept pipeline input? false
Accept wildcard characters? false
-TelemetryEventName <String>
If provided, the successful execution of this REST command will be logged to telemetry
using this event name.
Required? false
Position? 7
Default value
Accept pipeline input? false
Accept wildcard characters? false
-TelemetryProperties <Hashtable>
If provided, the successful execution of this REST command will be logged to telemetry
with these additional properties. This will be silently ignored if TelemetryEventName
is not provided as well.
Required? false
Position? 8
Default value @{}
Accept pipeline input? false
Accept wildcard characters? false
-TelemetryExceptionBucket <String>
If provided, any exception that occurs will be logged to telemetry using this bucket.
It's possible that users will wish to log exceptions but not success (by providing
TelemetryEventName) if this is being executed as part of a larger scenario. If this
isn't provided, but TelemetryEventName *is* provided, then TelemetryEventName will be
used as the exception bucket value in the event of an exception. If neither is specified,
no bucket value will be used.
Required? false
Position? 9
Default value
Accept pipeline input? false
Accept wildcard characters? false
-NoStatus [<SwitchParameter>]
If this switch is specified, long-running commands will run on the main thread
with no commandline status update. When not specified, those commands run in
the background, enabling the command prompt to provide status information.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-WhatIf [<SwitchParameter>]
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Confirm [<SwitchParameter>]
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
[PSCutomObject] - The result of the REST operation, in whatever form it comes in.
NOTES
This wraps Invoke-WebRequest as opposed to Invoke-RestMethod because we want access to the headers
that are returned in the response (specifically 'MS-ClientRequestId') for logging purposes, and
Invoke-RestMethod drops those headers.
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>Invoke-GHRestMethod -UriFragment "applications/" -Method Get -Description "Get first 10 applications"
Gets the first 10 applications for the connected dev account.
-------------------------- EXAMPLE 2 --------------------------
PS C:\\>Invoke-GHRestMethod -UriFragment "applications/0ABCDEF12345/submissions/1234567890123456789/" -Method
Delete -Description "Delete Submission" -NoStatus
Deletes the specified submission, but the request happens in the foreground and there is
no additional status shown to the user until a response is returned from the REST request.
RELATED LINKS