Bagikan melalui

Panduan kueri OData Analytics untuk Azure DevOps

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 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 Pembuatversian 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 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. Jika Anda meningkatkan dari Azure DevOps Server 2019, Anda dapat menginstal layanan Analytics selama peningkatan.

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 Pembuatversian 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 kompromi 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.

Petunjuk

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-peringatan ini karena menyediakan informasi terbaru 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). Pesan rekan tidak muncul dalam properti @vsts.warnings. 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

Yang Harus Dilakukan

Pertimbangan

Terblokir

Hindari

Pastikan Anda membatasi kueri ke proyek-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

✔️ PASTIKAN untuk menentukan penyaring proyek di dalam $expand klausul jika perluasan Anda dapat menyertakan data dalam proyek lain yang mungkin 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 melakukan kueri menggunakan endpoint ruang lingkup proyek

Jika Anda tertarik dengan data dari satu proyek, kami sarankan Anda menggunakan antarmuka OData berlingkup 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 diperlukan 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.

✔️ MOHON 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.

✔️ Harus menunggu atau menghentikan operasi jika kueri Anda gagal karena 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 pada saat akhir setiap hari di masa lampau. Misalnya, jika Anda mengajukan kueri WorkItemSnapshot dan memfilter menjadi satu WorkItemId, Anda akan mendapatkan satu catatan untuk setiap hari sejak item kerja tersebut 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 snapshot dirancang dengan mempertimbangkan 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 kolom DateSK atau DateValue dalam klausul groupby saat Anda mengagregasi tabel snapshot

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 tampak berlebihan dan 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 dalam 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 Alamat Entitas. 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.

Seperti yang ditunjukkan oleh pesan kesalahan, alat klien tertentu dapat menyalahgunakan pemberian 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 menangani 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 berdasarkan pengidentifikasi item kerjanya.

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 di elemen Key dari 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 'Revisions' tidak dapat digunakan dalam pilihan kueri $expand.

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

✔️ GUNAKAN set entitas WorkItemRevisions 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 pengidentifikasi {id}.

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, nyatakan dengan menggunakan filter pada WorkItem properti navigasi. Misalnya, kueri berikut mendapatkan semua revisi dari setiap 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 lebih kolom yang ditentukan dalam klausa GROUP BY dari 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 mendukungnya. 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 kelebihan 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.

✔️ Pastikan menggunakan titik akhir batch untuk kueri panjang

Anda mungkin mengalami masalah dengan kueri yang terlalu panjang. Terutama, masalah mungkin terjadi ketika:

  • Anda menanyakan 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 endpoint 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, namun dapat juga digunakan sebagai solusi untuk batasan panjang permintaan. Dengan mengirim permintaan HTTP POST, Anda dapat meneruskan kueri dengan panjang bebas dan layanan memahaminya dengan benar.

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

Kami membatasi penggunaan endpoint batch untuk memproses beberapa permintaan sekaligus. Satu permintaan hanya bisa memiliki satu pertanyaan. Jika Anda mencoba mengirim sekumpulan beberapa kueri, operasi gagal dengan pesan kesalahan berikut ini. Satu-satunya solusi adalah membagi kueri menjadi beberapa permintaan.

Analytics tidak mendukung pemrosesan beberapa operasi yang terdapat dalam pesan batch yang saat ini sedang diproses. 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 'N' kolom yang melebihi batas yang diizinkan yaitu 800 kolom. Silakan, gunakan opsi $select eksplisit (termasuk dalam $expand) untuk membatasi jumlah kolom.

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

❌ HINDARI membuat kueri yang terlalu panjang

Kami menyarankan agar Anda mengevaluasi pendekatan ketika Anda membuat kueri yang 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 untuk 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 jelas adalah bahwa semua filter harus mengirimkan informasi zona waktu juga. Jika Anda melewatinya, Anda akan mendapatkan pesan kesalahan berikut.

Kueri yang ditentukan dalam URI tidak valid. Tidak ada offset tanggal dan waktu yang disebutkan. 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 kinerja

Yang Harus Dilakukan

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 memang perlu mengukur perbedaan agar dapat menyadarinya. 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. Perhatikan waktu yang dibutuhkan di 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-tenant. Jadi, operasi lain yang terjadi pada saat yang sama dapat memengaruhi durasi kueri Anda.

✔️ Harus 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, mintalah layanan untuk meringkas data di sisi server dan mengembalikan respons yang lebih kecil daripada yang dapat Anda dapatkan dengan menerapkan fungsi yang sama di sisi klien. Terakhir, Analytics dioptimalkan untuk jenis kueri ini, jadi manfaatkan kueri tersebut.

Untuk informasi selengkapnya, lihat Data agregat.

✔️ Harus menentukan kolom dalam klausa $select

