Bagikan melalui

Membuat kueri OData untuk Analitik di Azure DevOps

  • Artikel

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

  • Tingkat akses: Anda harus menjadi anggota proyek dengan akses Dasar atau yang lebih tinggi.
  • 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.

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

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.

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
   }
 ]
}

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.

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"
   }
 ]
}

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 $selectekspresi , ,$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=trueuntuk 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