以程式方式建立服務鉤子訂閱
Azure DevOps Services |Azure DevOps Server 2022 - Azure DevOps Server 2019
使用 訂用帳戶 REST API ，您可以透過程式設計方式建立訂用帳戶，以在 Azure DevOps 專案中發生特定事件時，對外部/取用者服務執行動作。 例如，您可以建立訂用帳戶，以在組建失敗時通知您的服務。
支援的事件：
- 建置已完成
- 推送的程式代碼（適用於 Git 專案）
- 拉取請求建立或更新（針對 Git 專案）
- 程式碼已簽入（TFVC 專案）
- 已建立、更新、刪除、還原或批注的工作專案
您可以在訂用帳戶上設定篩選，以控制觸發動作的事件。 例如，您可以根據組建狀態篩選組建已完成事件。 如需一組完整的支援事件和篩選選項，請參閱 事件參考。
如需完整的支援消費者服務和動作，請參閱 消費者參考。
先決條件
| 類別 | 要求 |
|---|---|
| 專案存取 | Project 成員。 |
| 數據 | - 項目識別碼。 使用 專案 REST API 來取得專案標識碼。 - 事件識別碼和設定。 請參看 事件參考資料。 - 取用者和動作識別碼和設定。 請參閱 消費者參考。 |
建立請求
建構 HTTP POST 要求的本文，以根據專案識別碼、事件、取用者和動作建立訂用帳戶。
請參閱下列範例要求，該要求用於建立一個訂用帳戶，當建置 WebSite.CI 失敗時，此訂閱將讓建置事件 POST 至 https://myservice/event。
要求
{
"publisherId": "tfs",
"eventType": "build.complete",
"resourceVersion": "1.0",
"consumerId": "webHooks",
"consumerActionId": "httpRequest",
"publisherInputs": {
"buildStatus": "failed",
"definitionName": "WebSite.CI",
"projectId": "56479caf-1eeb-4bca-86ab-aaa6f29399d9",
},
"consumerInputs": {
"url": " https://myservice/event"
},
}
強烈建議針對 JSON 物件中私人數據的安全性使用安全的 HTTPS URL。
回應 請參閱下列回應以建立訂用帳戶的要求：
{
"id": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/hooks/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"publisherId": "tfs",
"eventType": "build.complete",
"resourceVersion": "1.0",
"consumerId": "webHooks",
"consumerActionId": "httpRequest",
"createdBy": {
"id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
},
"createdDate": "2014-03-28T16:10:06.523Z",
"modifiedBy": {
"id": "1c4978ae-7cc9-4efa-8649-5547304a8438"
},
"modifiedDate": "2014-04-25T18:15:26.053Z",
"publisherInputs": {
"buildStatus": "failed",
"definitionName": "WebSite.CI",
"hostId": "17f27955-99bb-4861-9550-f2c669d64fc9",
"projectId": "56479caf-1eeb-4bca-86ab-aaa6f29399d9",
"tfsSubscriptionId": "29cde8b4-f37e-4ef9-a6d4-d57d526d82cc"
},
"consumerInputs": {
"url": "http://myservice/event"
}
}
如果訂用帳戶要求失敗，您會收到 HTTP 回應碼 400，其中包含具有進一步詳細數據的訊息。
事件發生時會發生什麼事？
事件發生時，會評估專案中所有已啟用的訂用帳戶，並針對所有相符的訂用帳戶執行取用者動作。
資源版本 （進階）
當 API 處於預覽狀態時，適用資源版本設定。 在大部分情況下，將 1.0 指定為資源版本是最安全的路由。
傳送給特定使用者的事件負載，例如 Webhook、Azure 服務總線和 Azure 儲存體，包含主體資源的 JSON 表示法（例如組建或工作專案）。 此資源的表示法可以有不同的形式或版本。
您可以透過訂用帳戶上的 [resourceVersion] 欄位，指定您想要傳送給取用者服務的資源版本。
資源版本與 API 版本相同。 未指定資源版本表示「最新發行」。 您應該一律指定資源版本，以確保一段時間的事件承載一致。
常見問題
問：是否有服務可以手動訂閱？
答：是的。 如需您可以從專案管理頁面訂閱之服務的詳細資訊，請參閱 概觀。
問：我可以使用 C# 連結庫來建立訂用帳戶嗎？
不過，這裡有一個範例可以幫助你開始。
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Mvc;
namespace Microsoft.Samples.VisualStudioOnline
{
public class ServiceHookEventController : Controller
{
// POST: /ServiceHookEvent/workitemcreated
[HttpPost]
public HttpResponseMessage WorkItemCreated(Content workItemEvent)
{
//Grabbing the title for the new workitem
var value = RetrieveFieldValue("System.field", workItemEvent.Resource.Fields);
//Acknowledge event receipt
return new HttpResponseMessage(HttpStatusCode.OK);
}
/// <summary>
/// Gets the value for a specified work item field.
/// </summary>
/// <param name="key">Key used to retrieve matching value</param>
/// <param name="fields">List of fields for a work item</param>
/// <returns></returns>
public String RetrieveFieldValue(String key, IList<FieldInfo> fields)
{
if (String.IsNullOrEmpty(key))
return String.Empty;
var result = fields.Single(s => s.Field.RefName == key);
return result.Value;
}
}
public class Content
{
public String SubscriptionId { get; set; }
public int NotificationId { get; set; }
public String EventType { get; set; }
public WorkItemResource Resource { get; set; }
}
public class WorkItemResource
{
public String UpdatesUrl { get; set; }
public IList<FieldInfo> Fields { get; set;}
public int Id { get; set; }
public int Rev { get; set; }
public String Url { get; set; }
public String WebUrl { get; set; }
}
public class FieldInfo
{
public FieldDetailedInfo Field { get; set; }
public String Value { get; set; }
}
public class FieldDetailedInfo
{
public int Id { get; set; }
public String Name { get; set; }
public String RefName { get; set; }
}
}