Invoke GHRestMethod

Invoke-GHRestMethod

SYNOPSIS

A wrapper around Invoke-WebRequest that understands the GitHub API.

SYNTAX

Invoke-GHRestMethod [-UriFragment] <String> [-Method] <String> [[-Description] <String>] [[-Body] <String>]
 [[-AcceptHeader] <String>] [[-InFile] <String>] [[-ContentType] <String>] [[-AdditionalHeader] <Hashtable>]
 [-ExtendedResult] [-Save] [[-AccessToken] <String>] [[-TelemetryEventName] <String>]
 [[-TelemetryProperties] <Hashtable>] [[-TelemetryExceptionBucket] <String>] [<CommonParameters>]

DESCRIPTION

A very heavy wrapper around Invoke-WebRequest that understands the GitHub 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

EXAMPLES

EXAMPLE 1

Invoke-GHRestMethod -UriFragment "users/octocat" -Method Get -Description "Get information on the octocat user"

Gets the user information for Octocat.

EXAMPLE 2

Invoke-GHRestMethod -UriFragment "user" -Method Get -Description "Get current user"

Gets information about the current authenticated user.

PARAMETERS

-AcceptHeader

Specify the media type in the Accept header. Different types of commands may require different media types.

Type: System.String
Parameter Sets: (All)
Aliases:

Required: False
Position: 5
Default value: $script:defaultAcceptHeader
Accept pipeline input: False
Accept wildcard characters: False

-AccessToken

If provided, this will be used as the AccessToken for authentication with the REST Api as opposed to requesting a new one.

Type: System.String
Parameter Sets: (All)
Aliases:

Required: False
Position: 9
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-AdditionalHeader

Allows the caller to specify any number of additional headers that should be added to the request.

Type: System.Collections.Hashtable
Parameter Sets: (All)
Aliases:

Required: False
Position: 8
Default value: @{}
Accept pipeline input: False
Accept wildcard characters: False

-Body

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"

Type: System.String
Parameter Sets: (All)
Aliases:

Required: False
Position: 4
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ContentType

Specifies the value for the MIME Content-Type header of the request. This will usually be configured correctly automatically. You should only specify this under advanced situations (like if the extension of InFile is of a type unknown to this module).

Type: System.String
Parameter Sets: (All)
Aliases:

Required: False
Position: 7
Default value: $script:defaultJsonBodyContentType
Accept pipeline input: False
Accept wildcard characters: False

-Description

A friendly description of the operation being performed for logging and console display purposes.

Type: System.String
Parameter Sets: (All)
Aliases:

Required: False
Position: 3
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ExtendedResult

If specified, the result will be a PSObject that contains the normal result, along with the response code and other relevant header detail content.

Type: System.Management.Automation.SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-InFile

Gets the content of the web request from the specified file. Only valid for POST requests.

Type: System.String
Parameter Sets: (All)
Aliases:

Required: False
Position: 6
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Method

The type of REST method being performed. This only supports a reduced set of the possible REST methods (delete, get, post, put).

Type: System.String
Parameter Sets: (All)
Aliases:

Required: True
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Save

If specified, this will save the result to a temporary file and return the FileInfo of that temporary file.

Type: System.Management.Automation.SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-TelemetryEventName

If provided, the successful execution of this REST command will be logged to telemetry using this event name.

Type: System.String
Parameter Sets: (All)
Aliases:

Required: False
Position: 10
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-TelemetryExceptionBucket

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.

Type: System.String
Parameter Sets: (All)
Aliases:

Required: False
Position: 12
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-TelemetryProperties

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.

Type: System.Collections.Hashtable
Parameter Sets: (All)
Aliases:

Required: False
Position: 11
Default value: @{}
Accept pipeline input: False
Accept wildcard characters: False

-UriFragment

The unique, tail-end, of the REST URI that indicates what GitHub REST action will be performed. This should not start with a leading "/".

Type: System.String
Parameter Sets: (All)
Aliases:

Required: True
Position: 1
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.

INPUTS

OUTPUTS

[PSCustomObject] - The result of the REST operation, in whatever form it comes in.

[FileInfo] - The temporary file created for the downloaded file if -Save was specified.

NOTES

This wraps Invoke-WebRequest as opposed to Invoke-RestMethod because we want access to the headers that are returned in the response, and Invoke-RestMethod drops those headers.

RELATED LINKS