InvokeRESTAPI@0 - Invoke REST API v0 task

Article
02/27/2024

Use this task to invoke a REST API as a part of your pipeline.

Inputs

serviceConnection - Generic endpoint
Input alias: connectedServiceName. string. Required.

Specifies the generic service connection that provides the baseURL for the call and the authorization to use for the task.

method - Method
string. Required. Allowed values: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, PATCH. Default value: POST.

Specifies the HTTP method that invokes the API.

headers - Headers
string. Default value: {\n"Content-Type":"application/json"\n}.

Defines the header in JSON format. The header is attached with the request sent to the API.

body - Body
string. Optional. Use when method != GET && method != HEAD. Default value: {"JobId": "$(system.jobId)", "PlanId": "$(system.planId)", "TimelineId": "$(system.timelineId)", "ProjectId": "$(system.teamProjectId)", "VstsUrl": "$(system.CollectionUri)","AuthToken": "$(system.AccessToken)"}.

Specifies the request body for the function call in JSON format.

urlSuffix - Url suffix string
string.

Specifies the string to append to the baseUrl from the generic service connection while making the HTTP call.

Example: If the service connection URL is https:...TestProj/_apis/Release/releases and the URL suffix is /2/environments/1, the service connection URL becomes https:.../TestProj/_apis/Release/releases/2/environments/1. If the URL suffix is ?definitionId=1&releaseCount=1, then the service connection URL becomes https//...TestProj/_apis/Release/releases?definitionId=1&releaseCount=1.

waitForCompletion - Complete based on
string. Required. Allowed values: true (Callback), false (ApiResponse). Default value: false.

Specifies how the task reports completion. The allowed values are:

false - API response: Reports completion when the function returns success within 20 seconds, and the success criteria evaluates to true.
true - Callback: Reports completion when the external service makes a callback to update the timeline record.

successCriteria - Success criteria
string. Optional. Use when waitForCompletion = false.

Specifies the task's criteria for success. The response content does not influence the result if no criteria is defined. By default, the task passes when the call returns 200 OK.

Example: For response {"status" : "successful"}, the expression can be eq(root['status'], 'successful'). Learn more about specifying conditions.

Task control options

All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.

Output variables

None.

Remarks

Note

This task can be used only in an agentless job.

Note

This task is available in both classic build and release pipelines starting with TFS 2018.2 In TFS 2018 RTM, this task is available only in classic release pipelines.

Succeeds if the API returns success and the response body parsing is successful, or when the API updates the timeline record with success.

The Invoke REST API task does not perform deployment actions directly. Instead, it allows you to invoke any generic HTTP REST API as part of the automated pipeline and, optionally, wait for it to be completed.

Configuring an Invoke REST API task

For more information about using this task, see Approvals and gates overview.

What base URLs are used when invoking Azure Management APIs?

Azure management APIs are invoked using ResourceManagerEndpoint of the selected environment. For example https://management.Azure.com is used when the subscription is in an AzureCloud environment.

Where should a task signal completion when Callback is chosen as the completion event?

To signal completion, the external service should POST completion data to the following pipelines REST endpoint.

{planUri}/{projectId}/_apis/distributedtask/hubs/{hubName}/plans/{planId}/events?api-version=2.0-preview.1

**Request Body**
 { "name": "TaskCompleted", "taskId": "taskInstanceId", "jobId": "jobId", "result": "succeeded" }

See this simple cmdline application for specifics.

In addition, a C# helper library is available to enable live logging and managing task status for agentless tasks. Learn more

Can I use the response body as the input for another task?

No, as this task is an agentless task and uses TFS's internal HttpRequest, which doesn't return the content of the HTTP request.

Requirements

Requirement	Description
Pipeline types	YAML, Classic build, Classic release
Runs on	Server, ServerGate
Demands	None
Capabilities	This task does not satisfy any demands for subsequent tasks in the job.
Command restrictions	Any
Settable variables	Any
Agent version	All supported agent versions.
Task category	Deploy

Share via