Bagikan melalui

Panduan kueri OData Analytics untuk Azure DevOps

  • Artikel

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

Pengembang ekstensi dapat memperoleh manfaat dengan mengikuti panduan yang disediakan dalam artikel ini untuk merancang kueri OData yang efisien terhadap Analytics untuk Azure DevOps. Mengikuti panduan ini membantu memastikan kueri memiliki performa yang baik untuk waktu eksekusi dan konsumsi sumber daya. Kueri yang tidak mematuhi panduan ini dapat mengakibatkan performa yang buruk, dengan waktu tunggu laporan yang panjang, kueri yang melebihi konsumsi sumber daya yang diizinkan, atau pemblokiran layanan.

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.

Panduan ini adalah rekomendasi kami yang diawali dengan istilah DO, CONSIDER, AVOID, dan DON'T. Aturan pembatasan yang diberlakukan oleh Analytics berisi awalan [BLOCKED ]. Anda harus memahami trade-off antara solusi yang berbeda. Dalam keadaan tertentu, Anda mungkin memiliki persyaratan data yang memaksa Anda melanggar satu atau beberapa pedoman. Kasus seperti itu harus jarang terjadi. Kami menyarankan agar Anda memiliki alasan yang jelas dan menarik untuk keputusan tersebut.

Tip

Contoh yang ditampilkan dalam dokumen ini didasarkan pada URL Layanan Azure DevOps. Gunakan substitusi untuk versi lokal.

https://{servername}:{port}/tfs/{OrganizationName}/{ProjectName}/_odata/{version}/

Pesan kesalahan dan peringatan

✔️ DO meninjau peringatan respons OData

Setiap kueri yang Anda jalankan diperiksa terhadap sekumpulan aturan yang telah ditentukan sebelumnya. Pelanggaran mengembalikan respons OData setelah @vsts.warnings. Tinjau peringatan ini saat memberikan informasi saat ini dan peka konteks tentang cara meningkatkan kueri Anda.

{
  "@odata.context": "https://{OrganizationName}.tfsallin.net/_odata/v1.0/$metadata#WorkItems",
  "@vsts.warnings": [
    "The specified query does not include a $select or $apply clause which is recommended for all queries."
  ],
  ...
}

✔️ DO meninjau pesan kesalahan OData

Kueri yang melanggar aturan kesalahan OData menghasilkan respons yang gagal dengan kode status 400 (Permintaan Buruk). Mengaitkan pesan tidak muncul di @vsts.warnings dalam properti. Sebaliknya, mereka menghasilkan pesan kesalahan di message properti dalam respons JSON.

{
  "error": {
  "code": "0",
  "message": "The query specified in the URI is not valid. The Snapshot tables in Analytics are intended to be used only in an aggregation."
  }
}

Batasan

Boleh

Pertimbangan

Terblokir

Hindari

✔️ DO membatasi kueri ke proyek yang dapat Anda akses

Jika kueri Anda menargetkan data dari proyek yang tidak dapat Anda akses, kueri mengembalikan pesan "Akses proyek ditolak". Untuk memastikan bahwa Anda memiliki akses, pastikan izin Lihat analitik Anda diatur ke Izinkan untuk semua proyek yang Anda kueri. Untuk informasi selengkapnya, lihat Izin yang diperlukan untuk mengakses Analitik.

Jika Anda tidak memiliki akses ke proyek, pesan berikut akan ditampilkan:

Hasil kueri menyertakan data dalam satu atau beberapa proyek yang tidak dapat Anda akses. Tambahkan satu atau beberapa filter proyek untuk menentukan proyek yang dapat Anda akses di entitas 'WorkItems'. Jika Anda menggunakan properti $expand atau navigasi, filter proyek diperlukan untuk entitas tersebut.

Untuk mengatasi masalah ini, Anda dapat secara eksplisit menambahkan filter proyek, atau menggunakan titik akhir cakupan proyek seperti yang dijelaskan nanti dalam artikel ini.

Misalnya, kueri berikut mengambil item kerja milik proyek bernama {projectSK1} dan {projectSK2}.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectSK eq {projectSK1} or ProjectSK eq {projectSK2}
  &$select=WorkItemId, Title

✔️ DO menentukan filter proyek di dalam $expand klausul jika ekspansi Anda dapat menyertakan data dalam proyek lain yang berpotensi tidak dapat diakses

Saat Anda memperluas properti navigasi, ada kemungkinan Anda akhirnya mereferensikan data dari proyek lain yang tidak dapat diakses. Jika Anda mereferensikan data yang tidak dapat diakses, Anda menerima pesan kesalahan yang sama yang tercantum sebelumnya, "Hasil kueri menyertakan data dalam satu atau beberapa proyek...". Demikian pula, Anda dapat mengatasi masalah ini dengan menambahkan filter proyek eksplisit untuk mengontrol data yang diperluas.

Anda dapat melakukannya dalam klausul reguler $filter untuk properti navigasi sederhana. Misalnya, kueri berikut secara eksplisit meminta WorkItemLinks di mana tautan dan targetnya berada dalam proyek yang sama.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItemLinks?
  $filter=ProjectSK eq {projectSK} and TargetWorkItem/ProjectSK eq {projectSK}
  &$select=LinkTypeReferenceName, SourceWorkItemId, TargetWorkItemId
  &$expand=TargetWorkItem($select=WorkItemId, Title)

Sebagai gantinya, Anda dapat memindahkan filter untuk $filter memperluas opsi dalam $expand klausa. Namun, ini mengubah semantik kueri. Misalnya, kueri berikut mendapatkan semua tautan dari proyek tertentu dan secara kondisional memperluas target hanya jika ada dalam proyek yang sama. Meskipun valid, pendekatan ini dapat menyebabkan kebingungan karena mungkin sulit untuk menentukan apakah properti tidak diperluas karena itu null atau karena difilter. Gunakan solusi ini hanya jika Anda benar-benar membutuhkan perilaku khusus ini.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItemLinks?
  $filter=ProjectSK eq {projectSK}
  &$select=LinkTypeReferenceName, SourceWorkItemId, TargetWorkItemId
  &$expand=TargetWorkItem($filter=ProjectSK eq {projectSK}; $select=WorkItemId, Title)

