Membuat langganan hook layanan secara terprogram
Layanan Azure DevOps | Azure DevOps Server 2022 - Azure DevOps Server 2019
Menggunakan REST API Langganan , Anda dapat secara terprogram membuat langganan yang melakukan tindakan pada layanan eksternal/konsumen saat peristiwa tertentu terjadi dalam proyek Azure DevOps. Misalnya, Anda bisa membuat langganan untuk memberi tahu layanan Anda saat build gagal.
Peristiwa didukung:
- Build selesai
- Kode didorong (bagi proyek Git)
- Permintaan pull membuat atau memperbarui (bagi proyek Git)
- Kode telah dicek masuk (proyek TFVC)
- Item kerja dibuat, diperbarui, dihapus, dipulihkan, ataupun dikomentari
Anda bisa mengonfigurasi filter pada langganan Anda untuk mengontrol peristiwa mana yang memicu tindakan. Misalnya, Anda bisa memfilter peristiwa build yang selesai berdasarkan status build. Untuk memperoleh sekumpulan lengkap peristiwa yang didukung dan opsi filter, harap lihat Referensi peristiwa.
Untuk serangkaian lengkap layanan dan tindakan konsumen yang didukung, harap lihat Referensi konsumen.
Prasyarat
Untuk membuat langganan, data berikut diperlukan:
- ID Proyek. Gunakan Project REST API untuk mendapatkan ID proyek.
- ID peristiwa dan pengaturan. Lihat Referensi peristiwa.
- ID dan pengaturan konsumen dan tindakan. Lihat Referensi konsumen.
Membuat permintaan
Buat isi permintaan HTTP POST untuk membuat langganan berdasarkan ID proyek, peristiwa, konsumen, dan tindakan.
Lihat contoh permintaan berikut untuk membuat langganan yang menyebabkan peristiwa build menjadi POST https://myservice/event saat build WebSite.CI gagal.
Permintaan
{
"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"
},
}
Sebaiknya gunakan URL HTTPS aman untuk keamanan data privat di objek JSON.
Respons Lihat respons berikut terhadap permintaan untuk membuat langganan:
{
"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"
}
}
Jika permintaan langganan gagal, Anda mendapatkan kode respons HTTP 400 dengan pesan yang memiliki detail lebih lanjut.
Apa yang terjadi ketika peristiwa terjadi?
Saat peristiwa terjadi, semua langganan yang diaktifkan dalam proyek dievaluasi, dan tindakan konsumen dilakukan untuk semua langganan yang cocok.
Versi sumber daya (tingkat lanjut)
Penerapan versi sumber daya berlaku saat API dalam pratinjau. Untuk sebagian besar skenario, menentukan 1.0 bahwa versi sumber daya adalah rute paling aman.
Payload peristiwa yang dikirim ke konsumen tertentu, seperti Webhook, Azure Bus Layanan, dan Azure Storage, mencakup representasi JSON dari sumber daya subjek (misalnya, build atau item kerja). Representasi sumber daya ini dapat memiliki bentuk atau versi yang berbeda.
Anda dapat menentukan versi sumber daya yang ingin Anda kirim ke layanan konsumen melalui resourceVersion bidang pada langganan.
Versi sumber daya sama dengan versi API. Tidak menentukan versi sumber daya berarti "rilis terbaru". Anda harus selalu menentukan versi sumber daya, yang memastikan payload peristiwa yang konsisten dari waktu ke waktu.
Tanya Jawab Umum
T: Apakah ada layanan yang dapat saya berlangganan secara manual?
J: Ya. Untuk informasi selengkapnya tentang layanan yang dapat Anda berlangganan dari halaman administrasi untuk proyek, lihat Gambaran Umum.
T: Apakah ada pustaka C# yang bisa saya gunakan untuk membuat langganan?
J: Tidak, tetapi berikut adalah sampel untuk membantu Anda memulai.
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; }
}
}