background

Work Item Yönetimi (Part 1)

Herkese Merhaba

Bu yazımda Azure DevOps Servisine ait Rest API’lar ile Azure DevOps’da bulunan projelerinizin work itemları üzerinde neler yapabileceğinizi sizlerle paylaşacağım.

Öncelikle “Neden API’larla uğraşayım ki?” derseniz. Bunun için size birkaç sebep söyleyebilirim. Örneğin; bir product backlog itema ait tasklar içerisinde bulunan ‘Module’ isminde bir fieldımız olsun. Bu fielda pbi’ın title bilgisini yazdırmamız gerektiğini, bu işlemi ise birden fazla pbi için yapmamız gerektiğini varsayalım. Bu recursive işlemler yapmamızı gerektiren bir işlemdir. Yani her bir pbi için o field bilgisini al ve ona ait tasklara yazdır. Bu işlemi excelde yapmak oldukça güç olabilir. Heleki taska ait bir rule mevcutsa bunu yapmak pekde mümkün olmayabilir. Çünkü yüksek ihtimalle değişiklikleri publish ederken hata ile karşılaşaksınız. Ancak API lar ile bunu yapmanız sadece 5 dk Gerekli scripti yazdıktan sonra run tuşuna basın ve script işlemlerinizi yaparken siz başka işlerinizle ilgilenmeye devam edin

Neler Yapabiliriz?

Yeni bir work item oluşturmak, var olan bir work itemı silmek , fieldlarda güncelleme yapmak, belli bir sorguya göre istenilen work itemlarınızı listelemek ve bilgilerini görüntülemek gibi Azure DevOps’un önyüzünden yapabildiğiniz bir çok işlemi bu API servisleri ile yapabilmek mümkün. Nasıl mı? O zaman okumaya devam

İlk adım

Azure DevOps servislerine ait API’ları call edebilmek için projenize ait project collection seviyesinde kendiniz için bir personel access token generate etmeniz gerekmektedir. Bunun için aşağıdaki adımları izleyebilirsiniz:

Aşağıda gösterildiği gibi Profile Settings butonuna tıklayarak Personel access tokens listitemına basmalısınız.

Tokenların olduğu ekrana geldiğinizde New token butonuna basarak yeni bir token generate etmelisiniz.

Organization için işlem yapmak istediğiniz work itemların projesine ait organization(project collection) bilgisini seçmelisiniz.

Access tokenlar generate edildiği organizationa özeldir. O token ile başka bir organizationa ait bir proje için API invoke edilemez. Aksi taktirde 401 Unauthorized hatası alırsınız.

Token expire süresini dilediğiniz kadar seçebilirsiniz. Burada default değeri bırakılmıştır ve 30 gündür.

Burada Scope olarak bu token için full access yetkiside verebilirsiniz. Böylelikle bütün işlemleri bu token ile yapabilirsiniz. Ben bu yazı için Custom Define ile sadece work item yetkilerini enable ettim.

Create butonuna tıklayarak token generate edilir. Artık bu token bilgisini work item işlemleri için API ları invoke ederken header bilgisinde kullanabilirsiniz.

Bir work item oluşturma

Invoke edecğiniz API aşağıda verilmiştir.

PATCH
https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/${type}?api-version=5.1

Organization: Work itemlarınızın bulunduğu projeye ait organization ismi
Project: Work itemlarınızın bulunduğu proje ismi
Type: Create etmek istediğiniz work item tipiPeki yazdık bitti mi? Hayır Şimdi bu API’ı invoke edelim. Ben powershell scripti ile işlemlerimi yapacağım. Siz dilediğiniz programlama dilini kullanabilirsiniz.

Aşağıdaki powershell scriptinde Deneme projesi için task tipinde bir work item create etmektedir.