Opsi $filter perluas berguna saat Anda menggunakan properti perluas koleksi seperti Children dalam WorkItems kumpulan entitas. Misalnya, kueri berikut mengembalikan semua item kerja dari proyek tertentu bersama dengan semua anak mereka yang termasuk dalam proyek yang sama.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectSK eq {projectSK}
  &$select=WorkItemId, Title
  &$expand=Children($filter=ProjectSK eq {projectSK}; $select=WorkItemId, Title)

Tentukan filter jika Anda memperluas salah satu properti berikut ini:

  • WorkItems set entitas: Parent, Children
  • WorkItemLinks set entitas: TargetWorkItem.

✔️ PERTIMBANGKAN kueri menggunakan titik akhir cakupan proyek

Jika Anda tertarik dengan data dari satu proyek, kami sarankan Anda menggunakan titik akhir OData yang dicakup proyek (/{ProjectName}/_odata/v1.0). Ini menghindari masalah yang dijelaskan dalam dua bagian sebelumnya, dan secara implisit memfilter data ke satu proyek, kumpulan entitas yang direferensikan, dan semua properti navigasi yang diperluas.

Dengan penyederhanaan ini, kueri dari bagian sebelumnya dapat ditulis ulang ke formulir berikut. Filter dalam klausa perluas tidak hanya menghilang, tetapi juga tidak perlu filter pada kumpulan entitas utama.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}//WorkItemLinks?
  &$select=LinkTypeReferenceName, SourceWorkItemId, TargetWorkItemId
  &$expand=TargetWorkItem($select=WorkItemId, Title)

Kueri untuk anak item kerja juga jauh lebih pendek dan lebih sederhana.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}//WorkItems?
  &$select=WorkItemId, Title
  &$expand=Children($select=WorkItemId, Title)

Anda dapat menerapkan solusi ini hanya ketika fokus Anda adalah data dari satu proyek. Untuk pelaporan lintas proyek, Anda harus menggunakan strategi pemfilteran yang dijelaskan di bagian sebelumnya.

✔️ DO menunggu atau menghentikan operasi jika kueri Anda melebihi batas penggunaan

Jika Anda menjalankan banyak kueri, atau kueri memerlukan banyak sumber daya untuk dijalankan, Anda mungkin melebihi batas layanan dan diblokir sementara. Jika Anda melebihi batas layanan, hentikan operasi Anda sebagai kemungkinan adalah kueri berikutnya yang Anda kirim gagal dengan pesan kesalahan yang sama.

Permintaan diblokir karena melebihi penggunaan sumber daya '{resource}' di namespace '{namespace}'.

Untuk informasi selengkapnya tentang pembatasan tarif, lihat Batas tarif. Untuk mempelajari cara merancang kueri OData yang efisien, lihat Panduan Performa nanti di artikel ini.

✔️ DO menunggu atau menghentikan operasi jika kueri Anda gagal dengan batas waktu

Mirip dengan melebihi batas penggunaan, Anda harus menunggu atau menghentikan operasi jika kueri Anda melewati batas waktu. Ini dapat menandakan masalah sementara, sehingga Anda dapat mencoba kembali sekali untuk melihat apakah masalah diselesaikan. Namun, batas waktu persisten menunjukkan bahwa kueri mungkin terlalu mahal untuk dijalankan. Percobaan ulang lebih lanjut hanya mengakibatkan melebihi batas penggunaan dan Anda diblokir.

TF400733: Permintaan telah dibatalkan: Permintaan telah melebihi batas waktu permintaan, silakan coba lagi.

Batas waktu menunjukkan bahwa kueri memerlukan pengoptimalan. Untuk mempelajari cara mendesain kueri OData yang efisien, lihat Panduan performa nanti di artikel ini.

❌ [DIBLOKIR] JANGAN gunakan entitas rekam jepret untuk apa pun selain agregasi

Kumpulan entitas rekam jepret dengan Snapshot akhiran bersifat khusus karena dimodelkan sebagai rekam jepret harian. Anda dapat menggunakannya untuk mendapatkan status entitas seperti pada akhir setiap hari di masa lalu. Misalnya, jika Anda mengkueri WorkItemSnapshot dan memfilter ke satu WorkItemId, Anda akan mendapatkan satu rekaman untuk setiap hari sejak item kerja dibuat. Memuat langsung semua data ini akan mahal dan kemungkinan besar akan melebihi batas penggunaan dan diblokir. Namun, agregasi pada entitas ini diizinkan dan direkomendasikan. Bahkan, set entitas rekam jepret dirancang dengan pertimbangkan skenario agregasi.

Misalnya, kueri berikut mendapatkan jumlah item kerja berdasarkan tanggal untuk mengamati pertumbuhannya pada Januari 2020.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItemSnapshot?
  $apply=
    filter(DateSK ge 20200101 and DateSK le 20200131)/
    groupby((DateSK), aggregate($count as Count))

Untuk informasi selengkapnya tentang agregasi, lihat Agregat data.

✔️ DO sertakan DateSK atau DateValue kolom dalam groupby klausul saat Anda mengagregasi tabel rekam jepret

Karena semua entitas rekam jepret dimodelkan sebagai tabel rekam jepret harian, Anda harus selalu menyertakan salah satu properti harian (DateSK atau DateValue) dalam klausa pengelompokan. Jika tidak, hasilnya mungkin muncul dengan tidak benar.

Misalnya, jika Anda hanya mengelompokkan WorkItemSnapshot menurut AssignedTo properti dan menggabungkannya dengan hitungan, semua jumlah item kerja yang ditetapkan untuk orang akan dikalikan dengan jumlah hari ketika setiap tugas aktif. Meskipun Anda mungkin memiliki situasi di mana itu adalah hasil yang Anda inginkan, kasus seperti itu jarang terjadi.

❌ [DIBLOKIR] JANGAN gunakan kunci entitas di jalur sumber daya untuk alamat entitas

Sintaks OData menyediakan cara untuk mengakses entitas tertentu dengan menyertakan kuncinya langsung di segmen URL. Untuk informasi selengkapnya, lihat OData Versi 4.0. Bagian 2: Konvensi URL - 4.3 Entitas Alamat. Meskipun OData memungkinkan alamat tersebut, Analytics memblokirnya. Penyertaan dalam kueri menghasilkan kesalahan berikut.

