Invoke-TfsRestApi

Invoke an Azure DevOps REST API.

Table of Contents

1. Syntax
2. Description
3. Examples
4. Parameters
5. Related Links

Syntax

Invoke-TfsRestApi
    [-Path] <string>
    [-QueryParameters <Hashtable>]
    [-AdditionalHeaders <Hashtable>]
    [-ApiVersion <string>]
    [-AsTask]
    [-Body <string>]
    [-Collection <object>]
    [-Destination <string>]
    [-Method <string>]
    [-NoAutoUnwrap]
    [-Project <object>]
    [-Raw]
    [-RequestContentType <string>]
    [-ResponseContentType <string>]
    [-Server <object>]
    [-Team <object>]
    [-UseHost <string>]

[Go to top]

Description

Invoke-TfsRestApi can automatically parse an example URL from https://docs.microsoft.com/en-us/rest/api/azure/devops/ and replace its various tokens (such as {organization}, {project} and {team}) as long as collection / project / team information are available via either the their respective arguments in this command or the corresponding Connect-Tfs* cmdlet. HTTP method and API version are also automatically extracted from the supplied example, when available.

[Go to top]

Examples

Example 1

Calls a REST API that lists all team projects in a TFS collection named DefaultCollection

PS> Invoke-TfsRestApi -Method GET -Path /_apis/projects -ApiVersion 4.1 -Collection DefaultCollection

Example 2

Calls the API described by an example extracted from the docs.microsoft.com web site. HTTP method, host name and API version are all set based on the supplied values; Tokens {organization}, {project} and {team} are properly replaced with the corresponding values provided by the current connection context (via previous calls to Connect-TfsTeamProjectCollection, Connect-TfsTeamProject and/or Connect-TfsTeam).

PS> Invoke-TfsRestApi 'GET https://extmgmt.dev.azure.com/{organization}/_apis/extensionmanagement/installedextensions?api-version=5.1-preview.1'

Example 3

Calls an API in a TFS instance, parsing the example provided by the docs.microsoft.com web site.

PS> Invoke-TfsRestApi 'GET https://{instance}/{collection}/_apis/process/processes?api-version=4.1' -Collection http://vsalm:8080/tfs/DefaultCollection

Parameters

-AdditionalHeaders

Specifies a hashtable with additional HTTP headers to send to the API endpoint.

-ApiVersion

Specifies the desired API version. When omitted, defaults to “4.1”.

-AsTask

Returns the System.Threading.Tasks.Task object used to issue the asynchronous call to the API. The caller is responsible for finishing the asynchronous call by e.g. accessing the Result property.

-Body (Aliases: Content)

Specifies the request body to send to the API endpoint. Tipically contains the JSON payload required by the API.

-Collection (Aliases: Organization)

Specifies the URL to the Team Project Collection or Azure DevOps Organization to connect to, a TfsTeamProjectCollection object (Windows PowerShell only), or a VssConnection object. You can also connect to an Azure DevOps Services organizations by simply providing its name instead of the full URL. For more details, see the Get-TfsTeamProjectCollection cmdlet. When omitted, it defaults to the connection set by Connect-TfsTeamProjectCollection (if any).

-Destination

Saves the API response to a file. If omitted, the response will be written to the stardard output stream.

-Method

Specifies the HTTP method to call the API endpoint. When omitted, defaults to “GET”.

-NoAutoUnwrap

Prevents the automatic expansion (unwrapping) of the ‘value’ property in the response JSON.

-Path

Specifies the path of the REST API to call. Tipically it is the portion of the URL after the name of the collection/organization, i.e. in the URL https://dev.azure.com/{organization}/_apis/projects?api-version=5.1 the path is “/_apis/projects”.

-Project

Specifies the name of the Team Project, its ID (a GUID), or a Microsoft.TeamFoundation.Core.WebApi.TeamProject object to connect to. When omitted, it defaults to the connection set by Connect-TfsTeamProject (if any). For more details, see the Get-TfsTeamProject cmdlet.

-QueryParameters (Aliases: Parameters)

Specifies a hashtable with additional query parameters to send to the API endpoint.

-Raw

Returns the API response as an unparsed string. If omitted, JSON responses will be parsed, converted and returned as objects (via ConvertFrom-Json).

-RequestContentType

Specifies the request body content type to send to the API. When omitted, defaults to “application/json”.

-ResponseContentType

Specifies the response body content type returned by the API. When omitted, defaults to “application/json”.

-Server

Specifies the URL to the Team Foundation Server to connect to, a TfsConfigurationServer object (Windows PowerShell only), or a VssConnection object. When omitted, it defaults to the connection set by Connect-TfsConfiguration (if any). For more details, see the Get-TfsConfigurationServer cmdlet.

-Team

Specifies the name of the Team, its ID (a GUID), or a Microsoft.TeamFoundation.Core.WebApi.WebApiTeam object to connect to. When omitted, it defaults to the connection set by Connect-TfsTeam (if any). For more details, see the Get-TfsTeam cmdlet.

-UseHost

Specifies an alternate host name for APIs not hosted in “dev.azure.com”, e.g. “vsaex.dev.azure.com” or “vssps.dev.azure.com”.

Related Links