Membuat kueri OData untuk Analitik di Azure DevOps

Artikel
07/20/2023

Layanan Azure DevOps | Azure DevOps Server 2022 - Azure DevOps Server 2019

Analitik, platform pelaporan untuk Azure DevOps, dapat menjawab pertanyaan kuantitatif tentang status proyek Anda di masa lalu atau saat ini. Analytics mendukung kueri OData dari metadata dan data kumpulan entitasnya. Dengan menggunakan kueri sederhana dari browser web, Anda bisa terbiasa dengan model data dan proses kueri.

Dalam artikel ini Anda akan mempelajari hal berikut:

Cara membuat kueri Analitik OData untuk cloud atau lokal
Cara mengkueri metadata Analitik
Cara mengkueri OData Analitik untuk kumpulan entitas
Opsi kueri mana yang didukung dan urutan yang direkomendasikan
Ketika halaman sisi server diberlakukan

Anda dapat mengkueri Analytics dari browser web yang didukung. Untuk alat lain yang dapat Anda gunakan untuk mengkueri Analytics, lihat Alat kueri Analitik.

Catatan

OData, protokol tingkat aplikasi untuk berinteraksi dengan data melalui antarmuka RESTful (di mana REST=Representational State Transfer), mendukung deskripsi model data serta mengedit dan mengkueri data sesuai dengan model tersebut. Model Data Entitas (EDM) atau metadata menjelaskan informasi yang tersedia dari Analytics, termasuk entitas, jenis entitas, properti, hubungan, dan enumerasi yang Anda gunakan untuk mengkueri data untuk membuat laporan. Untuk gambaran umum OData, lihat Selamat Datang di OData.

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.

Komponen URL untuk mengkueri metadata

Analitik mengekspos model entitas di URL metadata, yang dibentuk dengan menambahkan $metadata ke URL akar layanan. Analitik menyediakan akar layanan untuk proyek atau seluruh organisasi di Azure DevOps.

Anda dapat mencari salah satu elemen data berikut dengan mengkueri metadata.

Jenis entitas dan set entitas
Properti dan properti navigasi
Kunci pengganti
Daftar enumerasi
EntitySet
Kontainer
Fungsi filter (Org.OData.Capabilities.V1.FilterFunctions)
Agregasi yang didukung (Org.OData.Aggregation.V1.ApplySupported)
Dukungan batch (Org.OData.Capabilities.V1.BatchSupportType)

URL yang Anda gunakan bergantung pada apakah Anda mengkueri data untuk Azure DevOps Services (cloud) atau Azure DevOps Server lokal.