Kueri yang ditentukan dalam URI tidak valid. Analitik tidak mendukung navigasi kunci atau properti seperti WorkItems(Id) atau WorkItem(Id)/AssignedTo. Jika Anda mendapatkan kesalahan tersebut di PowerBI, silakan, tulis ulang kueri Anda untuk menghindari lipatan yang salah yang menyebabkan masalah N+1.

Sebagai petunjuk pesan kesalahan, alat klien tertentu dapat menyalahgunakan alamat entitas langsung. Alih-alih memuat semua data dalam satu permintaan, klien tersebut dapat memilih untuk mengkueri setiap entitas secara independen. Praktik ini tidak disarankan karena dapat mengakibatkan jumlah permintaan yang tinggi. Sebagai gantinya, kami sarankan Anda menggunakan alamat entitas eksplisit seperti yang dijelaskan di bagian berikut.

✔️ DO secara eksplisit mengatasi entitas dengan klausa filter

Jika Anda ingin mengambil data untuk satu entitas, Anda harus menggunakan pendekatan yang sama seperti untuk kumpulan entitas, dan secara eksplisit menentukan filter dalam $filter klausa.

Misalnya, kueri berikut mendapatkan satu item kerja dengan pengidentifikasinya.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=WorkItemId eq {id}
  &$select=WorkItemId, Title

Jika Anda tidak yakin properti mana yang harus Anda sertakan dalam filter seperti itu, Anda dapat mencarinya dalam metadata. Lihat Membuat kueri OData untuk Analitik, komponen URL untuk mengkueri metadata. Properti berada dalam Key elemen EntityType. Misalnya, WorkItemId dan Revision merupakan kolom kunci untuk WorkItemRevision entitas.

<EntityType Name="WorkItemRevision">
  <Key>
    <PropertyRef Name="WorkItemId"/>
    <PropertyRef Name="Revision"/>
  </Key>
  [...]
</EntityType>

❌ [DIBLOKIR] JANGAN perluas Revisions pada WorkItem entitas

Model data Analitik melarang jenis ekspansi tertentu. Salah satunya, yang mungkin mengejutkan bagi beberapa orang, adalah Revisions properti koleksi pada WorkItem entitas. Jika Anda mencoba memperluas properti ini, Anda akan menerima pesan kesalahan berikut.

Kueri yang ditentukan dalam URI tidak valid. Properti 'Revisi' tidak dapat digunakan dalam opsi kueri $expand.

Pembatasan ini diberlakukan untuk mendorong semua orang menggunakan solusi yang direkomendasikan, yaitu mengambil revisi seperti WorkItemRevisions yang dijelaskan di bagian berikut.

✔️ DO menggunakan WorkItemRevisions entitas yang diatur untuk memuat semua revisi untuk item kerja tertentu

Gunakan WorkItemRevisions setiap kali Anda ingin mengambil riwayat lengkap untuk item kerja atau kumpulan item kerja.

Misalnya, kueri berikut mengembalikan semua revisi item kerja dengan {id} pengidentifikasi.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItemRevisions?
  $filter=WorkItemId eq {id}
  &$select=WorkItemId, Title

Jika Anda peduli dengan riwayat lengkap untuk semua item kerja yang cocok dengan kriteria tertentu, ekspreskan menggunakan filter pada WorkItem properti navigasi. Misalnya, kueri berikut mendapatkan semua revisi semua item kerja yang saat ini aktif.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItemRevisions?
  $filter=WorkItem/State eq 'Active'
  &$select=WorkItemId, Title

❌ [DIBLOKIR] Jangan kelompokkan pada kolom yang berbeda

Anda menggunakan operasi pengelompokan untuk mengurangi jumlah rekaman. Menggunakan kolom yang berbeda dalam groupby klausul menunjukkan masalah, dan kueri segera gagal. Jika Anda tidak sengaja mengalami situasi ini, Anda menerima pesan kesalahan berikut.

Satu atau beberapa kolom yang ditentukan dalam klausa groupby kueri ini tidak disarankan.

Untuk mengatasi masalah ini, hapus kolom yang berbeda dari groupby klausa.

❌ [DIBLOKIR] JANGAN gunakan countdistinct agregasi

Analitik tidak mendukung fungsi, countdistinct meskipun OData melakukannya. Meskipun kami berencana untuk menambahkan dukungan di masa mendatang, saat ini tidak tersedia. Kueri yang berisi fungsi ini mengembalikan pesan kesalahan berikut.

Kueri yang menerapkan hitungan berbeda dengan agregasi tidak didukung.

❌ MENGHINDARI agregasi yang dapat mengakibatkan luapan aritmatika

Dalam kasus yang jarang terjadi, kueri agregasi mungkin mengalami masalah dengan luapan aritmatika. Misalnya, ini dapat terjadi ketika Anda menjumlahkan beberapa properti numerik yang tidak dimaksudkan untuk penjumlahan, seperti StackRank di entitas item kerja. Karena standar Ekstensi OData untuk Agregasi Data tidak menyediakan cara untuk mentransmisikan properti ke jenis yang berbeda, satu-satunya cara untuk menyelesaikan masalah ini adalah dengan menghapus properti yang bermasalah dari agregasi.

✔️ DO menggunakan titik akhir batch untuk kueri panjang

Anda dapat menimbulkan masalah dengan kueri panjang. Terutama, masalah mungkin terjadi ketika:

  • Anda mengkueri proyek dengan banyak bidang kustom.
  • Kueri Anda dibuat secara terprogram.

Batas kueri OData saat ini yang dikirim dengan HTTP GET adalah 3.000 karakter. Jika Anda melebihinya, Anda mendapatkan kembali respons "404 Tidak Ditemukan".

HTTP/1.1 404 Not Found
Content-Length: 0

Untuk mengatasi masalah ini, gunakan titik akhir batch OData seperti yang dijelaskan dalam spesifikasi, OData Versi 4.0. Bagian 1: Protokol - 11.7 Permintaan Batch. Kemampuan batch terutama dirancang untuk mengelompokkan beberapa operasi ke dalam satu HTTP payload permintaan, tetapi Anda juga dapat menggunakannya sebagai solusi untuk batasan panjang kueri. Dengan mengirim HTTP POST permintaan, Anda dapat meneruskan kueri dengan panjang arbitrer dan layanan menafsirkannya dengan benar.

