Azure DevOps'ta Analiz için OData sorguları oluşturma

  • Makale

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Azure DevOps için raporlama platformu analiz, projelerinizin geçmiş veya mevcut durumuyla ilgili nicel soruları yanıtlayabilir. Analiz, meta verilerinin ve varlık kümesi verilerinin OData sorgularını destekler. Web tarayıcınızdan basit sorgular kullanarak veri modeli ve sorgu işlemi hakkında bilgi edinebilirsiniz.

Bu makalede şunları öğreneceksiniz:

  • Bulut veya şirket içi için Analytics OData sorgusu oluşturma
  • Analytics meta verilerini sorgulama
  • Varlık kümesi için Analytics OData sorgulama
  • Hangi sorgu seçeneklerinin desteklendiği ve önerilen sıra
  • Sunucu tarafı disk belleği uygulandığında

Desteklenen herhangi bir web tarayıcısından Analytics'i sorgulayabilirsiniz. Analytics'i sorgulamak için kullanabileceğiniz diğer araçlar için bkz . Analiz sorgu araçları.

Not

RESTful (REST=Temsili Durum Aktarımı) arabirimleri aracılığıyla verilerle etkileşime geçmek için kullanılan uygulama düzeyinde bir protokol olan OData, veri modellerinin açıklamasını ve bu modellere göre verilerin düzenlenmesini ve sorgulanmasını destekler. Varlık Veri Modeli (EDM) veya meta veriler, raporlar oluşturmak için verileri sorgulamak için kullandığınız varlıklar, varlık türleri, özellikler, ilişkiler ve numaralandırmalar da dahil olmak üzere Analytics'ten edinilebilen bilgileri açıklar. OData'ya genel bakış için bkz . OData'ya Hoş Geldiniz.

Önkoşullar

  • Analytics verilerini görüntülemek ve hizmeti sorgulamak için Temel erişim veya daha yüksek erişime sahip bir projenin üyesi olmanız gerekir. Varsayılan olarak, tüm proje üyelerine Analytics'i sorgulama ve Analiz görünümlerini tanımlama izinleri verilir.
  • Hizmet ve özellik etkinleştirme ve genel veri izleme etkinlikleriyle ilgili diğer önkoşullar hakkında bilgi edinmek için bkz . Analytics'e erişim izinleri ve önkoşulları.

Meta verileri sorgulamak için URL bileşenleri

Analiz, hizmet kök URL'sine eklenerek $metadata oluşturulan meta veri URL'sinde varlık modelini kullanıma sunar. Analiz, Azure DevOps'ta bir proje veya kuruluşun tamamı için hizmet kökleri sağlar.

Meta verileri sorgulayarak aşağıdaki veri öğelerinden herhangi birini arayabilirsiniz.

  • Varlık türleri ve varlık kümeleri
  • Özellikler ve gezinti özellikleri
  • Vekil anahtarlar
  • Numaralandırılmış listeler
  • Entityset
  • Kapsayıcılar
  • Filtre işlevleri (Org.OData.Capabilities.V1.FilterFunctions)
  • Desteklenen toplamalar (Org.OData.Aggregation.V1.ApplySupported)
  • Batch desteği (Org.OData.Capabilities.V1.BatchSupportType)

Kullandığınız URL, Azure DevOps Services (bulut) için verileri mi yoksa şirket içi Azure DevOps Server'ı mı sorguladığınıza bağlıdır.

Bulutta barındırılan bir kuruluşun veya projenin meta verilerini sorgulamak için, web tarayıcısında aşağıda gösterildiği gibi URL söz dizimini girin. ve {ProjectName} değerini kuruluşunuzun adıyla ve sorgulamak istediğiniz projenin adıyla değiştirin{OrganizationName}. Kuruluşun tüm meta verilerini döndürmek için proje adını belirtmeyin.

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

Not

En son Analytics OData sürümü v4.0-preview sürümüdür. Barındırılan hizmete yönelik tüm sorgular için bu sürümü kullanabilirsiniz. Analytics sürümleri ve kullanılabilir veriler hakkında daha fazla bilgi için bkz . Analytics için veri modeli.

