プログラムでサービス フック サブスクリプションを作成する

  • [アーティクル]

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

サブスクリプション REST API を使用すると、Azure DevOps プロジェクトで特定のイベントが発生したときに外部/コンシューマー サービスに対してアクションを実行するサブスクリプションをプログラムで作成できます。 たとえば、ビルドが失敗したときにサービスに通知するサブスクリプションを作成できます。

サポートされるイベント:

  • ビルドの完了
  • コードのプッシュ (Git プロジェクトの場合)
  • pull request の作成または更新 (Git プロジェクトの場合)
  • コードのチェックイン (TFVC プロジェクト)
  • 作業項目の作成、更新、削除、復元、またはコメント

サブスクリプションに対するフィルターを構成して、アクションをトリガーするイベントを制御できます。 たとえば、ビルド状態に基づいてビルド完了イベントをフィルター処理できます。 サポートされているイベントとフィルター オプションの詳細については、イベント リファレンスのページを参照してください。

サポートされるコンシューマー サービスとアクションの詳細については、コンシューマー リファレンスのページを参照してください。

前提条件

サブスクリプションを作成するには、次のデータが必要です。

  • プロジェクト ID。 Project REST API を使用してプロジェクト ID を取得します。
  • イベント ID と設定。 イベントリファレンスを 参照してください。
  • コンシューマー ID とアクション ID と設定。 コンシューマーのリファレンスを 参照してください。

要求を作成する

プロジェクト ID、イベント、コンシューマー、アクションに基づいてサブスクリプションを作成する HTTP POST 要求の本文を作成します。

ビルドが失敗したときにビルド イベントを POST するサブスクリプションを作成する要求の例を次にhttps://myservice/eventWebSite.CI示します。

Request

{
    "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 Service Bus、Azure Storage などの特定のコンシューマーに送信されるイベント ペイロードには、サブジェクト リソース (ビルドや作業項目など) の JSON 表現が含まれます。 このリソースの表現は、異なる形式またはバージョンを持つことができます。

サブスクリプションのフィールドを使用して、コンシューマー サービスに送信するリソースの resourceVersion バージョンを指定できます。 リソースのバージョンは API バージョンと同じです。 リソース バージョンを指定しない場合は、"最新リリース" を意味します。 リソースのバージョンを常に指定する必要があります。これにより、一定のイベント ペイロードが一定期間にわたって保証されます。

よく寄せられる質問

Q: 手動でサブスクライブできるサービスはありますか?

回答: はい。 プロジェクトの管理ページからサブスクライブできるサービスの詳細については、「概要」を参照してください。

Q: サブスクリプションの作成に使用できる C# ライブラリはありますか。

A: いいえ。開始するのに役立つサンプルを次に示します。

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; }
    }
}