Menentukan kueri dasar menggunakan OData Analytics

Layanan Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022

Gunakan kueri Analitik OData untuk mengambil data pelacakan kerja dari Azure DevOps di browser Anda atau di alat klien seperti Excel dan Power BI. Artikel ini membahas penghitungan item, memilih bidang tertentu dengan $select, memfilter dengan $filter, memperluas properti navigasi dengan $expand, mengkueri rentang tanggal, dan mengurutkan dengan $orderby.

Petunjuk / Saran

Anda dapat menggunakan AI untuk membantu tugas ini nanti di artikel ini, atau lihat Mengaktifkan bantuan AI dengan Azure DevOps MCP Server untuk memulai.

Contoh berfokus pada kumpulan entitas pelacakan kerja Azure Boards, tetapi prinsip yang sama berlaku untuk kumpulan entitas lain. Untuk informasi selengkapnya, lihat Membuat kueri OData untuk analitik dan referensi Metadata untuk Azure Boards Analytics.

Catatan

Layanan Analitik diaktifkan secara otomatis dan didukung dalam produksi untuk semua layanan dalam Azure DevOps Services. Integrasi Power BI dan akses ke umpan OData dari layanan Analytics kini tersedia secara umum. Anda dianjurkan untuk menggunakan umpan OData Analytics dan memberikan umpan balik.

Data yang tersedia bergantung pada versi. Versi terbaru yang didukung dari API OData adalah v2.0, dan versi pratinjau terbaru adalah v4.0-preview. Untuk informasi selengkapnya, lihat Versioning OData API.

Prasyarat

Kategori	Persyaratan
Tingkat-tingkat akses	- Anggota proyek. - Setidaknya akses Dasar .
Izin	Secara default, anggota proyek memiliki izin untuk mengkueri Analytics 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

• Kueri lintas proyek gagal saat pengguna yang menjalankan kueri tidak memiliki akses ke semua proyek. Untuk informasi selengkapnya, lihat Kueri cakupan proyek dan organisasi.
• Contoh dalam artikel ini menggunakan format URL Layanan Azure DevOps: https://analytics.dev.azure.com/{OrganizationName}/. Untuk Azure DevOps Server, gunakan https://{servername}/{CollectionName}/ sebagai gantinya. Untuk informasi selengkapnya, lihat Membuat kueri OData untuk Analitik.

Mendapatkan hitungan item

Untuk mengembalikan hanya hitungan tanpa data lain, tambahkan $apply=aggregate($count as Count) ke URL kumpulan entitas apa pun. Misalnya, kueri berikut menghitung proyek, item kerja, jalur area, dan pengguna di seluruh 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)

Kueri Projects untuk organisasi fabrikam mengembalikan:

{
  "value": [
    {
      "Count": 16
    }
  ]
}

Mendapatkan hitungan item dan datanya

Untuk mengembalikan hitungan bersama data, tambahkan $count=true ke kueri yang menyertakan $select klausa. Kueri berikut mengembalikan jumlah serta properti tertentu untuk item kerja, jalur area, dan pengguna dalam proyek:

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

Catatan

Selalu sertakan $select atau $apply dalam kueri Anda. Menghilangkan keduanya memicu peringatan dan berpotensi mencapai batas penggunaan.

Untuk nama properti yang valid, lihat Referensi metadata untuk Azure Boards Analytics dan Referensi metadata Tanggal Kalender, Proyek, dan Pengguna.

Misalnya, kueri berikut mengembalikan jumlah dan nama pengguna dalam proyek Fabrikam Fiber :

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Users?$count=true&$select=UserName

Respons mencakup jumlah total dalam @odata.count dan catatan yang cocok di value:

{
  "@odata.count": 5,
  "value": [
    { "UserName": "Microsoft.VisualStudio.Services.TFS" },
    { "UserName": "fabrikamfiber1@hotmail.com" },
    { "UserName": "Jamal Hartnett" },
    { "UserName": "fabrikamfiber5@hotmail.com" },
    { "UserName": "fabrikamfiber2@hotmail.com" }
  ]
}

Pilih properti atau bidang tertentu

$select Tambahkan klausa untuk mengembalikan properti yang Anda butuhkan saja. Nama properti peka terhadap huruf besar/kecil, tidak boleh mengandung spasi, dan harus sesuai dengan nama bidang item kerja. Misalnya, $select=WorkItemId,WorkItemType,Title,State mengembalikan empat bidang tersebut.

Untuk pencarian nama properti, termasuk kustomisasi bidang, lihat Referensi metadata untuk Azure Boards.

