Share via

以程式設計方式建立服務掛勾訂用帳戶

  • 發行項

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

使用訂用帳戶 REST API ，您可以透過程式設計方式建立訂用帳戶，以在 Azure DevOps 專案中發生特定事件時，對外部/取用者服務執行動作。 例如，您可以建立訂用帳戶，以在建置失敗時通知您的服務。

支援的事件:

  • 組建已完成
  • 程式碼推送 (針對 Git 專案)
  • 提取要求建立或已更新 (針對 Git 專案)
  • 程式碼已簽入 (TFVC 專案)
  • 工作項目的建立、更新、刪除、還原或註解時間：

您可以在訂用帳戶上設定篩選，以控制哪些事件可觸發動作。 例如，您可以根據組建狀態來篩選組建已完成事件。 如需一組完整的支援事件和篩選選項，請參閱事件參考。

如需一組完整的支援取用者服務和動作，請參閱取用者參考。

必要條件

若要建立訂用帳戶，需要下列數據：

建立要求

建構 HTTP POST 要求的本文，以根據專案識別碼、事件、取用者和動作建立訂用帳戶。

請參閱下列建立訂用帳戶的範例要求，以在建WebSite.CI置失敗時將組建事件設為POSThttps://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": "74aeeed0-bf5d-48dc-893f-f862b80987e9",
    "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/hooks/subscriptions/74aeeed0-bf5d-48dc-893f-f862b80987e9",
    "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 版本相同。 未指定資源版本表示「最新發行」。 您應該一律指定資源版本，以確保一段時間的事件承載一致。

常見問題集

問：是否有服務可以手動訂閱？

A: 可以。 如需您可以從專案管理頁面訂閱之服務的詳細資訊，請參閱概 觀。

問：我可以使用 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; }
    }
}