$witType="task"$apiadress = "https://dev.azure.com/kadriyetaylann/deneme/_apis/wit/workitems/`$$($witType)?api-version=5.1"$personalAccessToken = "2ojzcqzxxmkn6hxrt7lhog3lgfgiqxjyi5u37tcn4334xi4ofi3a"$token = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes(":$($personalAccessToken)"))$headers = @{authorization = "Basic $token" }$body="[{`"op`": `"add`",`"path`": `"/fields/System.Title`",`"value`": `"InvokeAPIDeneme1`"}]"Invoke-RestMethod -Uri $apiadress -Method Patch -Body $body -ContentType "application/json-patch+json" -Headers $headers

Scriptimizi biraz inceleyelim.

$witType: Create etmek istediğiniz work item type ismini string olarak bu parametreye değişken olarak atamalısınız
$apiadress: Invoke edeceğiniz API
$personalAccessToken: Azure DevOps üzerinden almış olduğunuz access token
$token: Encode edilmiş access token
$headers: Authorize olabilmek için encode edilmiş token bilgisi
$body: İstek atarken kullanılacak request body— Burada yapacağınız işlem(add,remove,update .. ), Field bilgisi ve o field için value değerini vermelisiniz.
op: Yapılacak işlem
path: Work item içindeki bir field bilgisi(Bu bir create işlemi olduğundan work item’ın title bilgisi verildi)
value: path parametresinde belirtilen field için value bilgisi

Son satırda ise API’a istek atılmaktadır.
Yukarıdaki script powershell’de çalıştırıldığında çıktı aşağıdaki çıktıya benzer bir çıktı olmalıdır.

Update İşlemi

Yukarıda oluşturmuş olduğumuz task work itemı için State bilgisini Active olarak update edelim.Bunun için aşağıdaki API kullanılmalı.

PATCH
https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}?api-version=5.1

Aşağıdaki kodu çalıştırdığınızda Status bilgisi update olacaktır.

$apiadress = "https://dev.azure.com/kadriyetaylann/deneme/_apis/wit/workitems/6?api-version=5.1"$personalAccessToken ="kng3gqpbax6kpku7kc2h5zi532jwxfm75wfj3gdgwxuxkemplk3a"$token = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes(":$($personalAccessToken)"))$headers = @{authorization = "Basic $token" }$body="[{`"op`": `"replace`",`"path`": `"/fields/System.State`",`"value`": `"Active`"}]"Invoke-RestMethod -Uri $apiadress -Method Patch -Body $body -ContentType "application/json-patch+json" -Headers $headers

Yukarıdaki scriptte apiadress ve body parametleri üzerinde değişiklik yapılmıştır.

Yukarıdaki script powershell’de çalıştırıldığında çıktı aşağıdaki çıktıya benzer bir çıktı olmalıdır.

Silme İşlemi

Yukarıda oluşturmuş olduğumuz work itemı silelim.

Bunun için aşağıdaki API kullanılmalı.

DELETE
https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}?api-version=5.1

Aşağıdaki kodu çalıştırdığınızda id’si 6 olan task work itemı silinecektir.

$apiadress = "https://dev.azure.com/kadriyetaylann/deneme/_apis/wit/workitems/6?api-version=5.1"$personalAccessToken ="kng3gqpbax6kpku7kc2h5zi532jwxfm75wfj3gdgwxuxkemplk3a"$token = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes(":$($personalAccessToken)"))$headers = @{authorization = "Basic $token" }Invoke-RestMethod -Uri $apiadress -Method Delete -ContentType "application/json-patch+json" -Headers $headers

Yukarıdaki script powershell’de çalıştırıldığında çıktı aşağıdaki çıktıya benzer bir çıktı olmalıdır.

Scriptler’e aşağıdaki GitHub linkinden de erişebilirsiniz.

Bu yazıda create, update ve delete işlemleri yapılmıştır. Sonraki yazılarımda Azure DevOps Query Editor’de hazırlamış olduğumuz queryleri API’lar aracılığı ile nasıl çalıştıracağımızdan bahsedeceğim.

İlgili yazıya buradan erişebilirsiniz :)

Bir sonraki yazımda görüşmek üzere :)

Reference

Nasıl yardımcı olabiliriz?