Tentukan kolom yang penting bagi Anda dalam klausa $select. Analitik dibangun di atas teknologi Columnstore Index. Itu berarti bahwa baik penyimpanan data maupun pemrosesan kueri berbasis kolom. Dengan mengurangi kumpulan properti yang Anda rujuk dalam klausul $select, Anda dapat mengurangi jumlah kolom yang harus dipindai dan memperbaiki 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.

✔️ Harus menentukan kolom dalam opsi perluasan $select di klausa $expand

Serupa dengan pedoman klausul $select, tentukan properti dalam opsi perluasan $select dalam $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)

✔️ Tentukan filter saat RevisedDateSK Anda melakukan kueri data item kerja historis (WorkItemRevisions atau kumpulan entitas WorkItemSnapshot)

Saat Anda mengkueri data historis, kemungkinan Anda tertarik pada periode terbaru (misalnya, 30 hari, 90 hari). Karena cara implementasi entitas item kerja, ada cara mudah bagi Anda untuk menulis kueri seperti itu guna mendapatkan kinerja yang optimal. 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 dan termasuk {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 merumuskan rekomendasi ini saat kami mengerjakan 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, 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. Gunakan properti IsLastDayOfPeriod, yang ditambahkan ke Analytics dengan mempertimbangkan 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)
    )

✔️ Gunakan properti koleksi Tags pada item kerja saat memfilter berdasarkan 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 kedua {tag1} dan {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 gunakan TagNames properti jika Anda ingin menampilkan semua tag pada item kerja sebagai teks

Properti navigasi Tags, yang dijelaskan di bagian sebelumnya, sangat baik untuk pemfilteran. Namun, bekerja dengan mereka menghadirkan beberapa tantangan karena kueri mengembalikan tag dalam kumpulan bertingkat. 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 fungsi tolower dan toupper untuk melakukan perbandingan yang tidak peka terhadap huruf besar/kecil

Jika Anda telah bekerja dengan sistem lain, Anda mungkin berharap untuk menggunakan fungsi tolower atau toupper untuk perbandingan yang tidak peka huruf besar/kecil. Dengan Analytics, semua perbandingan string tidak peka terhadap huruf besar/kecil secara bawaan, 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 gunakan sama sekali:

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

✔️ DO gunakan halaman berbasis server

Jika Anda meminta set data yang terlalu besar untuk dikirim dalam satu respons, Analytics menerapkan paginasi. 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 - Paging yang Dikendalikan Server. Dengan membiarkan layanan mengontrol paging, Anda mendapatkan performa terbaik dari skiptoken karena telah dirancang dengan hati-hati agar setiap entitas seefisien mungkin.

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

{
  "@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 pagination yang dikendalikan oleh server secara otomatis. Misalnya strategi ini sudah digunakan oleh alat berikut: Power BI, SQL Server Integration Services, dan Azure Data Factory.

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

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

✔️ Sebaiknya gunakan opsi kueri $top untuk membatasi jumlah rekaman

Opsi kueri $top hanya dihindari 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 dengan $orderby untuk mendapatkan hasil yang stabil dengan rekaman peringkat teratas.

✔️ PERTIMBANGKAN untuk menulis kueri untuk mengembalikan sejumlah kecil rekaman

Menulis kueri untuk mengembalikan sejumlah kecil rekaman adalah pedoman yang paling intuitif. Selalu usahakan untuk mengambil hanya data yang Anda butuhkan. 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 Columnstore Index. Itu berarti bahwa baik penyimpanan data maupun pemrosesan kueri berbasis kolom. Jadi, semakin banyak properti yang dirujuk kueri, semakin mahal untuk diproses. Selalu usahakan untuk membatasi kumpulan properti dalam kueri Anda hanya pada yang benar-benar Anda butuhkan 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

✔️ Mempertimbangkan 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, kueri berikut memfilter WorkItems dengan menggunakan properti ProjectSK daripada menggunakan properti navigasi Project/ProjectName.

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

❌ AVOID menggunakan Parent, Children, atau Revisions dalam klausul $filter 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, , ChildrenRevisions. Namun, setiap kali Anda menggunakannya dalam kueri, harapkan 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 properti ParentWorkItemId untuk merekonstruksi hierarki penuh di sisi klien. Lakukan pengoptimalan tersebut berdasarkan kasus per kasus.

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

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 untuk cepat gagal dalam kasus ketika sekumpulan data lebih besar dari yang bisa diterima oleh 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 query

✔️ DO gunakan $count properti virtual dalam metode agregasi

Beberapa entitas memperlihatkan 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 berubah-ubah

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 - 5.1.1.13 Alias Parameter. 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, mengagregasi hasil berdasarkan 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 klausa $apply dan filter dalam satu kueri dapat menyebabkan potensi kebingungan, 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 meninjau kemampuan OData yang dijelaskan di 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>