❌ [DIBLOKIR] JANGAN gunakan titik akhir batch untuk mengirim beberapa kueri

Kami membatasi penggunaan titik akhir batch untuk menangani batch beberapa permintaan. Satu permintaan masih hanya dapat memiliki satu kueri. Jika Anda mencoba mengirim batch beberapa kueri, operasi gagal dengan pesan kesalahan berikut. Satu-satunya solusi adalah membagi kueri menjadi beberapa permintaan.

Analitik tidak mendukung pemrosesan beberapa operasi yang dimuat pesan batch saat ini. Analitik menggunakan batch OData untuk mendukung permintaan POST, tetapi mengharuskan Anda membatasi operasi ke satu permintaan.

❌ [DIBLOKIR] JANGAN gunakan kueri yang menghasilkan lebih dari 800 kolom

Kami membatasi kueri yang menghasilkan lebih dari 800 kolom. Jika Anda tidak cukup selektif di mana kolom yang dikembalikan kueri Anda, Anda mungkin menerima pesan kesalahan berikut.

VS403670: Kueri yang ditentukan mengembalikan kolom 'N' yang lebih tinggi dari batas yang diizinkan 800 kolom. Silakan, gunakan opsi $select eksplisit (termasuk dalam $expand) untuk membatasi jumlah kolom.

Tambahkan klausa $select ke kueri Anda, dan untuk $expand operasi dalam kueri Anda, untuk menghindari melebihi batas ini.

❌ HINDARI membuat kueri panjang

Kami menyarankan agar Anda mengevaluasi pendekatan setiap kali Anda membuat kueri panjang. Meskipun ada banyak skenario yang membutuhkan kueri panjang (misalnya, filter kompleks atau daftar properti yang panjang), biasanya mereka memberikan indikator awal desain suboptimal.

Saat kueri Anda berisi banyak kunci entitas dalam kueri (misalnya, WorkItemId eq {id 1} or WorkItemId eq {id 2} or ...), Anda mungkin bisa menulis ulang. Alih-alih meneruskan pengidentifikasi, coba tentukan beberapa kriteria lain yang memilih kumpulan entitas yang sama. Terkadang mungkin perlu memodifikasi proses Anda (misalnya, menambahkan bidang atau tag baru), tetapi biasanya sepadan. Kueri yang menggunakan filter yang lebih abstrak lebih mudah dipertahankan dan memiliki potensi yang lebih besar untuk bekerja lebih baik.

Skenario lain yang cenderung menghasilkan kueri panjang terjadi ketika Anda menyertakan banyak tanggal individual (misalnya, DateSK eq {dateSK 1} or DateSK eq {dateSK 2} or ...). Cari pola lain yang dapat Anda gunakan untuk membuat filter yang lebih abstrak. Misalnya, kueri berikut mengembalikan semua item kerja yang dibuat pada hari Senin.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=CreatedOn/DayOfWeek eq 2
  &$select=WorkItemId, Title, State

✔️ DO menentukan zona waktu saat memfilter kolom tanggal

Zona waktu (Edm.DateTimeOffset) memaparkan semua informasi tanggal dan waktu dengan offset yang cocok dengan pengaturan zona waktu organisasi. Data ini tepat dan sederhana untuk ditafsirkan secara bersamaan. Konsekuensi lain yang tidak berbahaya adalah bahwa semua filter juga harus melewati informasi zona waktu. Jika Anda melewatinya, Anda akan mendapatkan pesan kesalahan berikut.

Kueri yang ditentukan dalam URI tidak valid. Tidak ada offset tanggalwaktu yang ditentukan. Silakan gunakan salah satu format ini YYYY-MM-ddZ untuk menentukan semuanya sejak tengah malam atau yyyy-MM-ddThh:mm-hh:mm (representasi standar ISO 8601 tanggal dan waktu) untuk menentukan offset.

Untuk mengatasi masalah ini, tambahkan informasi zona waktu. Misalnya, dengan asumsi bahwa organisasi dikonfigurasi untuk menampilkan data di zona waktu "(UTC-08:00) Pacific Time (AS & Kanada)", kueri berikut mendapatkan semua item kerja yang dibuat sejak awal 2020.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=CreatedDate ge 2020-01-01T00:00:00-08:00
  &$select=WorkItemId, Title, State

Solusi yang sama berfungsi untuk zona waktu dengan offset positif, namun, karakter plus (+) memiliki arti khusus dalam URI dan Anda harus menanganinya dengan benar. Jika Anda menentukan 2020-01-01T00:00:00+08:00 (dengan + karakter) sebagai titik awal, Anda akan mendapatkan kesalahan berikut.

Kueri yang ditentukan dalam URI tidak valid. Kesalahan sintaks pada posisi 31 di 'CreatedDate ge 2020-01-01T0000 08:00'.

Untuk mengatasinya, ganti + karakter dengan versi yang dikodekan, %2B. Misalnya, dengan asumsi bahwa organisasi dikonfigurasi untuk menampilkan data di zona waktu "(UTC+08:00) Beijing, Chongqing, Hong Kong, Urumqi", kueri berikut mengembalikan semua item kerja yang dibuat sejak awal 2020.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=CreatedDate ge 2020-01-01T00:00:00%2B08:00
  &$select=WorkItemId, Title, State

Pendekatan alternatif adalah menggunakan properti kunci pengganti tanggal karena tidak menyimpan informasi zona waktu. Misalnya, kueri berikut mengembalikan semua item kerja yang dibuat sejak awal 2020 terlepas dari pengaturan organisasi.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=CreatedDateSK ge 20200101
  &$select=WorkItemId, Title, State

Pedoman performa

Boleh

Jangan lakukan itu.

Pertimbangan

Hindari

✔️ DO mengukur efek penerapan pedoman performa

Seperti halnya rekomendasi performa apa pun, Anda tidak boleh mengimplementasikannya secara membabi buta. Sebagai gantinya, selalu ambil garis besar dan ukur efek perubahan yang Anda buat. Semua pedoman dibuat berdasarkan interaksi dengan klien Analytics yang memiliki persyaratan dan tantangan khusus. Rekomendasi ini dianggap umum dan berpotensi berguna bagi siapa pun yang merancang kueri serupa. Namun, dalam kasus yang jarang terjadi, mengikuti pedoman tidak akan berpengaruh atau bahkan efek negatif pada performa. Anda perlu mengukur perbedaan untuk melihatnya. Jika hal ini terjadi, berikan umpan balik di portal Komunitas Pengembang.

