InvokeRESTAPI@1 - 叫用 REST API v1 工作

發行項
04/29/2024

使用此工作來叫用 REST API 作為管線的一部分。

Syntax

# 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 Resource Manager) 。預設值：connectedServiceName。

指定要用來叫用 REST API 的服務連線類型。選取 [Azure Resource Manager]，以針對所有其他 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 Resource Manager 訂用帳戶。

azureServiceConnection - Azure 訂用帳戶
輸入別名： connectedServiceNameARM。 string. 當 connectedServiceNameSelector = connectedServiceNameARM 時為必要。

指定要設定及用於叫用 Azure 管理 API 的 Azure Resource Manager 訂用帳戶。

method - 方法
string. 必要。允許的值：OPTIONS、GETHEAD、、DELETEPUTPOST、、 TRACEPATCH。預設值：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？

Azure 管理 API 是使用所選環境的 ResourceManagerEndpoint 來叫用。例如 https://management.azure.com ，當訂用帳戶位於 AzureCloud 環境中時使用。

選擇 [回呼 ] 做為完成事件時，工作應該在何處發出完成訊號？

若要發出完成訊號，外部服務應該將完成數據張貼到下列管線 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 方法，然後選取 [完成] 事件。您也可以定義要通過工作的準則成功。
完成時，選取 [儲存 & 佇列 ]。