Cloud (Layanan Azure DevOps
Lokal (Azure DevOps Server

Untuk mengkueri metadata untuk organisasi atau proyek yang dihosting di cloud, masukkan sintaks URL seperti yang ditunjukkan di bawah ini di browser web. Ganti {OrganizationName} dan {ProjectName} dengan nama organisasi Anda dan nama proyek yang ingin Anda kueri. Untuk mengembalikan semua metadata untuk organisasi, jangan tentukan nama proyek.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/version/$metadata 
\______________________________/\______________________________/\______________/\_________/
               |                                 |                       |           |
    Analytics service root URL         Organization/Project        OData version  return metadata

Catatan

Versi OData Analitik terbaru adalah v4.0-preview. Anda dapat menggunakan versi ini untuk semua kueri terhadap layanan yang dihosting. Untuk informasi selengkapnya tentang versi Analytics dan data yang tersedia, lihat Model data untuk Analytics.

Berikut adalah contoh untuk organisasi fabrikam yang dihosting di Azure DevOps Services.

https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata

Untuk mengkueri metadata untuk server lokal, masukkan sintaks URL seperti yang ditunjukkan di bawah ini di browser web. Ganti {ServerName}, {CollectionName} dan {ProjectName} dengan nama lokal Anda. Untuk mengembalikan semua metadata untuk koleksi, jangan tentukan nama proyek.

https://{ServerName}/{CollectionName}/{ProjectName}/_odata/version/$metadata 
\_________________________________________________/\______________/\________/
                            |                              |            | 
     On-premises server, collection, project         OData version  return metadata

Catatan

Berikut adalah contoh untuk server bernama fabrikam-devops dan yang DefaultCollection dihosting di Azure DevOps Server 2022:

https://fabrikam-devops/DefaultCollection/_odata/v4.0-preview/$metadata

Menginterpretasikan respons metadata

Analitik mengembalikan file XML model data. Gunakan fungsi pencarian browser Anda untuk menemukan informasi khusus untuk entitas yang diminati.

Tip

Bergantung pada browser yang Anda gunakan, file ini mungkin atau mungkin tidak diformat dengan cara yang dapat dibaca. Jika tidak diformat, Anda dapat menemukan formatter XML online gratis melalui pencarian browser web.

Dua skema utama yang ditentukan dalam metadata Analytics adalah Microsoft.VisualStudio.Services.Analytics.Model, yang menentukan jenis entitas dan jenis enumerasi dan anggotanya, dan Default skema, yang menentukan kontainer entitas dan set entitas dan fungsi filter, transformasi, dan agregasi kustom OData yang didukung. Untuk informasi selengkapnya, lihat Metadata OData Analitik.

<?xml version="1.0" encoding="UTF-8"?>
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
    <edmx:DataServices>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Microsoft.VisualStudio.Services.Analytics.Model">
           <EntityType Name="Entity Name"/>
        </Schema>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Default">
           <EntityContainer Name="Container"/>
        </Schema>
    </edmx:DataServices>
</edmx:Edmx>

Semua jenis entitas dikaitkan dengan properti dan properti navigasi. Anda dapat memfilter kueri kumpulan entitas menggunakan kedua jenis properti ini. Ini tercantum dalam metadata di EntityType bawah sebagai Property atau NavigationalProperty. Anda menggunakan entitas terkait untuk menentukan filter tambahan, seperti Jalur Perulangan, Jalur Area, atau Teams.

Cuplikan kode berikut menyediakan tampilan parsial metadata untuk WorkItem entitas. Properti sesuai dengan bidang item kerja serta data tertentu yang diambil oleh Analytics, seperti LeadTimeDays dan CycleTimeDays. Properti navigasi sesuai dengan kumpulan entitas lain, atau data Analitik tertentu yang diambil untuk jenis entitas, seperti Revisions, , LinksChildren, dan Parent.

<Key>
   <PropertyRef Name="WorkItemId"/>
</Key>
<Property Name="WorkItemId" Type="Edm.Int32" Nullable="false">
   <Annotation Term="Ref.ReferenceName" String="System.Id"/>
   <Annotation Term="Display.DisplayName" String="Work Item Id"/>
</Property>
<Property Name="InProgressDate" Type="Edm.DateTimeOffset">
   <Annotation Term="Display.DisplayName" String="InProgress Date"/>
   </Property>
<Property Name="CompletedDate" Type="Edm.DateTimeOffset">
   <Annotation Term="Display.DisplayName" String="Completed Date"/>
   </Property>
<Property Name="LeadTimeDays" Type="Edm.Double">
   <Annotation Term="Display.DisplayName" String="Lead Time Days"/>
</Property>
<Property Name="CycleTimeDays" Type="Edm.Double">
   <Annotation Term="Display.DisplayName" String="Cycle Time Days"/>
</Property>
<Property Name="InProgressDateSK" Type="Edm.Int32"/>
<Property Name="CompletedDateSK" Type="Edm.Int32"/>
<Property Name="AnalyticsUpdatedDate" Type="Edm.DateTimeOffset"/>
<Property Name="ProjectSK" Type="Edm.Guid" Nullable="false"/>
<Property Name="WorkItemRevisionSK" Type="Edm.Int32" Nullable="false"/>
...
<NavigationProperty Name="BoardLocations" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.BoardLocation)"/>
<NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>
<NavigationProperty Name="InProgressOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="InProgressDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="CompletedOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="CompletedDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="Revisions" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemRevision)"/>
<NavigationProperty Name="Links" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemLink)"/>
<NavigationProperty Name="Children" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Parent" Type="Microsoft.VisualStudio.Services.Analytics.Model.WorkItem">
<ReferentialConstraint Property="ParentWorkItemId" ReferencedProperty="WorkItemId"/>
</NavigationProperty>
<NavigationProperty Name="Processes" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Process)"/>
<NavigationProperty Name="Descendants" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project" Nullable="false">
<ReferentialConstraint Property="ProjectSK" ReferencedProperty="ProjectSK"/>
<Annotation Term="Display.DisplayName" String="Project"/>
...

Komponen URL untuk mengkueri entitas

Untuk mengkueri data Analitik dan membuat laporan, Anda biasanya mengkueri kumpulan entitas. Untuk gambaran umum entitas yang didukung, lihat Metadata Analitik OData.