Ada banyak opsi untuk mengukur performa. Yang paling sederhana adalah menjalankan dua versi kueri yang sama langsung di browser. Amati waktu yang diperlukan dalam alat pengembang. Misalnya, Anda dapat menggunakan panel Jaringan di Alat Pengembang Microsoft Edge F12). Opsi lain adalah mengambil informasi ini menggunakan Alat Fiddler Web Debugger.

Apa pun pendekatan Anda, jalankan kedua kueri beberapa kali. Misalnya, jalankan kueri masing-masing 30 kali untuk memiliki set sampel yang cukup besar. Kemudian cari tahu karakteristik performa. Analitik mengikuti arsitektur multi-penyewa. Jadi, operasi lain yang terjadi pada saat yang sama dapat memengaruhi durasi kueri Anda.

✔️ DO menggunakan ekstensi agregasi

Sejauh ini hal terbaik yang dapat Anda lakukan untuk meningkatkan performa kueri Anda adalah menggunakan ekstensi agregasi - Ekstensi OData untuk Agregasi Data. Dengan ekstensi agregasi, minta layanan untuk meringkas sisi server data dan mengembalikan respons yang lebih kecil daripada yang dapat Anda ambil dengan menerapkan sisi klien fungsi yang sama. Terakhir, Analytics dioptimalkan untuk jenis kueri ini, jadi manfaatkan kueri tersebut.

Untuk informasi selengkapnya, lihat Data agregat.

✔️ DO menentukan kolom dalam $select klausa

Tentukan kolom yang Anda pedulikan $select dalam klausa. Analitik dibangun di atas teknologi Indeks Penyimpan Kolom. Itu berarti bahwa data adalah penyimpanan dan pemrosesan kueri berbasis kolom. Dengan mengurangi kumpulan properti, Anda mereferensikan dalam $select klausul, Anda dapat mengurangi jumlah kolom yang harus dipindai dan meningkatkan performa kueri secara keseluruhan.

Misalnya, kueri berikut menentukan kolom untuk item kerja.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $select=WorkItemId, Title, State

Catatan

Azure DevOps mendukung kustomisasi proses. Beberapa administrator menggunakan fitur ini dan membuat ratusan bidang kustom. Jika Anda menghilangkan $select klausa, kueri Anda mengembalikan semua bidang, termasuk bidang kustom.

✔️ DO menentukan kolom dalam $select opsi perluas di $expand dalam klausa

Demikian $select pula dengan pedoman klausul, tentukan properti dalam opsi perluas dalam $select $expand klausa. Mudah dilupakan, tetapi jika Anda menghilangkannya, respons Anda berisi semua properti dari objek yang diperluas.

Misalnya, kueri berikut menentukan kolom untuk item kerja dan induknya.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $select=WorkItemId, Title, State
  &$expand=Parent($select=WorkItemId, Title, State)

✔️ DO menentukan filter saat RevisedDateSK Anda mengkueri data item kerja historis (WorkItemRevisions atau WorkItemSnapshot kumpulan entitas)

Saat Anda mengkueri data historis, kemungkinan Anda tertarik pada periode terbaru (misalnya, 30 hari, 90 hari). Karena bagaimana entitas item kerja diterapkan, ada cara mudah bagi Anda untuk menulis kueri tersebut untuk mendapatkan performa yang hebat. Setiap kali Anda memperbarui item kerja, item tersebut membuat revisi baru dan merekam tindakan ini di System.RevisedDate bidang , yang membuatnya sempurna untuk filter riwayat.

Di Analytics, tanggal yang direvisi ditampilkan di RevisedDate properti (Edm.DateTimeOffset) dan RevisedDateSK (Edm.Int32). Untuk performa terbaik, gunakan yang terakhir. Ini adalah kunci pengganti tanggal dan mewakili tanggal ketika revisi dibuat atau memiliki null untuk revisi aktif yang tidak lengkap. Jika Anda menginginkan semua tanggal sejak inklusif {startDate} , tambahkan filter berikut ke kueri Anda.

RevisedDateSK eq null or RevisedDateSK gt {startDateSK}

Misalnya, kueri berikut mengembalikan jumlah item kerja untuk setiap hari sejak awal 2020. Perhatikan bahwa selain filter yang jelas pada DateSK kolom ada filter kedua pada RevisedDateSK. Meskipun mungkin tampak berlebihan, ini membantu mesin kueri untuk memfilter revisi yang tidak berada dalam cakupan dan secara signifikan meningkatkan performa kueri.

https://analytics.dev.azure.com/{OrganizationName}/_odata/v1.0/WorkItemSnapshot?
  $apply=
    filter(DateSK gt 20200101)/
    filter(RevisedDateSK eq null or RevisedDateSK gt 20200101)/
    groupby(
      (DateValue), 
      aggregate($count as Count)
    )

Catatan

Kami datang dengan rekomendasi ini ketika kami bekerja pada widget Burndown. Awalnya kami mendefinisikan filter hanya untuk DateSK tetapi kami tidak bisa mendapatkan kueri ini untuk menskalakan dengan baik bagi organisasi dengan himpunan data besar. Selama pembuatan profil kueri, kami melihat bahwa DateSK tidak memfilter revisi dengan baik. Hanya setelah kami menambahkan filter pada RevisedDateSK apakah kami bisa mendapatkan performa hebat dalam skala besar.
~ Tim Produk

✔️ DO menggunakan rekam jepret mingguan atau bulanan untuk kueri tren yang mencakup periode waktu yang lama

Secara default, semua tabel rekam jepret dimodelkan sebagai tabel fakta rekam jepret harian. Jika Anda mengkueri rentang waktu, maka akan mendapatkan nilai untuk setiap hari. Rentang waktu yang lama menghasilkan sejumlah besar rekaman. Jika Anda tidak memerlukan presisi tinggi seperti itu, Anda dapat menggunakan rekam jepret mingguan atau bahkan bulanan.

