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

[アーティクル]
04/04/2024

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": "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 バージョンと同じです。リソースバージョンを指定しない場合は、"最新リリース" を意味します。リソースのバージョンを常に指定する必要があります。これにより、一定のイベントペイロードが一定期間にわたって保証されます。

よく寄せられる質問

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

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

次の方法で共有

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

前提条件

要求を作成する

イベントが発生するとどうなりますか?

リソースのバージョン (詳細)

よく寄せられる質問

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

フィードバック

その他のリソース

次の方法で共有

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

前提条件

要求を作成する

イベントが発生するとどうなりますか?

リソースのバージョン (詳細)

よく寄せられる質問

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

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

関連記事

フィードバック

その他のリソース

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