Kueri berikut mengembalikan ID, jenis, judul, dan status untuk tiga item kerja teratas dalam proyek Fabrikam Fiber:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$top=3

{
  "value": [
    { "WorkItemId": 31, "Title": "About screen", "WorkItemType": "Task", "State": "New" },
    { "WorkItemId": 30, "Title": "Change background color", "WorkItemType": "Task", "State": "Active" },
    { "WorkItemId": 32, "Title": "Standardize on form factors", "WorkItemType": "Task", "State": "Active" }
  ]
}

Penyaringan data

$filter Tambahkan klausa untuk mengembalikan hanya item yang cocok dengan kriteria tertentu. Gunakan operator perbandingan seperti eq, ne, gt, ge, lt, dan le, dan gabungkan kondisi dengan and dan or. Misalnya, kueri berikut mengembalikan fitur yang sedang berlangsung:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,AssignedTo,State&$filter=WorkItemType eq 'Feature' and State eq 'In Progress'

Menggabungkan beberapa kondisi filter

Gunakan tanda kurung untuk mengelompokkan or kondisi dalam filter yang lebih and luas. Kueri berikut mengembalikan cerita pengguna, bug, dan jenis kustom dalam status tertentu:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,AssignedTo,State&$filter=(WorkItemType eq 'User Story' or WorkItemType eq 'Bug' or WorkItemType eq 'Backlog Work') and (State eq 'New' or State eq 'Committed' or State eq 'Active')

{
  "value": [
    { "WorkItemId": 210, "Title": "Slow response on form", "State": "Active" },
    ...
    { "WorkItemId": 160, "Title": "Game store testing", "State": "New" }
  ]
}

Anda juga dapat menggunakan fungsi string seperti contains, startswith, dan endswith dalam ekspresi filter. Untuk informasi selengkapnya, lihat Fungsi yang didukung.

Properti Jalur Area Kueri atau Jalur Perulangan

Beberapa kueri memerlukan kunci pengganti (AreaSK atau IterationSK) daripada string jalur. Gunakan kumpulan entitas Area atau Iterasi untuk mencari kunci untuk jalur tertentu.

Mengembalikan AreaSK untuk jalur area tertentu

Kueri berikut mengembalikan AreaSK untuk jalur area Fabrikam Fiber\Production Planning\Web. Untuk properti lain yang tersedia, lihat Areas.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Areas?$filter=AreaPath eq 'Fabrikam Fiber\Production Planning\Web'&$select=AreaSK

{
  "value": [
    { "AreaSK": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" }
  ]
}

Mengembalikan IterationSK untuk jalur iterasi tertentu

Kueri berikut mengembalikan IterationSK untuk jalur iterasi Fabrikam Fiber\Release 1\Sprint 3 . Untuk properti lain yang tersedia, lihat 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

Filter menurut properti navigasi

Properti navigasi seperti Iteration, Area, dan AssignedTo mewakili hubungan ke entitas lain. Untuk memfilter bidang dari entitas terkait, gunakan jalur lengkap dalam format NavigationProperty/Field. Misalnya, Iteration/IterationPath mereferensikan IterationPath bidang melalui Iteration properti navigasi:

/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

Kueri berikut mengembalikan lima item kerja teratas dalam iterasi tertentu, menggunakan jalur navigasi lengkap:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Iteration/IterationPath eq 'Fabrikam Fiber\3Week Sprints\Sprint 3'&$select=WorkItemId,WorkItemType,Title,State&$orderby=WorkItemId asc

Memperluas data dari entitas terkait

Pemfilteran menurut properti navigasi tidak menyertakan datanya dalam respons. Untuk mengembalikan bidang dari entitas terkait, gunakan $expand. Tanpa $expand, Anda tidak dapat mengakses bidang properti navigasi melalui $select.

Kueri berikut mengembalikan item kerja 480 dengan semua bidang yang diperluas dari entitas Iteration :

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration

Karena $select tidak diterapkan pada ekspansi Iteration, respons mencakup setiap bidang Iteration.

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "IterationSK": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "StartDate": "2025-12-04T00:00:00-12:00",
        "EndDate": "2025-12-25T23:59:59.999-12:00",
        "IterationLevel1": "Fabrikam Fiber",
        "IterationLevel2": "3Week Sprints",
        "IterationLevel3": "Sprint 3",
        ...
        "Depth": 2,
        "IsEnded": false
      }
    }
  ]
}

Gunakan perintah pilih dalam pernyataan pengembangan