URL berikut digunakan untuk mengkueri , EntitySetseperti WorkItems, , WorkItemSnapshotdan PipelineRuns.

Cloud (Layanan Azure DevOps
Lokal (Azure DevOps Server

https://analytics.dev.azure.com/OrganizationName/ProjectName/_odata/version/EntityType?{Query-options}
\______________________________/\__________________________/ \____________/\_________/\_____________/
               |                             |                    |               |          |
    Analytics service root URL     Organization/Project      OData version    Entity   Query parts

Berikut adalah contoh untuk organisasi fabrikam yang mengembalikan jumlah item kerja yang ditentukan untuk proyek Fabrikam Fiber.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?%20$apply=aggregate($count%20as%20Count)

Contoh mengembalikan 1399 item kerja.

{
"@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(Count)",
"value": [
   {
   "@odata.id": null,
   "Count": 1399
   }
 ]
}

Berikut adalah contoh untuk server fabrikam , DefaultCollection, yang mengembalikan jumlah item kerja yang ditentukan untuk proyek Fabrikam .

https://fabrikam/DefaultCollection/Fabrikam/_odata/v4.0-preview/WorkItems?%20$apply=aggregate($count%20as%20Count)

Contoh mengembalikan 1399 item kerja.

{
"@odata.context": "http://fabrikam/DefaultCollection/Fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)",
"value": [
   {
      "@odata.id": null,
      "Count": 44
   }
 ]
}

Catatan

Jika Anda tidak menyertakan $select klausul atau $apply , Anda akan menerima peringatan, seperti "VS403507: The specified query does not include a $select or $apply clause which is recommended for all queries. Details on recommended query patterns are available here: https://go.microsoft.com/fwlink/?linkid=861060." Setara dengan melakukan pernyataan pilih pada kumpulan entitas dan mengembalikan semuanya, semua kolom, dan semua baris. Jika Anda memiliki sejumlah besar rekaman, mungkin perlu waktu beberapa detik. Jika Anda memiliki lebih dari 10.000 item kerja, halaman berbasis server diberlakukan.

Untuk menghindari batas penggunaan, selalu sertakan $select klausa atau $apply .

Untuk informasi properti metadata entitas dan hubungan, lihat artikel berikut ini:

Contoh: Mengkueri kumpulan entitas tertentu

Untuk mengkueri kumpulan entitas tertentu, seperti WorkItems, , Areasatau Projects, tambahkan nama kumpulan entitas: /WorkItems, , /Areasatau /Projects. Untuk daftar lengkap kumpulan entitas, lihat Model data untuk Analytics.

Cloud (Layanan Azure DevOps
Lokal (Azure DevOps Server

Misalnya, Anda bisa mendapatkan daftar proyek yang ditentukan untuk organisasi Anda dengan mengkueri /Projects dan memilih untuk mengembalikan ProjectName properti. Untuk organisasi fabrikam, URL seperti yang ditunjukkan di bawah ini.

  https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/Projects?$select=ProjectName

Analitik mengembalikan nama proyek proyek yang ditentukan untuk organisasi fabrikam .

{
@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(ProjectName)",

"value": [
   {
      "ProjectName": "Basic Fabrikam"
   },
   {
      "ProjectName": "Fabrikam Fiber"
   },
   {
      "ProjectName": "MyFirstProject"
   },
   {
      "ProjectName": "Fabrikam Test"
   },
   {
      "ProjectName": "MyPublicProject"
   }
 ]
}

Berikut adalah contoh yang mengkueri Projects entitas yang ditetapkan untuk mengembalikan nama semua proyek yang ditentukan pada DefaultCollection di server fabrikam ,

https://fabrikam/DefaultCollection/_odata/v4.0-preview/Projects?$select=ProjectName

Contoh mengembalikan tiga nama proyek.

{
"@odata.context": "http://fabrikam/DefaultCollection/_odata/v4.0-preview/$metadata#Projects(ProjectName)",
"value": [
   {
      "ProjectName": "Fabrikam Fiber"
   },
   {
      "ProjectName": "Fabrikam"
   },
   {
      "ProjectName": "Fabrikam Florida"
   }
 ]
}

Opsi kueri

Opsi kueri adalah sekumpulan parameter string kueri yang diterapkan ke sumber daya yang dapat membantu mengontrol jumlah data yang dikembalikan untuk sumber daya di URL.

Opsi kueri harus ditentukan dalam urutan yang tercantum dalam tabel berikut ini.

Opsi kueri	Catatan
`$apply`	Kumpulan transformasi yang bisa Anda terapkan ke kueri, seperti: `filter`, , `groupbyaggregate`, , `expand,` `compute` `concat` Misalnya, lihat Data pelacakan kerja agregat menggunakan Analytics.
`$compute`	Fungsi OData yang didukung yang dapat Anda tentukan untuk menentukan properti komputasi yang dapat digunakan dalam `$select`ekspresi , ,`$filter` atau `$orderby` .
`$filter`	Gunakan untuk memfilter daftar sumber daya yang dikembalikan. Ekspresi yang ditentukan dengan `$filter` dievaluasi untuk setiap sumber daya dalam koleksi, dan hanya item tempat ekspresi dievaluasi ke true disertakan dalam respons. Sumber daya yang ekspresinya dievaluasi ke false atau ke null, atau properti referensi mana yang tidak tersedia karena izin, dihilangkan dari respons. Misalnya, lihat Data pelacakan kerja kueri menggunakan Analytics .
`$orderby`	Gunakan untuk menentukan urutan di mana rekaman harus dikembalikan. Misalnya, lihat Data pelacakan kerja kueri menggunakan Analytics.
`$top`/`$skip`	Gunakan untuk membatasi jumlah rekaman yang dikembalikan. Misalnya, lihat Kueri proyek dan cakupan organisasi.
`$select`/`$expand`	Gunakan `$select` untuk menentukan kolom yang Anda butuhkan untuk membuat laporan Anda. Gunakan `$expand` untuk menumpuk opsi kueri lainnya. Masing-masing `expandItem` dievaluasi relatif terhadap entitas yang berisi properti navigasi atau streaming yang diperluas. Daftar opsi kueri yang dipisahkan titik koma, diapit dalam tanda kurung, ke nama properti navigasi. Opsi kueri sistem yang diizinkan adalah `$filter`, , `$orderby$select`, `$skip`, `$top`, `$count`, `$search`, dan `$expand`. Misalnya, lihat Data pelacakan kerja kueri menggunakan Analytics.
`$skiptoken`	Gunakan untuk melewati jumlah rekaman tertentu.
`$count` atau `$count=true`	Masukkan `$count` untuk hanya mengembalikan jumlah rekaman. Masukkan `$count=true`untuk mengembalikan jumlah rekaman dan data yang dikueri. Misalnya, lihat Data pelacakan kerja agregat menggunakan Analytics.

Tip

Hindari pencampuran $apply dan $filter klausa dalam satu kueri. Untuk memfilter kueri, Anda memiliki dua opsi: (1) menggunakan $filter klausa atau (2) menggunakan $apply=filter() klausa kombinasi. Masing-masing opsi ini berfungsi dengan baik sendiri, tetapi menggabungkannya bersama-sama dapat menyebabkan beberapa hasil yang tidak terduga.

Terapkan halaman sisi server

Analitik memaksa halaman saat hasil kueri melebihi 10000 rekaman. Dalam hal ini, Anda akan mendapatkan halaman pertama data dan tautan untuk diikuti untuk mendapatkan halaman berikutnya. Tautan (@odata.nextLink) dapat ditemukan di akhir output JSON. Ini akan terlihat seperti kueri asli diikuti oleh $skip atau $skiptoken. Contoh:

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
  "value":[
   // 10000 values here
  ],
  "@odata.nextLink":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$skiptoken=10000"
}

Catatan

Saat menarik data ke alat klien seperti Power BI Desktop atau Excel, alat akan secara otomatis mengikuti tautan berikutnya dan memuat semua rekaman yang diperlukan.

Langkah berikutnya

Membuat kueri dasar menggunakan OData Analytics

Bagikan melalui

Membuat kueri OData untuk Analitik di Azure DevOps

Prasyarat

Komponen URL untuk mengkueri metadata

Menginterpretasikan respons metadata

Komponen URL untuk mengkueri entitas

Contoh: Mengkueri kumpulan entitas tertentu

Opsi kueri

Terapkan halaman sisi server

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Membuat kueri OData untuk Analitik di Azure DevOps

Prasyarat

Komponen URL untuk mengkueri metadata

Menginterpretasikan respons metadata

Entitas terkait dan properti navigasi

Komponen URL untuk mengkueri entitas

Contoh: Mengkueri kumpulan entitas tertentu

Opsi kueri

Terapkan halaman sisi server

Langkah berikutnya

Artikel terkait

Saran dan Komentar

Sumber Daya Tambahan: