Kueri yang dilingkup proyek dan organisasi

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

Dengan menggunakan Analytics untuk Azure DevOps, Anda dapat membuat kueri yang dilingkupkan ke proyek atau organisasi atau koleksi. Anda bisa menjalankan kueri ini langsung di browser Anda atau di dalam Power BI.

Kueri cakupan proyek membantu menjawab pertanyaan tentang satu proyek sedangkan kueri terlingkup organisasi dan koleksi memungkinkan Anda menjawab pertanyaan yang melintasi batas proyek. Kueri tercakup organisasi dan pengumpulan memerlukan izin pengguna yang lebih luas atau pembatasan cakupan yang cermat untuk memastikan bahwa kueri Anda tidak diblokir karena kurangnya izin.

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.

Prasyarat

• Untuk melihat data Analitik dan mengkueri layanan, Anda harus menjadi anggota proyek dengan akses Dasar atau yang lebih besar. Secara default, semua anggota proyek diberikan izin untuk mengkueri Analitik dan menentukan tampilan Analitik.
• Untuk mempelajari tentang prasyarat lain mengenai pengaktifan layanan dan fitur serta aktivitas pelacakan data umum, lihat Izin dan prasyarat untuk mengakses Analitik.

Penting

Jika Anda tidak memiliki akses ke semua proyek dalam organisasi, disarankan agar Anda menerapkan filter proyek ke semua kueri Anda. Saat menarik data ke alat klien seperti Power BI atau Excel, menggunakan sintaks jalur proyek adalah cara terbaik untuk memastikan bahwa semua data Anda dibatasi oleh proyek tertentu. Sebaiknya Gunakan kueri yang terlingkup organisasi atau cakupan koleksi hanya saat Anda perlu melaporkan dua proyek atau lebih.

Kueri cakupan proyek

Anda membuat kueri dengan memasukkan URL OData ke browser web yang didukung.

URL dasar untuk kueri OData tingkat proyek seperti yang diperlihatkan dalam sintaks berikut.

Cloud (Layanan Azure DevOps

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/

Dalam contoh yang disediakan, ganti {OrganizationName} dan {ProjectName} dengan nama organisasi dan proyek yang ingin Anda kueri.

Lokal (Azure DevOps Server

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

Dalam contoh yang disediakan, buat penggantian berikut:

• analytics.dev.azure.comdengan{ServerName}:{Port}/tfs/
• {CollectionName} dengan nama koleksi proyek Anda (defaultnya adalah DefaultCollection)
• {ProjectName} dengan nama proyek yang ingin Anda kueri.

Catatan

Contoh yang tersisa yang disediakan dalam artikel ini didasarkan pada URL Layanan Azure DevOps. Anda harus mengganti di URL Server Azure DevOps Anda untuk menjalankan contoh.

Mengembalikan jumlah item kerja

Misalnya, kueri cakupan proyek berikut mengembalikan jumlah item kerja untuk proyek tertentu.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/WorkItems/$count

Misalnya, kueri proyek Fabrikam Fiber mengembalikan hitungan 7126 item kerja. Item kerja yang dihapus tidak disertakan dalam hitungan.

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v1.0/WorkItems/$count

7126

Mengembalikan Jalur Area proyek

Demikian juga, string kueri berikut akan mengembalikan area untuk proyek tertentu:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/Areas

Ini setara dengan filter berikut pada kueri cakupan organisasi:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/Areas?
  $filter=Project/ProjectName eq '{ProjectName}'

Misalnya, kueri proyek Fabrikam Fiber mengembalikan semua properti yang ditentukan untuk Jalur Area karena tidak ada $select operator yang diterapkan dalam kueri.

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v1.0/Areas

Contoh berikut menunjukkan data yang dikembalikan untuk satu Jalur Area.

ProjectSK	"56af920d-393b-4236-9a07-24439ccaa85c"
AreaSK	"26be05fd-e68a-4fcb-833f-497f6bee45f2"
AreaId	"26be05fd-e68a-4fcb-833f-497f6bee45f2"
AreaName	"Service Delivery"
Number	55373
AreaPath	"Fabrikam Fiber\\Service Delivery"
AreaLevel1	"Fabrikam Fiber"
AreaLevel2	"Service Delivery"
AreaLevel3	null
AreaLevel4	null
AreaLevel5	null
AreaLevel6	null
AreaLevel7	null
AreaLevel8	null
AreaLevel9	null
AreaLevel10	null
AreaLevel11	null
AreaLevel12	null
AreaLevel13	null
AreaLevel14	null
Depth	1

Penggunaan opsi $expand

Saat menggunakan kueri cakupan proyek dengan $expand opsi, Anda tidak diharuskan menyediakan filter lain.

Misalnya, filter cakupan proyek berikut:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/WorkItems?
  $expand=Parent

difilter secara otomatis untuk memberlakukan keamanan:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Parent($filter=ProjectName eq '{ProjectName}')

Kueri yang dilingkup organisasi

URL Dasar untuk kueri tingkat organisasi seperti yang ditunjukkan:

https://analytics.dev.azure.com/{OrganizationName}/_odata/v1.0

Saat menggunakan kueri yang dilingkup organisasi dengan $expand opsi, Anda harus menyediakan filter lain.

Misalnya, kueri cakupan organisasi berikut, yang menggunakan $expand untuk mengambil anak dari semua item kerja.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Children

Ini memerlukan filter lain untuk memverifikasi bahwa anak-anak terbatas pada proyek yang ditentukan:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Children($filter=Project/ProjectName eq '{ProjectName}')

Mengembalikan induk dari semua item kerja

Kueri berikut, yang menggunakan $expand opsi untuk mengambil induk semua item kerja.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Parent

Ini memerlukan filter lain untuk memverifikasi bahwa induk terbatas pada proyek yang ditentukan:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Parent($filter=Project/ProjectName eq '{ProjectName}')

Tanpa filter lain, permintaan akan gagal jika induk item kerja mereferensikan item kerja dalam proyek yang tidak dapat Anda akses baca.

Pembatasan keamanan tingkat proyek

Analitik memiliki beberapa batasan lagi pada sintaks kueri yang terkait dengan keamanan tingkat proyek.

Filter any atau all berlaku untuk entitas dasar pada $expand. Untuk filter berdasarkan proyek, kami secara eksplisit mengabaikan filter saat menggunakan $expand:

Misalnya, kueri berikut:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Children($filter=Project/ProjectName eq '{ProjectName}')

Ditafsirkan sebagai:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Children

dan akan gagal jika Anda tidak memiliki akses ke semua proyek.

Untuk mengatasi pembatasan, Anda perlu menambahkan ekspresi tambahan di $filter:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}' and Children/any(r: r/ProjectName eq '{ProjectName}')
  &$expand=Children

Penggunaan $level hanya didukung jika Anda memiliki akses ke semua proyek dalam koleksi atau saat menggunakan kueri cakupan proyek:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $expand=Children($levels=2;$filter=ProjectName eq '{ProjectName}')

Analitik tidak mendukung referensi lintas tingkat untuk proyek menggunakan $it klausa. Sebagai contoh, kueri berikut mereferensikan item ProjectName kerja akar menggunakan $it alias, yang tidak didukung:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $expand=Links(
    $expand=TargetWorkItem;
    $filter=TargetWorkItem/Project/ProjectName eq $it/Project/ProjectName)

Langkah selanjutnya

Data agregat kueri

Artikel terkait

• Panduan kueri