InvokeRESTAPI@1 - Invoke REST API v1 task

Artikel
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"PlanUrl": "$(system.CollectionUri)", \n"ProjectId": "$(system.TeamProjectId)", \n"HubName": "$(system.HostType)", \n"PlanId": "$(system.PlanId)", \n"JobId": "$(system.JobId)", \n"TimelineId": "$(system.TimelineId)", \n"TaskInstanceId": "$(system.TaskInstanceId)", \n"AuthToken": "$(system.AccessToken)"\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.

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

urlSuffix - Url suffix and parameters
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 - Completion event
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 pipeines.

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.

steps:
- task: InvokeRESTAPI@1
  displayName: 'Invoke REST API: GET'
  inputs:
    serviceConnection: 'generic_demo'
    method: GET
    successCriteria: 'eq(root[''count''], ''1425'')'

In this example, the task succeeds when the response matched our successCriteria: eq(root[''count''], ''1425'').

From your pipeline definition, select the ellipsis button (...), and then select Add an agentless job.
In your new agentless job, select the + sign to add a new task.
Search for the Invoke REST API task. Select Add to add it to your agentless job.
Select your Connection type and your Service connection. Select the HTTP Method that you want to use, and then select a Completion event. You can also define a success a criteria to pass the task.
Select Save & queue when you are done.