Anda dapat melakukannya dengan ekspresi filter lain untuk menghapus hari yang tidak menyelesaikan minggu atau bulan tertentu. IsLastDayOfPeriod Gunakan properti , yang ditambahkan ke Analytics dengan mengingat skenario ini. Properti ini berjenis Microsoft.VisualStudio.Services.Analytics.Model.Period dan dapat menentukan apakah satu hari selesai dalam periode yang berbeda (misalnya, minggu, bulan, dan sebagainya).

<EnumType Name="Period" IsFlags="true">
  <Member Name="None" Value="0"/>
  <Member Name="Day" Value="1"/>
  <Member Name="WeekEndingOnSunday" Value="2"/>
  <Member Name="WeekEndingOnMonday" Value="4"/>
  <Member Name="WeekEndingOnTuesday" Value="8"/>
  <Member Name="WeekEndingOnWednesday" Value="16"/>
  <Member Name="WeekEndingOnThursday" Value="32"/>
  <Member Name="WeekEndingOnFriday" Value="64"/>
  <Member Name="WeekEndingOnSaturday" Value="128"/>
  <Member Name="Month" Value="256"/>
  <Member Name="Quarter" Value="512"/>
  <Member Name="Year" Value="1024"/>
  <Member Name="All" Value="2047"/>
</EnumType>

Karena Microsoft.VisualStudio.Services.Analytics.Model.Period didefinisikan sebagai enum dengan bendera, gunakan operator OData has dan tentukan jenis lengkap untuk literal periode.

IsLastDayOfPeriod has Microsoft.VisualStudio.Services.Analytics.Model.Period'Month'

Misalnya, kueri berikut mengembalikan jumlah item kerja yang ditentukan pada hari terakhir setiap bulan.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItemSnapshot?
  $apply=
    filter(IsLastDayOfPeriod has Microsoft.VisualStudio.Services.Analytics.Model.Period'Month')/
    groupby(
      (DateValue), 
      aggregate($count as Count)
    )

✔️ DO menggunakan Tags properti koleksi pada item kerja saat memfilter menurut tag

Anda dapat menggunakan TagNames properti dengan contains fungsi untuk menentukan apakah pekerjaan telah ditandai dengan tag tertentu. Namun, pendekatan ini dapat mengakibatkan kueri lambat, terutama saat memeriksa beberapa tag secara bersamaan. Untuk performa dan hasil terbaik, gunakan properti navigasi sebagai gantinya Tags .

Misalnya, kueri berikut mendapatkan semua item kerja yang ditandai dengan {tag}.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Tags/any(t:t/TagName eq '{tag}')
  &$select=WorkItemId, Title, State

Pendekatan ini juga berfungsi dengan baik ketika Anda perlu memfilter beberapa tag. Misalnya, kueri berikut mengembalikan semua item kerja yang ditandai dengan {tag1} atau {tag2}

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Tags/any(t:t/TagName eq {tag1} or t/TagName eq {tag2})
  &$select=WorkItemId, Title, State

Anda juga dapat menggabungkan filter ini dengan operator "dan". Misalnya, kueri berikut mendapatkan semua item kerja yang ditandai dengan dan {tag1} {tag2}

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Tags/any(t:t/TagName eq {tag1}) and Tags/any(t:t/TagName eq {tag2})
  &$select=WorkItemId, Title, State

✔️ DO menggunakan TagNames properti jika Anda ingin menampilkan semua tag pada item kerja sebagai teks

Properti Tagsnavigasi , dijelaskan di bagian sebelumnya, sangat bagus untuk pemfilteran. Namun, bekerja dengan mereka menyajikan beberapa tantangan saat kueri mengembalikan tag dalam koleksi berlapis. Model data juga berisi TagNames properti primitif (Edm.String), yang kami tambahkan untuk menyederhanakan skenario konsumsi tag. Ini adalah nilai teks tunggal yang berisi daftar semua tag yang dikombinasikan dengan pemisah titik koma "; " . Gunakan properti ini ketika semua yang Anda pedulikan adalah menampilkan tag bersama-sama. Anda dapat menggabungkannya dengan filter tag yang dijelaskan sebelumnya.

Misalnya, kueri berikut mendapatkan semua item kerja yang ditandai dengan {tag}. Ini mengembalikan ID item kerja, judul, status, dan representasi teks dari tag gabungan.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Tags/any(t:t/TagName eq '{tag}')
  &$select=WorkItemId, Title, State, TagNames

Penting

Properti TagNames memiliki batas panjang 1024 karakter. Ini berisi sekumpulan tag yang pas dalam batas tersebut. Jika item kerja memiliki banyak tag atau tag sangat panjang, maka TagNames jangan berisi set lengkap dan Tag properti navigasi harus digunakan sebagai gantinya.

❌ JANGAN gunakan tolower dan toupper fungsi untuk melakukan perbandingan yang tidak peka huruf besar/kecil

Jika Anda telah bekerja dengan sistem lain, Anda mungkin berharap untuk menggunakan tolower fungsi atau toupper untuk perbandingan yang tidak peka huruf besar/kecil. Dengan Analytics, semua perbandingan string tidak peka huruf besar/kecil secara default, sehingga Anda tidak perlu menerapkan fungsi apa pun untuk menanganinya secara eksplisit.

Misalnya, kueri berikut mendapatkan semua item kerja yang ditandai dengan "QUALITY," "quality," atau kombinasi kasus lain dari kata ini.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Tags/any(t:t/TagName eq 'quality')
  &$select=WorkItemId, Title, State, TagNames

❌ JANGAN gunakan ekspansi yang tidak terbatas dengan $levels=max

OData memiliki kemampuan untuk memperluas semua tingkat struktur hierarkis. Misalnya, pelacakan item kerja memiliki beberapa entitas di mana ekspansi yang tidak terbatas dapat diterapkan. Operasi ini hanya berfungsi untuk organisasi dengan sejumlah kecil data. Ini tidak menskalakan dengan baik untuk himpunan data yang lebih besar. Jangan menggunakannya sekalipun:

  • Anda bekerja dengan himpunan data besar.
  • Anda mengembangkan widget dan Anda tidak memiliki kontrol atas tempat widget diinstal.

✔️ DO menggunakan halaman berbasis server

Jika Anda meminta set yang terlalu besar untuk dikirim dalam satu respons, Analytics menerapkan halaman. Respons hanya mencakup set parsial dan tautan yang memungkinkan pengambilan kumpulan item parsial berikutnya. Strategi ini dijelaskan dalam spesifikasi OData - OData Versi 4.0. Bagian 1: Protokol - Halaman Berbasis Server. Dengan membiarkan layanan mengontrol halaman, Anda mendapatkan performa skiptoken terbaik karena telah dirancang dengan hati-hati agar setiap entitas seefisien mungkin.

Tautan ke halaman berikutnya disertakan @odata.nextLink dalam properti .

{
  "@odata.context": "https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/$metadata#WorkItems(*)",
  "value": [
    ...
  ],
  "@odata.nextLink":"https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?$skiptoken=12345"}

Catatan

Sebagian besar klien OData yang ada dapat menangani halaman berbasis server secara otomatis. Misalnya strategi ini sudah digunakan oleh alat berikut: Power BI, SQL Server Integration Services, dan Azure Data Factory.

❌ JANGAN gunakan $top opsi kueri dan $skip untuk mengimplementasikan halaman berbasis klien

Dengan REST API lainnya, Anda mungkin telah menerapkan halaman berbasis klien dengan $top opsi kueri dan .$skip Jangan gunakan dengan Analytics. Ada beberapa masalah dengan pendekatan dan performa ini adalah salah satunya. Sebagai gantinya, adopsi strategi halaman berbasis server yang dijelaskan di bagian sebelumnya.

✔️ DO menggunakan $top opsi kueri untuk membatasi jumlah rekaman

Opsi $top kueri hanya disarankan saat digunakan bersama dengan $skip. Jika dalam skenario pelaporan Anda, Anda hanya memerlukan subset rekaman (misalnya, sampel), tidak masalah untuk menggunakan $top opsi kueri. Selain itu, jika Anda perlu memberi peringkat rekaman sesuai dengan beberapa kriteria, Anda harus selalu menggunakan $top dalam kombinasi untuk $orderby mendapatkan hasil yang stabil dengan catatan peringkat teratas.

✔️ PERTIMBANGKAN untuk menulis kueri untuk mengembalikan sejumlah kecil rekaman

Menulis kueri untuk mengembalikan sejumlah kecil rekaman adalah pedoman yang paling intuitif. Selalu bertujuan untuk mengambil hanya data yang benar-benar Anda pedulikan. Anda dapat mencapainya dengan membuat sebagian besar kemampuan pemfilteran yang canggih tersedia dalam bahasa kueri OData.

✔️ PERTIMBANGKAN untuk membatasi jumlah properti yang dipilih minimal

Beberapa administrator proyek sangat menyesuaikan prosesnya dengan menambahkan bidang kustom. Kustomisasi berat dapat menyebabkan masalah performa saat mengambil semua kolom yang tersedia pada entitas luas (misalnya, WorkItems). Analitik dibangun di atas teknologi Indeks Penyimpan Kolom. Itu berarti bahwa data adalah penyimpanan dan pemrosesan kueri berbasis kolom. Jadi, semakin banyak properti yang dirujuk kueri, semakin mahal untuk diproses. Selalu bertujuan untuk membatasi sekumpulan properti dalam kueri Anda terhadap apa yang benar-benar Anda pedulikan dalam skenario pelaporan Anda.

✔️ PERTIMBANGKAN pemfilteran pada properti kunci pengganti tanggal (DateSK akhiran)

Ada banyak cara untuk menentukan filter tanggal. Anda dapat memfilter properti tanggal secara langsung (misalnya, CreatedDate), mitra navigasinya (misalnya, CreatedOnDate), atau representasi kunci penggantinya (misalnya, CreatedDate). Opsi terakhir menghasilkan performa terbaik dan lebih disukai ketika persyaratan pelaporan memungkinkannya.

Misalnya, kueri berikut mendapatkan semua item kerja yang dibuat sejak awal 2020.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=CreatedDateSK ge 20200101

✔️ PERTIMBANGKAN pemfilteran pada kolom kunci pengganti

Jika Anda ingin memfilter data pada nilai objek terkait (misalnya, memfilter item kerja pada nama proyek), Anda selalu memiliki dua pilihan. Anda dapat menggunakan properti navigasi (misalnya, Project/ProjectName) atau mengambil kunci pengganti di muka dan menggunakannya langsung dalam kueri (misalnya, ProjectSK).

Jika Anda membuat widget, kami sarankan Anda menggunakan opsi terakhir. Ketika kunci diteruskan sebagai bagian dari kueri, jumlah set entitas yang harus disentuh berkurang dan performa meningkat.

Misalnya, filter WorkItems kueri berikut menggunakan ProjectSK properti daripada Project/ProjectName properti navigasi.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectSK eq {projectSK}

❌AVOID menggunakan Parentproperti , Children, atau Revisions dalam $filter klausul atau $expand

Item kerja adalah entitas paling mahal dalam seluruh model data. Mereka memiliki beberapa properti navigasi yang dapat Anda gunakan untuk mengakses item kerja terkait: Parent, , RevisionsChildren. Namun, setiap kali Anda menggunakannya dalam kueri, mengharapkan penurunan performa. Selalu tanyakan apakah Anda benar-benar membutuhkan salah satu properti ini dan berpotensi memperbarui desain Anda.

Misalnya, alih-alih memperluas Parent, Anda dapat mengambil lebih banyak item kerja dan menggunakan ParentWorkItemId properti untuk merekonstruksi sisi klien hierarki lengkap. Lakukan pengoptimalan tersebut berdasarkan kasus per kasus.

✔️ PERTIMBANGKAN untuk meneruskan VSTS.Analytics.MaxSize preferensi di header

Saat menjalankan kueri, Anda tidak tahu jumlah rekaman yang dikembalikan kueri. Kirim kueri lain dengan agregasi atau ikuti semua tautan berikutnya dan ambil seluruh himpunan data. Analitik menghormati VSTS.Analytics.MaxSize preferensi, yang memungkinkan Anda gagal dengan cepat dalam instans tersebut bahwa himpunan data lebih besar dari apa yang dapat diterima klien Anda.

Opsi ini berguna dalam skenario ekspor data. Untuk menggunakannya, Anda harus menambahkan Prefer header ke permintaan HTTP Anda dan mengatur VSTS.Analytics.MaxSize ke nilai non-negatif. Nilai VSTS.Analytics.MaxSize menunjukkan jumlah maksimum rekaman yang bisa Anda terima. Jika Anda mengaturnya ke nol, maka nilai default 200 K akan digunakan.

