プログラムによるサービス フック サブスクリプションの作成

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

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

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

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

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

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

前提 条件

要求を作成する

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

ビルド WebSite.CI が失敗したときに、ビルド イベントを https://myservice/event に POST するサブスクリプションを作成するための要求の例は以下の通りです。

要求

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

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

FAQ

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

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

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

関連記事

• サービス フック を承認する
• コンシューマー
• イベント
• トラブルシューティングとよくある質問