InvokeRESTAPI@1 - 调用 REST API v1 任务

项目
04/29/2024

使用此任务调用 REST API 作为管道的一部分。

语法

# Invoke REST API v1
# Invoke a REST API as a part of your pipeline.
- task: InvokeRESTAPI@1
  inputs:
    connectionType: 'connectedServiceName' # 'connectedServiceName' | 'connectedServiceNameARM'. Alias: connectedServiceNameSelector. Required. Connection type. Default: connectedServiceName.
    serviceConnection: # string. Alias: connectedServiceName | genericService. Required when connectedServiceNameSelector = connectedServiceName. Generic service connection. 
    #azureServiceConnection: # string. Alias: connectedServiceNameARM | azureSubscription. Required when connectedServiceNameSelector = connectedServiceNameARM. Azure subscription. 
    method: 'POST' # 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'TRACE' | 'PATCH'. Required. Method. Default: POST.
    #headers: # string. Headers. 
    #body: # string. Optional. Use when method != GET && method != HEAD. Body. 
    #urlSuffix: # string. URL suffix and parameters. 
  # Advanced
    waitForCompletion: 'false' # 'true' | 'false'. Required. Completion event. Default: false.
    #successCriteria: # string. Optional. Use when waitForCompletion = false. Success criteria.

# Invoke REST API v1
# Invoke a REST API as a part of your pipeline.
- task: InvokeRESTAPI@1
  inputs:
    connectionType: 'connectedServiceName' # 'connectedServiceName' | 'connectedServiceNameARM'. Alias: connectedServiceNameSelector. Required. Connection type. Default: connectedServiceName.
    serviceConnection: # string. Alias: connectedServiceName. Required when connectedServiceNameSelector = connectedServiceName. Generic service connection. 
    #azureServiceConnection: # string. Alias: connectedServiceNameARM. Required when connectedServiceNameSelector = connectedServiceNameARM. Azure subscription. 
    method: 'POST' # 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'TRACE' | 'PATCH'. Required. Method. Default: POST.
    #headers: # string. Headers. 
    #body: # string. Optional. Use when method != GET && method != HEAD. Body. 
    #urlSuffix: # string. URL suffix and parameters. 
  # Advanced
    waitForCompletion: 'false' # 'true' | 'false'. Required. Completion event. Default: false.
    #successCriteria: # string. Optional. Use when waitForCompletion = false. Success criteria.

输入

connectionType - 连接类型
输入别名： connectedServiceNameSelector。 string. 必需。允许的值： connectedServiceName (泛型) 、 connectedServiceNameARM (Azure 资源管理器) 。默认值：connectedServiceName。

指定用于调用 REST API 的服务连接类型。选择“Azure 资源管理器”，为所有其他 API 调用 Azure 管理 API 或通用。

serviceConnection - 通用服务连接
输入别名： connectedServiceName | genericService。 string. 当 connectedServiceNameSelector = connectedServiceName 时，需要此选项。

指定为调用提供 baseUrl 的泛型服务连接，以及用于任务的授权。

serviceConnection - 通用服务连接
输入别名： connectedServiceName。 string. 当 connectedServiceNameSelector = connectedServiceName 时，需要此选项。

指定为调用提供 baseUrl 的泛型服务连接，以及用于任务的授权。

azureServiceConnection - Azure 订阅
输入别名： connectedServiceNameARM | azureSubscription。 string. 当 connectedServiceNameSelector = connectedServiceNameARM 时，需要此选项。

指定要配置和用于调用 Azure 管理 API 的 Azure 资源管理器订阅。

azureServiceConnection - Azure 订阅
输入别名： connectedServiceNameARM。 string. 当 connectedServiceNameSelector = connectedServiceNameARM 时，需要此选项。

指定要配置和用于调用 Azure 管理 API 的 Azure 资源管理器订阅。

method - 方法
string. 必需。允许的值：OPTIONS、GET、、HEAD、POSTPUT、DELETE、TRACE、PATCH。默认值：POST。

指定调用 API 的 HTTP 方法。

headers - 头
string. 默认值：{\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}。

定义 JSON 格式的标头。标头与发送到 API 的请求一起附加。

body - 身体
string. 可选。在时 method != GET && method != HEAD使用。

以 JSON 格式指定函数调用的请求正文。

urlSuffix - URL 后缀和参数
string.

指定要在进行 HTTP 调用时从泛型服务连接追加到 baseUrl 的字符串。

示例：如果服务连接 URL 为 https:...TestProj/_apis/Release/releases ，URL 后缀为 /2/environments/1，则服务连接 URL 变为 https:.../TestProj/_apis/Release/releases/2/environments/1。如果 URL 后缀为 ?definitionId=1&releaseCount=1，则服务连接 URL 变为 https//...TestProj/_apis/Release/releases?definitionId=1&releaseCount=1。

waitForCompletion - 完成事件
string. 必需。允许的值： true (回调) 、 false (ApiResponse) 。默认值：false。

指定任务报告完成的方式。允许的值为：

false - API 响应：当函数在 20 秒内返回成功且成功条件的计算结果为 true 时，报告完成。
true - 回调：当外部服务进行回调以更新时间线记录时，报告完成情况。

successCriteria - 成功条件
string. 可选。在时 waitForCompletion = false使用。

指定任务的成功条件。如果未定义条件，则响应内容不会影响结果。默认情况下，任务在调用返回 200 OK时传递。

示例：对于响应 {"status" : "successful"}，表达式可以是 eq(root['status'], 'successful')。详细了解如何指定条件。

任务控制选项

除了任务输入，所有任务都有控制选项。有关详细信息，请参阅控制选项和常见任务属性。

输出变量

无。

备注

注意

此任务只能在无代理作业中使用。

如果 API 返回成功且响应正文分析成功，或者 API 以成功更新时间线记录，则成功。

调用 REST API 任务不直接执行部署操作。相反，它允许调用任何通用 HTTP REST API 作为自动化管道的一部分，并选择性地等待它完成。

配置调用 REST API 任务

有关使用此任务的详细信息，请参阅审批和入口概述。

调用 Azure 管理 API 时使用哪些基 URL？

使用所选环境的 ResourceManagerEndpoint 调用 Azure 管理 API。例如 https://management.azure.com ，当订阅位于 AzureCloud 环境中时，使用。

选择“回调”作为完成事件时，任务应在哪里发出完成信号？

要发出完成信号，外部服务应将完成数据 POST 到以下管道 REST 终结点。

{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" }

有关详细信息，请参阅简单的 cmdline 应用程序。

此外，C# 帮助程序库可用于启用实时日志记录和管理无代理任务的任务状态。了解详细信息

是否可以使用响应正文作为另一个任务的输入？

否，因为此任务是无代理任务，使用 TFS 的内部 HttpRequest，它不会返回 HTTP 请求的内容。

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

在此示例中，当响应匹配我们的 successCriteria： eq (root[''count'']， ''1425''') 时，任务成功。

在管道定义中，选择省略号按钮 (...)，然后选择“添加无代理作业”。
在新的无代理作业中，选择 + 符号以添加新任务。
调用 REST API 任务的搜索。选择“添加”，将其添加到无代理作业。
选择 “连接类型” 和 “服务连接”。选择要使用的 HTTP 方法，然后选择 完成事件。还可以定义通过任务的成功条件。
完成后，选择“ 保存 & 队列 ”。