Aşağıda, Azure DevOps Services üzerinde barındırılan fabrikam kuruluşu için bir örnek verilmiştir.

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

Meta veri yanıtını yorumlama

Analiz, veri modelinin XML dosyasını döndürür. İlgilendiğiniz varlığa özgü bilgileri bulmak için tarayıcı arama işlevinizi kullanın.

İpucu

Kullandığınız tarayıcıya bağlı olarak, bu dosya okunabilir bir şekilde biçimlendirilebilir veya biçimlendirilmeyebilir. Biçimlendirilmemişse, web tarayıcısı araması aracılığıyla ücretsiz bir çevrimiçi XML biçimlendirici bulabilirsiniz.

Analytics meta verilerinde tanımlanan iki ana şema, Microsoft.VisualStudio.Services.Analytics.Modelvarlık türlerini ve numaralandırılmış türleri ve üyelerini Default tanımlayan ve varlık kapsayıcılarını ve varlık kümelerini ve desteklenen OData filtresi, dönüştürme ve özel toplama işlevlerini tanımlayan şemadır. Daha fazla bilgi için bkz . Analytics OData meta verileri.

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

Tüm varlık türleri özellikler ve gezinti özellikleriyle ilişkilendirilir. Varlık kümesi sorgularınızı bu özellik türlerini kullanarak filtreleyebilirsiniz. Bunlar, veya altındaki EntityTypePropertyNavigationalPropertymeta verilerde listelenir. Yineleme Yolları, Alan Yolları veya Teams gibi ek filtreler belirtmek için ilgili varlıkları kullanırsınız.

Aşağıdaki kod parçacığı, varlığın meta verilerinin WorkItem kısmi bir görünümünü sağlar. Özellikler, hem bir iş öğesi alanına hem de Analytics tarafından yakalanan ve CycleTimeDaysgibi LeadTimeDays belirli verilere karşılık gelir. Gezinti özellikleri diğer varlık kümelerine veya varlık türü için yakalanan , Links, Childrenve Parentgibi Revisionsbelirli Analytics verilerine karşılık gelir.

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

Varlıkları sorgulamak için URL bileşenleri

Analytics verilerini sorgulamak ve raporlar oluşturmak için genellikle bir varlık kümesini sorgularsınız. Desteklenen varlıklara genel bakış için bkz . Analytics OData meta verileri.

Aşağıdaki URL, , WorkItemSnapshotve PipelineRunsgibi WorkItemsbelirli EntitySetbir öğesini sorgulamak için kullanılır.

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

Fabrikam Fiber projesi için tanımlanan iş öğelerinin sayısını döndüren fabrikam kuruluşuna bir örnek aşağıda verilmiştir.

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

Örnek 1399 iş öğesi döndürür.

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

Not

Or $apply yan tümcesi eklemezseniz$select, Varlık kümesinde bir select deyimi gerçekleştirmeye eşdeğerdir ve her şeyi, tüm sütunları ve tüm satırları döndürme gibi "VS403507: The specified query does not include a $select or $apply clause which is recommended for all queries. Details on recommended query patterns are available here: https://go.microsoft.com/fwlink/?linkid=861060." bir uyarı alırsınız. Çok sayıda kaydınız varsa, bu işlem birkaç saniye sürebilir. 10.000'den fazla iş öğeniz varsa sunucu temelli disk belleği uygulanır.

Kullanım sınırlarıyla karşılaşmamak için her zaman bir $select veya $apply yan tümcesi ekleyin.

Varlık meta verileri özelliği ve ilişki bilgileri için aşağıdaki makalelere bakın:

Örnek: Belirli bir varlık kümesini sorgulama

, veya gibi WorkItemsbelirli bir varlık kümesini sorgulamak için varlık kümesinin adını ekleyin: /WorkItems, /Areasveya /Projects.ProjectsAreas Varlık kümelerinin tam listesi için bkz . Analiz için veri modeli.

Örneğin, özelliğini sorgulayıp /Projects döndürmeyi seçerek kuruluşunuz için tanımlanan projelerin ProjectName listesini alabilirsiniz. Fabrikam kuruluşu için URL aşağıda gösterildiği gibidir.

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

Analiz, fabrikam kuruluşu için tanımlanan projelerin proje adlarını döndürür.

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

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

Sorgu seçenekleri

Sorgu seçeneği, URL'deki kaynak için döndürülen veri miktarını denetlemeye yardımcı olabilecek bir kaynağa uygulanan sorgu dizesi parametreleri kümesidir.

Sorgu seçenekleri aşağıdaki tabloda listelenen sırayla belirtilmelidir.

Sorgu seçeneği Notlar
$apply Bir sorguya uygulayabileceğiniz dönüştürme kümesi; örneğin: filter, groupby, aggregate, compute, , expand,concat
Örnekler için bkz . Analytics kullanarak iş izleme verilerini toplama.
$compute bir veya ifadesinde kullanılabilecek hesaplanan özellikleri tanımlamak için belirtebileceğiniz desteklenen bir $select$filter$orderby OData işlevi.
$filter Döndürülen kaynakların listesini filtrelemek için kullanın. ile $filter belirtilen ifade koleksiyondaki her kaynak için değerlendirilir ve yanıta yalnızca ifadenin true olarak değerlendirildiği öğeler eklenir. İfadenin false veya null olarak değerlendirildiği ya da izinler nedeniyle kullanılamayan başvuru özellikleri yanıttan atlanır.
Örnekler için bkz . Analytics kullanarak iş izleme verilerini sorgulama.
$orderby Kayıtların döndürülmesi gereken sırayı belirtmek için kullanın.
Örnekler için bkz . Analytics kullanarak iş izleme verilerini sorgulama.
$top/$skip Döndürülen kayıt sayısını sınırlamak için kullanın.
Örnekler için bkz . Proje ve kuruluş kapsamındaki sorgular.
$select/$expand Raporunuzu oluşturmak için ihtiyacınız olan sütunları belirtmek için kullanın $select . Diğer sorgu seçeneklerini iç içe yerleştirme için kullanın $expand . Her expandItem biri, genişletilmekte olan gezinti veya akış özelliğini içeren varlığa göre değerlendirilir.

Ayraç içine alınmış sorgu seçeneklerinin noktalı virgülle ayrılmış listesi, gezinti özelliği adına. İzin verilen sistem sorgusu seçenekleri : $filter, $select, $orderby, $skip, $top, $count, $search, ve $expand.
Örnekler için bkz . Analytics kullanarak iş izleme verilerini sorgulama.
$skiptoken Belirtilen sayıda kaydı atlamak için kullanın.
$count veya $count=true Yalnızca kayıt sayısını döndürmek için girin $count . Hem kaydın sayısını hem de sorgulanan verileri döndürmek için girin $count=true.
Örnekler için bkz . Analytics kullanarak iş izleme verilerini toplama.

İpucu

Tek bir sorguda ve $filter yan tümcelerini karıştırmaktan $apply kaçının. Sorgunuzu filtrelemek için iki seçeneğiniz vardır: (1) yan $filter tümce kullanın veya (2) birleşim $apply=filter() yan tümcesi kullanın. Bu seçeneklerin her biri tek başına harika çalışır, ancak bunları bir araya getirmek bazı beklenmeyen sonuçlara yol açabilir.

Sunucu tarafı disk belleğini zorunlu kılma

Sorgu sonuçları 10000 kaydı aştığında analiz disk belleğini zorlar. Bu durumda, sonraki sayfaya ulaşmak için izleyebileceğiniz ilk veri ve bağlantı sayfasını alırsınız. Bağlantı (@odata.nextLink) JSON çıkışının sonunda bulunabilir. Özgün bir sorgu ve ardından $skip veya $skiptokengibi görünür. Örneğin:

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

Not

Power BI Desktop veya Excel gibi istemci araçlarına veri çekerken, araçlar otomatik olarak sonraki bağlantıyı izler ve gerekli tüm kayıtları yükler.

Sonraki adımlar

OData Analytics kullanarak temel sorgular oluşturma