Misalnya, kueri berikut mengembalikan item kerja jika himpunan data lebih kecil atau sama dengan 1000 rekaman.

GET https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems HTTP/1.1
User-Agent: {application}
Prefer: VSTS.Analytics.MaxSize=1000
OData-MaxVersion: 4.0
Accept: application/json;odata.metadata=minimal
Host: analytics.dev.azure.com/{OrganizationName}

Jika himpunan data melebihi batas 1000 rekaman, kueri segera gagal dengan kesalahan berikut.

Hasil kueri berisi 1.296 baris dan melebihi ukuran maksimum yang diizinkan 1000. Kurangi jumlah rekaman dengan menerapkan filter tambahan

Untuk informasi tentang mengatur ukuran halaman maksimum, lihat properti ODataPreferenceHeader.MaxPageSize.

Panduan gaya kueri

✔️ DO menggunakan $count properti virtual dalam metode agregasi

Beberapa entitas mengekspos Count properti. Mereka membuat beberapa skenario pelaporan lebih mudah ketika data diekspor ke penyimpanan yang berbeda. Namun, Anda tidak boleh menggunakan kolom ini dalam agregasi dalam kueri OData. Gunakan properti virtual sebagai gantinya $count .

Misalnya, kueri berikut mengembalikan jumlah total item kerja.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $apply=aggregate($count as Count)

❌ HINDARI menggunakan $count properti virtual di segmen URL

Meskipun standar OData memungkinkan Anda menggunakan $count properti virtual untuk kumpulan entitas (misalnya, _odata/v1.0/WorkItems/$count), tidak semua klien dapat menginterpretasikan respons dengan benar. Jadi, disarankan untuk menggunakan agregasi sebagai gantinya.

Misalnya, kueri berikut mengembalikan jumlah total item kerja.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $apply=aggregate($count as Count)

✔️ PERTIMBANGKAN menggunakan alias parameter untuk memisahkan bagian kueri yang volatil

Alias parameter menyediakan solusi elegan untuk mengekstrak komponen volatil seperti nilai parameter dari teks kueri utama. Anda dapat menggunakannya dalam ekspresi yang mengevaluasi:

  • Nilai primitif
  • Nilai kompleks
  • Kumpulan nilai primitif atau kompleks.

Untuk informasi selengkapnya, lihat OData Versi 4.0. Bagian 2: Konvensi URL - Alias Parameter 5.1.1.13. Parameter berguna saat teks kueri digunakan sebagai templat yang dapat diinstansiasi dengan nilai yang disediakan pengguna.

Misalnya, kueri berikut menggunakan @createdDateSK parameter untuk memisahkan nilai dari ekspresi filter.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=CreatedDateSK ge @createdDateSK
  &$select=WorkItemId, Title, State
  &@createdDateSK=20200101

❌ MENGHINDARI pencampuran $apply dan $filter klausa dalam satu kueri

Jika Anda ingin menambahkan filter ke kueri, Anda memiliki dua opsi. Anda dapat melakukannya dengan $filter klausa atau $apply=filter() kombinasi. Masing-masing opsi ini berfungsi dengan baik sendiri, tetapi menggabungkannya bersama-sama dapat menyebabkan beberapa hasil yang tidak terduga.

Terlepas dari harapan yang mungkin dimiliki, OData dengan jelas mendefinisikan urutan evaluasi. Selain itu $apply , klausul memiliki prioritas atas $filter. Untuk alasan ini, Anda harus memilih satu atau yang lain tetapi hindari dua opsi filter ini dalam satu kueri. Penting jika kueri dibuat secara otomatis.

Misalnya, kueri berikut pertama-tama memfilter item kerja menurut StoryPoint gt 5, hasil agregat menurut adalah jalur dan akhirnya memfilter hasilnya dengan StoryPoints gt 2. Dengan urutan evaluasi ini, kueri selalu mengembalikan set kosong.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=StoryPoints gt 2
  $apply=
    filter(StoryPoints gt 5)/
    groupby(
      (Area/AreaPath),
      aggregate(StoryPoints with sum as StoryPoints)
    )

✔️ PERTIMBANGKAN untuk menyusun kueri Anda agar sesuai dengan urutan evaluasi OData

Karena pencampuran dan filter klausa dalam satu kueri dapat menyebabkan potensi kebingungan$apply, kami sarankan Anda menyusun klausul kueri agar sesuai dengan urutan evaluasi.

  1. $apply
  2. $filter
  3. $orderby
  4. $expand
  5. $select
  6. $skip
  7. $top

✔️ PERTIMBANGKAN untuk meninjau kemampuan OData yang dijelaskan dalam anotasi metadata

Saat Anda tidak yakin tentang kemampuan OData mana yang didukung Analytics, Anda dapat mencari anotasi dalam metadata. Komite Teknis OASIS Open Data Protocol (OData) dalam repositori TC GitHub mempertahankan daftar anotasi yang tersedia.

Misalnya, daftar fungsi filter yang didukung tersedia dalam Org.OData.Capabilities.V1.FilterFunctions anotasi pada kontainer entitas.

<Annotation Term="Org.OData.Capabilities.V1.FilterFunctions">
  <Collection>
  <String>contains</String>
  <String>endswith</String>
  [...]
  </Collection>
</Annotation>

Anotasi berguna lainnya adalah Org.OData.Capabilities.V1.ExpandRestrictions, yang menjelaskan properti navigasi mana yang tidak dapat Anda gunakan dalam $expand klausa. Misalnya, anotasi berikut menjelaskan bahwa Revisions dalam WorkItems kumpulan entitas tidak dapat diperluas.

<EntitySet Name="WorkItems" EntityType="Microsoft.VisualStudio.Services.Analytics.Model.WorkItem">
  [...]
  <Annotation Term="Org.OData.Capabilities.V1.ExpandRestrictions">
    <Record>
      <PropertyValue Property="Expandable" Bool="true"/>
      <PropertyValue Property="NonExpandableProperties">
        <Collection>
          <NavigationPropertyPath>Revisions</NavigationPropertyPath>
        </Collection>
      </PropertyValue>
    </Record>
  </Annotation>
</EntitySet>