Untuk membatasi bidang yang dikembalikan dari entitas yang diperluas, tambahkan $select klausa di dalam $expand menggunakan sintaks $expand=Entity($select=Field1,Field2). Kueri berikut ini memperluas Iteration, tetapi hanya mengembalikan IterationName dan IterationPath.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath)

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3"
      }
    }
  ]
}

Tabel berikut ini memperlihatkan $expand dengan $select contoh untuk jenis properti navigasi umum:

Jenis navigasi	Properti kunci	Contoh klausa
TanggalWaktu	DateSK	$expand=CreatedDate($select=Date) atau $expand=CreatedDate($select=WeekStartingDate)
Identitas	UserSK	$expand=AssignedTo($select=UserName) atau $expand=AssignedTo($select=UserEmail)
Daerah	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)
Proyek	ProjectSK	$expand=Project($select=ProjectName)
Tim	TeamSK	$expand=Teams($select=TeamName)

Untuk memperluas beberapa properti navigasi dalam satu kueri, gunakan daftar yang dibatasi koma:

$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath)

Menggunakan pernyataan perluasan berlapis

Untuk memperluas properti navigasi dalam entitas yang sudah diperluas, letakkan satu $expand ke dalam yang lain. Kueri berikut ini pertama memperluas Iteration dan kemudian memperluas Project di dalam Iteration untuk menunjukkan proyek mana yang menjadi bagian dari iterasi tersebut.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($expand=Project)

Untuk menggabungkan perluasan berlapis dengan $select, gunakan titik koma (;) untuk memisahkan $select dari $expand dalam tanda kurung. Tanpa titik koma, kueri mengembalikan kesalahan. Kueri ini mengembalikan hanya IterationName dan IterationPath dari Iteration, ditambah elemen bersarang Project.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath;$expand=Project)

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "Project": {
          "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber"
        }
      }
    }
  ]
}

Mengkueri rentang tanggal

Contoh kueri berikut mengembalikan item kerja yang Tanggal Diubah terakhirnya lebih besar dari atau sama dengan 1 Januari 2025.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-01-01Z

Contoh kueri berikut mengembalikan item kerja yang Tanggal Diubah terakhirnya terjadi selama minggu 31 Oktober hingga 7 November 2025.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-10-31Z and ChangedDate le 2025-11-07Z

Urukan hasil

Tambahkan $orderby untuk mengurutkan hasil menurut satu atau beberapa properti. Hasil mengurutkan dalam urutan naik secara default; tambahkan desc untuk turun. Pisahkan beberapa bidang pengurutan dengan koma.

Urutkan menurut	Klausul
ID item kerja	/WorkItems?$orderby=WorkItemId
ID item kerja (terurut terbaru)	/WorkItems?$orderby=WorkItemId desc
Jenis item kerja, lalu status	/WorkItems?$orderby=WorkItemType,State

Menggunakan AI untuk membuat kueri OData

Jika mengonfigurasi Azure DevOps MCP Server, Anda dapat menggunakan asisten AI untuk membantu membangun dan memecahkan masalah kueri OData.

Contoh arahan

Tugas	Contoh tanggapan
Membuat kueri	Write an OData query that returns all active bugs with their area path and assigned-to fields in <Contoso> project
Filter menurut tanggal	Create an OData query that returns work items created in the last 30 days in <Contoso> project
Memperluas properti navigasi	Write an OData query that expands the iteration path and area path for user stories in <Contoso> project
Debug kueri	My OData query returns no results — help me troubleshoot the filter clause and URL format for <Contoso> project
Perluas berlapis	Write an OData query with nested expand to return work items with their parent details in <Contoso> project
Mengurutkan dan membatasi hasil	Create an OData query that returns the 20 most recently changed bugs ordered by changed date in <Contoso> project
Hitung menurut jenis item kerja	Write an OData query that counts work items grouped by work item type for <Contoso> project
Filter dengan fungsi string	Create an OData query that returns work items whose title contains "login" in <Contoso> project
Gabungkan pilih, filter, dan perluas	Write an OData query that returns the title, state, assigned-to name, and iteration path for all user stories in the current sprint in <Contoso> project

Langkah selanjutnya

Kueri yang berbasis pada proyek & organisasi

Konten terkait

• Membuat kueri OData untuk Analitik
• Mengagregasi data menggunakan Analytics
• Referensi metadata untuk Azure Boards Analytics
• Praktik terbaik untuk digunakan saat mengkueri Analitik
• Fitur OData yang didukung
• OData v4.0 Bagian 2: Konvensi URL Plus Errata 02