Menentukan kueri dasar menggunakan OData Analytics
Layanan Azure DevOps | Azure DevOps Server 2022 - Azure DevOps Server 2019
Dengan menggunakan Analytics untuk Azure DevOps, Anda dapat membuat kueri dasar dan yang difilter untuk mengembalikan data yang menarik. Anda bisa menjalankan kueri ini langsung di browser Anda atau di dalam Power BI.
Artikel ini membangun informasi yang disediakan dalam Membuat kueri OData untuk referensi Analitik dan Metadata untuk Azure Boards Analytics. Selain itu, kueri dalam artikel ini difokuskan pada pengambilan set entitas pelacakan kerja, namun, prinsip-prinsip tersebut berlaku untuk mengkueri kumpulan entitas lain.
Dalam artikel ini Anda akan mempelajari cara menentukan kueri yang mengembalikan data berikut:
- Jumlah item (tidak ada data lain)
- Jumlah item dan data
- Properti yang ditentukan untuk Area atau Jalur Perulangan
- Kolom atau bidang terpilih
- Data yang difilter
- Mengembalikan data untuk bidang Identitas, Jalur Area, dan Jalur Iterasi
- Filter menurut properti navigasi
- Mengkueri rentang tanggal
- Pernyataan perluasan Nest
- Urutkan hasil, opsi orderby
Catatan
Layanan Analitik diaktifkan secara otomatis dan didukung dalam produksi untuk semua Layanan Azure DevOps. Integrasi dan akses Power BI ke umpan OData Dari Layanan Analitik umumnya tersedia. Kami mendorong Anda untuk menggunakannya dan memberi kami umpan balik.
Data yang tersedia bergantung pada versi. Versi terbaru yang didukung adalah v2.0
, dan versi pratinjau terbaru adalah v4.0-preview
. Untuk informasi selengkapnya, lihat Penerapan versi OData API.
Catatan
Layanan Analytics secara otomatis diinstal dan didukung dalam produksi untuk semua koleksi proyek baru untuk Azure DevOps Server 2020 dan versi yang lebih baru. Integrasi dan akses Power BI ke umpan OData Dari Layanan Analitik umumnya tersedia. Kami mendorong Anda untuk menggunakannya dan memberi kami umpan balik. Jika Anda meningkatkan dari Azure DevOps Server 2019, maka Anda dapat menginstal layanan Analytics selama peningkatan.
Data yang tersedia bergantung pada versi. Versi terbaru yang didukung adalah v2.0
, dan versi pratinjau terbaru adalah v4.0-preview
. Untuk informasi selengkapnya, lihat Penerapan versi OData API.
Catatan
Layanan Analitik sedang dalam pratinjau untuk Azure DevOps Server 2019. Anda dapat mengaktifkan atau menginstalnya untuk koleksi proyek. Integrasi dan akses Power BI ke umpan OData Layanan Analitik ada di Pratinjau. Kami mendorong Anda untuk menggunakannya dan memberi kami umpan balik.
Data yang tersedia bergantung pada versi. Versi terbaru yang didukung adalah v2.0
, dan versi pratinjau terbaru adalah v4.0-preview
. Untuk informasi selengkapnya, lihat Penerapan versi OData API.
Prasyarat
- Akses: Menjadi anggota proyek dengan setidaknya akses Dasar .
- Izin: Secara default, anggota proyek memiliki izin untuk mengkueri Analitik dan membuat tampilan.
- Untuk informasi selengkapnya tentang prasyarat lain mengenai pengaktifan layanan dan fitur serta aktivitas pelacakan data umum, lihat Izin dan prasyarat untuk mengakses Analitik.
Catatan
Dalam artikel ini, URL kueri OData didefinisikan untuk Layanan Azure DevOps. Untuk membuat kueri serupa untuk server lokal, lihat panduan yang disediakan dalam Membuat kueri OData untuk Analitik. Kami mendorong Anda untuk menyesuaikan kueri yang disediakan untuk organisasi dan proyek Anda agar terbiasa dengan mengkueri OData menggunakan browser Anda.
Mengembalikan jumlah item (tidak ada data lain)
Untuk mempelajari tentang jumlah item atau entitas yang ditentukan dalam organisasi atau proyek, tentukan $apply=aggregate($count as Count)
opsi kueri. Misalnya, kueri berikut mengembalikan jumlah proyek, item kerja, Jalur Area, dan pengguna yang ditentukan untuk organisasi.
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Projects?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/WorkItems?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Areas?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Users?$apply=aggregate($count as Count)
Tip
Kueri lintas proyek gagal saat pengguna yang menjalankan kueri tidak memiliki akses ke semua proyek. Baca selengkapnya tentang persyaratan dalam Kueri proyek dan cakupan organisasi.
Jumlah proyek
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(Count)"
value
0
@odata.id null
Count 28
Jumlah item kerja
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)"
value
0
@odata.id null
Count 1166
Jumlah area
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value
0
@odata.id null
Count 70
Jumlah pengguna
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value
0
@odata.id null
Count 16
Mengembalikan jumlah item dan data
Untuk mengembalikan jumlah item bersama dengan pilih data untuk item, tentukan $count=true
opsi kueri. Misalnya, kueri berikut mengembalikan jumlah item kerja, Jalur Area, dan pengguna yang ditentukan untuk proyek bersama dengan properti yang ditentukan. Untuk properti yang valid, lihat Referensi metadata untuk Azure Boards Analytics dan Tanggal Kalender, Proyek, dan Referensi metadata Pengguna untuk Azure DevOps Analytics.
Tip
Jika Anda tidak menentukan properti yang akan dikembalikan, Analytics akan mengembalikan semua properti yang ditentukan untuk jenis entitas yang ditentukan.
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/WorkItems?$count=true&$select=WorkItemId,Title,WorkItemType
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/Areas?$count=true&$select=AreaName,AreaPath
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/Users?$count=true&$select=UserName,UserEmail
Properti Area atau Perulangan
Untuk mencari AreaSK
atau IterationSK
, atau properti lain dari Jalur Area atau Jalur Perulangan, gunakan kueri berikut.
Mengembalikan AreaSK untuk Jalur Area tertentu
Kueri berikut menentukan untuk mengembalikan properti yang ditentukan untuk Fabrikam Fiber\Service Delivery\Internet Area Path.AreaSK
Untuk menentukan properti lain yang Areas
ditentukan untuk kumpulan entitas, lihat Referensi metadata untuk Azure Boards Analytics, Area.
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Areas?$filter=AreaPath eq 'Fabrikam Fiber\Service Delivery\Internet' &$select=AreaSK
Kueri mengembalikan data berikut.
{
"@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Areas(AreaSK)",
"value": [
{
"AreaSK": "637dc203-0549-4415-9663-b6358ac27d21"
}
]
}
Mengembalikan IterationSK untuk Jalur Iterasi tertentu
Kueri berikut menentukan untuk mengembalikan properti yang IterationSK
ditentukan untuk Jalur Perulangan Fabrikam Fiber\Release 1\Sprint 3. Untuk menentukan properti lain yang Iterations
ditentukan untuk kumpulan entitas, lihat Referensi metadata untuk Azure Boards Analytics, Iterasi.
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Iterations?$filter=IterationPath eq 'Fabrikam Fiber\Release 1\Sprint 3' &$select=IterationSK
Kueri mengembalikan data berikut.
{
"@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Iterations(IterationSK)",
"value": [
{
"IterationSK": "862e961a-ac7a-4fcc-9ebc-8afd0c12fed5"
}
]
}
Mengembalikan properti atau bidang tertentu
Untuk mengembalikan properti tertentu atau bidang item kerja, tambahkan $select
klausa yang menentukan nama properti.
Misalnya, untuk mengembalikan ID Item Kerja, Tipe Item Kerja, Judul, dan Status item kerja, tambahkan klausa berikut ke kueri Anda. Klausa ini menentukan properti yang sesuai dengan bidang bernama.
Catatan
Nama properti tidak berisi spasi apa pun. Kueri Anda akan gagal jika Anda menambahkan spasi. Kueri OData memerlukan perhatian diberikan pada spasi dan casing. Untuk memahami bagaimana properti bidang kustom diberi label, lihat Referensi metadata untuk Azure Boards, Properti kustom.
Di sini kami menentukan untuk mengembalikan tiga item kerja teratas.
https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$top=3
Analitik mengembalikan data berikut.
@odata.context "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value
0
WorkItemId 462
Title "Test case"
WorkItemType "Test Case"
State "Design"
1
WorkItemId 491
Title "Change color settings"
WorkItemType "Shared Steps"
State "Active"
2
WorkItemId 461
Title "Test impediment"
WorkItemType "Impediment"
State "Open"
.
Memfilter data Anda
Untuk memfilter kumpulan entitas untuk mengembalikan item tertentu, tentukan $filter
klausa yang menentukan kriteria yang harus dipenuhi item. Membangun kueri terakhir, di sini kita menambahkan klausa filter untuk hanya mengembalikan jenis item kerja Fitur yang berada dalam status Sedang Berlangsung .
/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=State eq 'In Progress'
https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemType eq 'Feature' and State eq 'In Progress'&$select=WorkItemId,Title,AssignedTo,State
Analitik mengembalikan data berikut.
@odata.context "https://analytics.dev.azure.com/kelliott/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,State)"
value
0
WorkItemId 380
Title "Refresh web look, feel, performance factors"
State "In Progress"
1
WorkItemId 480
Title "Customer Phone - Phase 1"
State "In Progress"
2
WorkItemId 493
Title "Change initial view"
State "In Progress"
3
WorkItemId 479
Title "Customer Web - Phase 1"
State "In Progress"
4
WorkItemId 551
Title "Mobile feedback"
State "In Progress"
Tentukan beberapa klausa filter
Anda dapat menggunakan AND
dan OR
untuk menentukan beberapa klausa filter.
Misalnya, kueri berikut menentukan untuk mengembalikan item kerja jenis Cerita Pengguna, Bug, dan Pekerjaan Backlog (jenis item kerja kustom) yang berada di status Baru, Berkomitmen, atau Aktif . Gunakan tanda kurung untuk mengelompokkan klausa filter sesuai kebutuhan.
Selain itu, Anda dapat menerapkan berbagai fungsi seperti contains
, , startswith
endswith
dan banyak lagi. Lihat fitur dan klausa OData yang didukung, Fungsi yang didukung.
Mengembalikan data untuk bidang Identitas, Jalur Area, dan Jalur Iterasi
Properti tertentu dikaitkan dengan properti navigasi dan tidak dapat diakses secara langsung menggunakan pernyataan .$select
Anda harus menggunakan $expand
pernyataan untuk mengembalikan data yang diminati. Properti ini sering dikaitkan dengan beberapa propertinya sendiri. Misalnya, dengan bidang Identitas, Anda dapat menentukan untuk mengembalikan nama pengguna atau email pengguna.
Tabel berikut ini menyediakan contoh cara memperluas beberapa properti ini.
Jenis bidang | Properti yang dirujuk | Contoh klausa untuk disertakan |
---|---|---|
DateTime | DateSK |
$expand=CreatedDate($select=Date) atau$expand=CreatedDate($select=WeekStartingDate) |
Identitas | UserSK |
$expand=AssignedTo($select=UserName) atau$expand=AssignedTo($select=UserEmail) |
Luas | AreaSK |
$expand=Area($select=AreaName) atau$expand=Area($select=AreaPath) |
Perulangan | IterationSK |
$expand=Iteration($select=IterationName) atau$expand=Iteration($select=IterationPath) atau$expand=Iteration($select=StartDate) |
Project | ProjectSK |
$expand=Project($select=ProjectName) |
Tim | TeamSK |
$expand=Teams($select=TeamName) |
Untuk menentukan beberapa properti yang perlu diperluas, Anda menentukannya dalam satu klausa perluas dalam daftar yang dibatasi komandan.
$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath)
Filter menurut properti navigasi
Saat Anda menentukan properti navigasi sebagai bagian dari kriteria filter, Anda harus menentukannya dalam format yang diperlukan.
Misalnya, klausul berikut menentukan untuk memfilter item kerja berdasarkan Iterasi 1 yang ditentukan untuk proyek.
/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'
Dalam contoh ini, Iteration
adalah nama properti navigasi dan IterationPath
sesuai dengan jalur lengkap untuk perulangan. Untuk menggunakan entitas lain sebagai filter, letakkan properti navigasi diikuti dengan garis miring diikuti dengan nama bidang untuk difilter.
Dan, berikut adalah kueri OData lengkap:
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'
Berikut adalah contoh lain yang meminta lima item kerja teratas di bawah Fabrikam Fiber\Service Delivery\Voice Area Path dikembalikan.
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Area/AreaPath eq 'Fabrikam Fiber\Service Delivery\Voice'&$select=WorkItemId, WorkItemType, Title, State&$orderby=WorkItemId asc
@odata.context "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value
0
WorkItemId 361
Title "Hello World Web Site"
WorkItemType "Product Backlog Item"
State "Removed"
1
WorkItemId 362
Title "Resume"
WorkItemType "Product Backlog Item"
State "New"
2
WorkItemId 363
Title "Welcome back page"
WorkItemType "Product Backlog Item"
State "Done"
3
WorkItemId 365
Title "Pause"
WorkItemType "Feature"
State "New"
4
WorkItemId 374
Title "Fix performance issues"
WorkItemType "Task"
State "To Do"
Tip
Anda tidak dapat menggunakan properti navigasi secara langsung dalam $select
pernyataan. Sebagai gantinya, Anda perlu menggunakan $expand
.
Contoh pemfilteran sebelumnya untuk Jalur Perulangan tidak mengembalikan jalur iterasi karena terkandung dalam entitas terkait. Untuk mengembalikan data dalam entitas terkait, tambahkan $expand
pernyataan:
/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration
Dan berikut adalah contoh yang mengembalikan informasi yang ditetapkan ke ID item kerja 480.
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&&$expand=Iteration
@odata.context "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)"
value
0
WorkItemId 480
Title "Customer Phone - Phase 1"
WorkItemType "Feature"
State "In Progress"
Iteration
ProjectSK "56af920d-393b-4236-9a07-24439ccaa85c"
IterationSK "c7063041-ff3a-4d7f-bb46-c433c7030d59"
IterationId "c7063041-ff3a-4d7f-bb46-c433c7030d59"
IterationName "Sprint 1"
Number 55297
IterationPath "Fabrikam Fiber\\Release 1\\Sprint 1"
StartDate "2022-01-17T00:00:00-08:00"
EndDate "2022-02-04T23:59:59.999-08:00"
IterationLevel1 "Fabrikam Fiber"
IterationLevel2 "Release 1"
IterationLevel3 "Sprint 1"
IterationLevel4 null
IterationLevel5 null
IterationLevel6 null
IterationLevel7 null
IterationLevel8 null
IterationLevel9 null
IterationLevel10 null
IterationLevel11 null
IterationLevel12 null
IterationLevel13 null
IterationLevel14 null
Depth 2
IsEnded true
AnalyticsUpdatedDate "2022-01-18T22:18:58.17Z"
Seperti yang Anda lihat, Jalur Perulangan diperluas dalam hasil dan semua data iterasi dikembalikan. Mungkin lebih banyak data dari yang Anda inginkan.
Untuk mengembalikan lebih sedikit $select
data, tambahkan pernyataan terhadap iterasi juga:
/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration($select=Name,IterationPath)
Kemudian mengembalikan data berikut.
{
"@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration,Iteration(Name,IterationPath))",
"value":[
{
"WorkItemId":10000,
"WorkItemType":"Task",
"Title":"Some title",
"State":"Completed",
"Iteration":{
"Name":"Sprint 55",
"IterationPath":"Fabrikam\\Sprints\\Sprint 55"
}
}
]
}
Mengkueri rentang tanggal
Contoh berikut mengembalikan item kerja yang Tanggal Diubahnya lebih besar dari sama dengan 1 Januari 2021.
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-01-01Z
Contoh berikut mengembalikan item kerja yang Tanggal Diubah terjadi selama minggu 26 April hingga 30 April 2021.
https://analytics.dev.azure.com{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-04-26Z&ChangedDate le 2021-04-30Z
Pernyataan perluasan Nest
Di OData, Anda dapat menyarangkan $expand
pernyataan. Misalnya, Anda dapat menulis pernyataan kueri sebelumnya untuk menampilkan proyek perulangan adalah bagian dari:
/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($expand=Project)
Ini mengembalikan JSON berikut:
{
"@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
"value":[
{
"WorkItemId":10000,
"Revision":3,
"Watermark":283397,
"Title":"Production deployment and testing for Entitlement API v2 and Subscriber database",
"WorkItemType":"Task",
"ChangedDate":"2014-07-10T19:29:58.41Z",
"CreatedDate":"2014-04-19T22:44:58.31Z",
"State":"Completed",
"Reason":"Completed",
"Priority":2,
"CompletedWork":10.0,
"OriginalEstimate":20.0,
"Count":1,
"Iteration":{
"IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46",
"Name":"Sprint 55",
"Number":13021,
"IterationPath":"Fabrikam\\Sprints\\Sprint 55",
"StartDate":"2013-09-23T00:00:00Z",
"EndDate":"2013-10-11T00:00:00Z",
"IterationLevel1":"Fabrikam",
"IterationLevel2":" Sprints",
"IterationLevel3":"Sprint 55",
"Level":2,
"IsDeleted":false,
"Project":{
"ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
"ProjectName":"Fabrikam",
"IsDeleted":false
}
}
}
]
}
Anda juga dapat menggabungkan $expand
pernyataan dan $select
. Misalnya, Anda dapat mengubah kueri sebelumnya untuk hanya mengembalikan Nama Iterasi dan Jalur Perulangan:
/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($select=IterationId,IterationPath;$expand=Project)
Ini mengembalikan JSON berikut:
{
"@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(Iteration(IterationId,IterationPath,Project))",
"value":[
{
"WorkItemId":10000,
"Revision":3,
"Watermark":283397,
"Title":"Production deployment and testing for Entitlement API v2 and Subscriber database","WorkItemType":"Task",
"ChangedDate":"2014-07-10T19:29:58.41Z",
"CreatedDate":"2014-04-19T22:44:58.31Z",
"State":"Completed",
"Reason":"Completed",
"Priority":2,
"CompletedWork":10.0,
"OriginalEstimate":20.0,
"Count":1,
"Iteration":{
"IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46","IterationPath":"Fabrikam\\Sprints\\Sprint 55",
"Project":{
"ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
"ProjectName":"Fabrikam",
"IsDeleted":false
}
}
}
]
}
Perhatikan bahwa hasilnya di sini hanya menunjukkan IterationId dan IterationPath dan bahwa Proyek adalah objek berlapis dalam hasil JSON. Item kunci lain yang perlu diperhatikan adalah URL itu sendiri. Saat menggunakan $select
pernyataan dan $expand
klausa, Anda harus menggunakan titik koma (;) sebelum $expand
. Hal lain akan mengakibatkan kesalahan.
Urutkan hasil, orderby
opsi
$orderby
Tentukan opsi untuk mengurutkan hasil Anda atau tentukan urutan di mana hasil dikembalikan. Anda dapat mengurutkan dalam urutan naik atau turun menggunakan kata kunci asc
atau desc
, masing-masing. Beberapa contoh ditampilkan
Urutkan menurut | Klausa untuk disertakan |
---|---|
ID item pekerjaan | /WorkItems?$orderby=WorkItemId |
ID item kerja turun | /WorkItems?$orderby=WorkItemId desc |
Jenis item kerja dan Status | /WorkItems?$orderby=WorkItemType,State |