Azure DevOps için OData Analytics sorgu yönergeleri

  • Makale

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

Uzantı geliştiricileri, Azure DevOps için Analytics'e karşı verimli OData sorguları tasarlamaya yönelik bu makalede sağlanan yönergeleri izleyerek yararlanabilir. Bu yönergelerin takipi, sorguların yürütme süresi ve kaynak tüketimi için iyi bir performansa sahip olduğundan emin olmanıza yardımcı olur. Bu yönergelere uymayen sorgular, uzun rapor bekleme süreleri, izin verilen kaynak tüketimini aşan sorgular veya hizmet engellemeleriyle düşük performansa neden olabilir.

Dekont

Analiz hizmeti, tüm Azure DevOps Services için üretimde otomatik olarak etkinleştirilir ve desteklenir. Power BI tümleştirmesi ve Analiz Hizmeti'nin OData akışına erişim genel olarak kullanılabilir. Bunu kullanmanızı ve bize geri bildirim göndermenizi öneririz. Kullanılabilir veriler sürüme bağlıdır. Desteklenen en son sürüm, v2.0en son önizleme sürümü ise sürümüdür v4.0-preview. Daha fazla bilgi için bkz . OData API sürümü oluşturma.

Dekont

Analytics hizmeti, Azure DevOps Server 2020 ve sonraki sürümleri için tüm yeni proje koleksiyonları için otomatik olarak yüklenir ve üretimde desteklenir. Power BI tümleştirmesi ve Analiz Hizmeti'nin OData akışına erişim genel olarak kullanılabilir. Bunu kullanmanızı ve bize geri bildirim göndermenizi öneririz. Azure DevOps Server 2019'dan yükselttiyseniz yükseltme sırasında Analytics hizmetini yükleyebilirsiniz.

Kullanılabilir veriler sürüme bağlıdır. Desteklenen en son sürüm, v2.0en son önizleme sürümü ise sürümüdür v4.0-preview. Daha fazla bilgi için bkz . OData API sürümü oluşturma.

Dekont

Analiz hizmeti, Azure DevOps Server 2019 için önizleme aşamasındadır. Bir proje koleksiyonu için etkinleştirebilir veya yükleyebilirsiniz . Power BI tümleştirmesi ve Analiz Hizmeti'nin OData akışına erişim Önizleme aşamasındadır. Bunu kullanmanızı ve bize geri bildirim göndermenizi öneririz.

Kullanılabilir veriler sürüme bağlıdır. Desteklenen en son sürüm, v2.0en son önizleme sürümü ise sürümüdür v4.0-preview. Daha fazla bilgi için bkz . OData API sürümü oluşturma.

Bu yönergeler DO, CONSIDER, AVOID ve DON't terimleriyle önekli önerilerimizdir. Analytics tarafından zorunlu kılınan kısıtlayıcı kurallar [ENGELLENDİ] ön ekini içerir. Farklı çözümler arasındaki dengeleri anlamanız gerekir. Belirli koşullar altında, sizi bir veya daha fazla yönergeyi ihlal etmeye zorlayan veri gereksinimleriniz olabilir. Bu tür durumlar nadir olmalıdır. Bu tür kararlar için net ve cazip bir nedeniniz olması önerilir.

Bahşiş

Bu belgede gösterilen örnekler bir Azure DevOps Services URL'sini temel alır. Şirket içi sürümler için değiştirmeleri kullanın.

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

Hata ve uyarı iletileri

✔️ DO OData yanıt uyarılarını gözden geçirin

Yürüttüğüniz her sorgu önceden tanımlanmış kurallar kümesine göre denetlenir. İhlaller, aşağıdaki @vsts.warningsOData yanıtını döndürür. Sorgunuzu geliştirme hakkında geçerli ve bağlama duyarlı bilgiler sağlarken bu uyarıları gözden geçirin.

{
  "@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, OData hata iletilerini gözden geçirme

OData hata kuralını ihlal eden sorgular, 400 (Hatalı İstek) durum koduyla başarısız yanıtla sonuçlanır. İlişkili iletiler özelliğinde @vsts.warnings görünmez. Bunun yerine, JSON yanıtında message özelliğinde bir hata iletisi oluşturur.

{
  "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."
  }
}

Kısıtlamalar

Do's

Dikkat edilmesi gerekenler

Engellendi

Önleme

✔️ SORGUYU erişiminiz olan proje veya projelerde sınırlayın

Sorgunuz erişiminiz olmayan bir projedeki verileri hedeflediyse, sorgu "Proje erişimi reddedildi" iletisini döndürür. Erişiminiz olduğundan emin olmak için Analiz görüntüleme izninizin sorguladığınız tüm projeler için İzin Ver olarak ayarlandığından emin olun. Daha fazla bilgi edinmek için bkz . Analytics'e erişmek için gereken izinler.

Bir projeye erişiminiz yoksa aşağıdaki ileti görüntülenir:

Sorgu sonuçları, erişiminiz olmayan bir veya daha fazla projedeki verileri içerir. 'WorkItems' varlığında erişiminiz olan projeleri belirtmek için bir veya daha fazla proje filtresi ekleyin. $expand veya gezinti özelliklerini kullanıyorsanız, bu varlıklar için proje filtresi gerekir.

Bu sorunu geçici olarak çözmek için, açıkça bir proje filtresi ekleyebilir veya bu makalenin devamında açıklandığı gibi proje kapsamlı uç noktayı kullanabilirsiniz.

Örneğin, aşağıdaki sorgu ve {projectSK2}adlı {projectSK1} projelere ait iş öğelerini getirir.

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

✔️ Genişletmeniz diğer, erişilemez olabilecek projelerde veri içerebiliyorsa yan tümcesinin içinde $expand proje filtresi belirtin

Gezinti özelliklerini genişlettiğinizde, diğer erişilemez projelerdeki verilere başvurma olasılığınız vardır. Erişilemeyen verilere başvurursanız, daha önce listelenen "Sorgu sonuçları bir veya daha fazla projedeki verileri içerir..." hata iletisini alırsınız. Benzer şekilde, genişletilmiş verileri denetlemek için açık proje filtreleri ekleyerek bu sorunu çözebilirsiniz.

Basit gezinti özellikleri için normal $filter yan tümcesinde bunu yapabilirsiniz. Örneğin, aşağıdaki sorgu hem bağlantının hem de hedefin aynı projede nerede olduğunu açıkça sorar WorkItemLinks .

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)

Bunun yerine, filtreyi yan tümcesindeki genişletme seçeneğine $filter$expand taşıyabilirsiniz. Ancak, sorgunun semantiğini değiştirir. Örneğin, aşağıdaki sorgu belirli bir projedeki tüm bağlantıları alır ve yalnızca aynı projede varsa hedefi koşullu olarak genişletir. Geçerli olsa da, bir özelliğin genişletilip genişletilmediğini saptamak zor olabileceği için null veya filtrelendiği için bu yaklaşım karışıklığa neden olabilir. Bu çözümü yalnızca bu özel davranışa gerçekten ihtiyacınız varsa kullanın.

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)

$filter Genişletme seçeneği, varlık kümesindeki gibi ChildrenWorkItems genişletme koleksiyonu özelliğini kullandığınızda kullanışlıdır. Örneğin, aşağıdaki sorgu belirli bir projedeki tüm iş öğelerini aynı projeye ait olan tüm alt öğeleriyle birlikte döndürür.

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)

Aşağıdaki özelliklerden birini genişletirseniz filtreyi belirtin:

  • WorkItems varlık kümesi: Parent, Children
  • WorkItemLinks varlık kümesi: TargetWorkItem.

✔️ Proje kapsamlı uç noktayı kullanarak sorgulamayı GÖZ ÖNÜNDE BULUNDURUN

Tek bir projedeki verilerle ilgileniyorsanız proje kapsamlı OData uç noktasını (/{ProjectName}/_odata/v1.0 ) kullanmanızı öneririz. Önceki iki bölümde açıklanan sorunları önler ve verileri örtük olarak bir projeye, başvurulan varlık kümesine ve tüm genişletilmiş gezinti özelliklerine filtreler.

Bu basitleştirmeyle, önceki bölümdeki sorgular aşağıdaki forma yeniden yazılabilir. Yalnızca expand yan tümcesindeki filtre kaybolmadı, aynı zamanda ana varlık kümesindeki filtreye de gerek kalmadı.

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

İş öğesi alt öğelerine yönelik sorgu da çok daha kısa ve basittir.

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

Bu çözümü yalnızca odağınız tek bir projeden alınan veriler olduğunda uygulayabilirsiniz. Çapraz proje raporlaması için önceki bölümlerde açıklanan filtreleme stratejilerini kullanmanız gerekir.

✔️ Sorgunuz kullanım sınırlarını aşarsa işlemi bekleme veya durdurma

Çok sayıda sorgu yürütürseniz veya sorguların çalıştırılması için çok fazla kaynak gerekiyorsa, hizmet sınırlarını aşabilir ve geçici olarak engellenebilirsiniz. Hizmet sınırlarını aşarsanız, gönderdiğiniz bir sonraki sorgunun aynı hata iletisiyle başarısız olması olasılığı nedeniyle işleminizi durdurun.

'{namespace}' ad alanında '{resource}' kaynağının kullanımı aşıldığından istek engellendi.

Hız sınırlama hakkında daha fazla bilgi için bkz . Hız sınırları. Verimli OData sorguları tasarlamayı öğrenmek için bu makalenin devamında yer alan Performans Yönergeleri'ne bakın.

✔️ Sorgunuz zaman aşımıyla başarısız olursa IŞLEMI BEKLEME VEYA DURDURMA

Kullanım sınırlarını aşmaya benzer şekilde, sorgunuz bir zaman aşımıyla karşılaşırsa işlemi beklemeniz veya durdurmanız gerekir. Geçici bir soruna işaret edebilir, bu nedenle sorunun çözülip çözülmediğini görmek için bir kez yeniden deneyebilirsiniz. Ancak, kalıcı zaman aşımları sorgunun çalıştırmak için büyük olasılıkla çok pahalı olduğunu gösterir. Daha fazla yeniden deneme yalnızca kullanım sınırlarının aşılmasıyla sonuçlanır ve engellenirsiniz.

TF400733: İstek iptal edildi: İstek istek zaman aşımını aştı, lütfen yeniden deneyin.

Zaman aşımları, sorgunun iyileştirme gerektirdiğini gösterir. Verimli OData sorguları tasarlamayı öğrenmek için bu makalenin devamında yer alan Performans yönergeleri bölümüne bakın.

❌ [ENGELLİ] Toplamalar dışında herhangi bir şey için anlık görüntü varlıklarını kullanma

Sonekli Snapshot anlık görüntü varlık kümeleri, günlük anlık görüntüler olarak modellendikleri için özeldir. Geçmişteki her günün sonunda olduğu gibi varlıkların durumunu almak için bunları kullanabilirsiniz. Örneğin, tek WorkItemIdbir sorgulayıp WorkItemSnapshot filtrelediyseniz, iş öğesi oluşturulduktan sonra her gün için bir kayıt alırsınız. Bu verilerin doğrudan yüklenmesi pahalı olabilir ve büyük olasılıkla kullanım sınırlarını aşar ve engellenir. Ancak, bu varlıklardaki toplamalara hem izin verilir hem de önerilir. Aslında, anlık görüntü varlık kümeleri toplama senaryoları göz önünde bulundurularak tasarlanmıştır.

Örneğin, aşağıdaki sorgu, Ocak 2020'de nasıl büyüdüğünü gözlemlemek için tarihe göre iş öğelerinin sayısını alır.

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

Toplamalar hakkında daha fazla bilgi edinmek için bkz . Verileri toplama.

✔️ Anlık görüntü tabloları üzerinde toplama yaparken YAN tümcesinde groupby DO ekleme DateSK veya DateValue sütun ekleme

Tüm anlık görüntü varlıkları günlük anlık görüntü tabloları olarak modellendiği için, gruplandırma yan tümcesine her zaman günün özelliklerinden birini (DateSK veya DateValue) eklemeniz gerekir. Aksi takdirde, sonuç yanlış şişirilmiş görünebilir.

Örneğin, yalnızca özelliğe göre AssignedTo gruplandırır WorkItemSnapshot ve sayı ile toplarsanız, kişilere atanan tüm iş öğesi sayısı, her atamanın etkin olduğu gün sayısıyla çarpılır. İstediğiniz sonucun bu olduğu bir durumla karşılaşabilirsiniz ancak bu tür durumlar nadirdir.

❌ [ENGELLİ] Varlık adresleme için kaynak yollarında varlık anahtarlarını kullanma

OData söz dizimi, anahtarlarını doğrudan URL segmentlerine ekleyerek belirli bir varlığa erişmenin bir yolunu sağlar. Daha fazla bilgi için bkz . OData Sürüm 4.0. Bölüm 2: URL Kuralları - 4.3 Varlıkları Ele Alma. OData bu tür adreslemelere izin veriyor olsa da Analytics bunu engeller. Sorguya ekleme aşağıdaki hatayla sonuçlanır.

URI'de belirtilen sorgu geçerli değil. Analiz, WorkItems(Id) veya WorkItem(Id)/AssignedTo gibi anahtar veya özellik gezintisini desteklemez. Bu hatayı PowerBI'da alıyorsanız, N+1 sorununa neden olan hatalı katlamalardan kaçınmak için sorgunuzu yeniden yazın.

Hata iletileri ipucu olarak, bazı istemci araçları doğrudan varlık adreslemini kötüye kullanabilir. Bu tür istemciler tüm verileri tek bir istekte yüklemek yerine her varlığı bağımsız olarak sorgulamayı seçebilir. Bu uygulama, çok sayıda isteğe neden olabileceğinden önerilmez. Bunun yerine, aşağıdaki bölümde açıklandığı gibi açık varlık adresleme kullanmanızı öneririz.

✔️ DO, filtre yan tümceleriyle varlıkları açıkça adreslemektedir

Tek bir varlık için veri getirmek istiyorsanız, varlık koleksiyonuyla aynı yaklaşımı kullanmanız ve yan tümcesinde $filter filtreleri açıkça tanımlamanız gerekir.

Örneğin, aşağıdaki sorgu tanımlayıcısı tarafından tek bir iş öğesi alır.

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

Böyle bir filtreye hangi özellikleri eklemeniz gerektiğini bilmiyorsanız, meta verilerde arayabilirsiniz. Bkz . Meta verileri sorgulamak için Analiz, URL bileşenleri için OData sorguları oluşturma. Özellikler öğesinin Key öğesindedir EntityType. Örneğin ve WorkItemIdRevision varlığın WorkItemRevision anahtar sütunlarıdır.

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

❌[ENGELLİ] Varlığı genişletme RevisionsWorkItem

Analytics veri modeli belirli türlerdeki genişletmelere izin vermemektedir. Bazıları için şaşırtıcı olabilecek bunlardan biri, varlık üzerindeki RevisionsWorkItem koleksiyon özelliğidir. Bu özelliği genişletmeye çalışırsanız aşağıdaki hata iletisini alırsınız.

URI'de belirtilen sorgu geçerli değil. 'Revisions' özelliği $expand sorgu seçeneğinde kullanılamaz.

Bu kısıtlama, aşağıdaki bölümde açıklandığı gibi düzeltmeleri WorkItemRevisions getiren önerilen çözümü kullanmaya herkesi teşvik etmek için uygulamaya konuldu.

✔️ DO, belirli bir iş öğesinin tüm düzeltmelerini yüklemek için varlık kümesini kullanma WorkItemRevisions

Bir iş öğesi veya iş öğeleri koleksiyonu için tam geçmişi getirmek istediğiniz her zaman kullanın WorkItemRevisions .

Örneğin, aşağıdaki sorgu tanımlayıcı ile {id} bir iş öğesinin tüm düzeltmelerini döndürür.

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

Belirli ölçütlerle eşleşen tüm iş öğelerinin tam geçmişine önem veriyorsanız, gezinti özelliğinde WorkItem bir filtre kullanarak ifade edin. Örneğin, aşağıdaki sorgu şu anda etkin olan tüm iş öğelerinin tüm düzeltmelerini alır.

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

❌ [ENGELLİ] Ayrı sütunlarda gruplandırma

Kayıt sayısını azaltmak için gruplandırma işlemi kullanırsınız. Yan tümcesinde groupby ayrı sütunlar kullanılması bir sorunu gösterir ve sorgu hemen başarısız olur. Bu durumla yanlışlıkla karşılaşırsanız aşağıdaki hata iletisini alırsınız.

Bu sorgunun groupby yan tümcesinde belirtilen sütunlardan biri veya daha fazlası önerilmez.

Bu sorunu çözmek için yan tümcesinden groupby ayrı sütunu kaldırın.

❌[ENGELLİ] Toplama kullanma countdistinct

Analiz, OData'nın desteklemesine countdistinct rağmen işlevi desteklemez. Gelecekte destek eklemeyi planlıyoruz ancak şu anda kullanılamıyor. Bu işlevi içeren bir sorgu aşağıdaki hata iletisini döndürür.

Toplama ile ayrı bir sayı uygulayan sorgular desteklenmez.

❌ Aritmetik taşmayla sonuçlanabilir AVOID toplamaları

Nadir durumlarda toplama sorgusu aritmetik taşma ile ilgili sorunlarla karşılaşabilir. Örneğin, iş öğesi varlıkları gibi StackRank , toplama için tasarlanmamış bazı sayısal özellikleri topladığınızda bu durum oluşabilir. Veri Toplama için OData Uzantısı standardı bir özelliği farklı bir türe dönüştürmenin bir yolunu sağlamadığından, bu sorunu çözmenin tek yolu toplamadan sorunlu özelliği kaldırmaktır.

✔️ Uzun sorgular için toplu iş uç noktasını kullanma

Uzun sorgularla ilgili sorunlarla karşılaşabilirsiniz. Özellikle, sorunlar şu durumlarda oluşabilir:

  • Birçok özel alanı olan bir projeyi sorgularsınız.
  • Sorgunuz program aracılığıyla oluşturulur.

ile HTTP GET gönderilen OData sorgularının geçerli sınırı 3.000 karakterdir. Bu değeri aşarsanız bir "404 Bulunamadı" yanıtı alırsınız.

HTTP/1.1 404 Not Found
Content-Length: 0

Bu sorunu çözmek için OData Sürüm 4.0 belirtiminde açıklandığı gibi OData toplu iş uç noktasını kullanın. Bölüm 1: Protokol - 11.7 Toplu İstekler. Batch özelliği öncelikli olarak birden çok işlemi tek HTTP bir istek yükünde gruplandıracak şekilde tasarlanmıştır, ancak sorgu uzunluğu sınırlaması için geçici bir çözüm olarak da kullanabilirsiniz. İstek göndererek HTTP POST , rastgele uzunlukta bir sorgu geçirebilirsiniz ve hizmet bunu doğru şekilde yorumlar.

❌ [ENGELLİ] Birden çok sorgu göndermek için toplu iş uç noktasını kullanma

Toplu iş uç noktasının kullanımını birden çok istekten oluşan bir toplu işlemi işlemesini kısıtlarız. Tek bir isteğin yine de tek bir sorgusu olabilir. Birkaç sorgudan oluşan bir toplu iş göndermeye çalışırsanız, işlem aşağıdaki hata iletisiyle başarısız olur. Tek çözüm sorguları birden çok isteğe bölmektir.

Analiz, geçerli toplu iş iletisinin içerdiği birden çok işlemin işlenmesini desteklemez. Analytics, POST isteklerini desteklemek için OData toplu işlemini kullanır, ancak işlemi tek bir istekle sınırlamanızı gerektirir.

❌ [ENGELLİ] 800'den fazla sütuna neden olan sorguları kullanma

800'den fazla sütuna neden olan sorguları kısıtlıyoruz. Sorgunuzun döndürdüğü sütunlarda yeterince seçmeli değilseniz aşağıdaki hata iletisini alabilirsiniz.

VS403670: Belirtilen sorgu izin verilen 800 sütun sınırından daha yüksek olan 'N' sütunlarını döndürür. Sütun sayısını sınırlamak için lütfen açık $select ($expand içinde dahil) seçeneklerini kullanın.

Bu sınırı aşmamak için sorgunuza ve $expand işlemlerine bir $select yan tümcesi ekleyin.

❌ Uzun sorgular oluşturmaktan KAÇıNıN

Uzun bir sorgu oluşturduğunuzda yaklaşımınızı değerlendirmenizi öneririz. Uzun sorgu gerektiren birçok senaryo (örneğin, karmaşık filtreler veya uzun bir özellik listesi) olsa da, genellikle en iyi olmayan tasarımın erken göstergesini sağlarlar.

Sorgunuz sorguda çok sayıda varlık anahtarı içerdiğinde (örneğin, WorkItemId eq {id 1} or WorkItemId eq {id 2} or ...) büyük olasılıkla yeniden yazabilirsiniz. Tanımlayıcıları geçirmek yerine, aynı varlık kümesini seçen başka ölçütler tanımlamayı deneyin. Bazen işleminizi değiştirmeniz gerekebilir (örneğin, yeni bir alan veya etiket ekleyin), ancak genellikle buna değer. Daha fazla soyut filtre kullanan sorguların bakımı daha kolaydır ve daha iyi çalışma potansiyeli daha yüksektir.

Uzun sorgular oluşturma eğiliminde olan başka bir senaryo, tek tek birçok tarih eklediğinizde gerçekleşir (örneğin, DateSK eq {dateSK 1} or DateSK eq {dateSK 2} or ...). Daha soyut bir filtre oluşturmak için kullanabileceğiniz başka bir desen arayın. Örneğin, aşağıdaki sorgu Pazartesi günü oluşturulan tüm iş öğelerini döndürür.

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

✔️ DO, tarih sütunlarını filtrelerken saat dilimini belirtme

Saat dilimi (Edm.DateTimeOffset), kuruluşun saat dilimi ayarlarıyla eşleşen bir uzaklık ile tüm tarih ve saat bilgilerini kullanıma sunar. Bu veriler aynı anda hassas ve basit bir şekilde yorumlanır. Başka bir kötü sonuç, tüm filtrelerin saat dilimi bilgilerini de geçirmesi gerekir. Atlarsanız aşağıdaki hata iletisini alırsınız.

URI'de belirtilen sorgu geçerli değil. Tarih saat uzaklığı belirtilmedi. Uzaklığı belirtmek için lütfen YYYY-AA-ggZ biçimlerinden birini kullanarak gece yarısından itibaren her şeyi belirtin veya yyyy-AA-ggThh:mm-hh:mm (TARIH ve saatlerin ISO 8601 standart gösterimi).

Bu sorunu çözmek için saat dilimi bilgilerini ekleyin. Örneğin, kuruluşun "(UTC-08:00) Pasifik Saati (ABD ve Kanada)" saat diliminde verileri görüntüleyecek şekilde yapılandırıldığını varsayarsak, aşağıdaki sorgu 2020'nin başından bu yana oluşturulan tüm iş öğelerini alır.

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

Aynı çözüm, pozitif uzaklıkları olan saat dilimleri için de çalışır, ancak artı karakterinin (+) URI'de özel bir anlamı vardır ve doğru şekilde işlemeniz gerekir. Başlangıç noktanız olarak (karakterle+) belirtirseniz 2020-01-01T00:00:00+08:00 aşağıdaki hatayı alırsınız.

URI'de belirtilen sorgu geçerli değil. 'CreatedDate ge 2020-01-01T0000 08:00' içinde 31 konumunda sözdizimi hatası.

Bunu çözmek için karakterini kodlanmış sürümüyle %2Bdeğiştirin+. Örneğin, kuruluşun "(UTC+08:00) Pekin, Chongqing, Hong Kong, Urumqi" saat diliminde verileri görüntüleyecek şekilde yapılandırıldığını varsayarsak, aşağıdaki sorgu 2020'nin başından bu yana oluşturulan tüm iş öğelerini döndürür.

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

Alternatif bir yaklaşım, saat dilimi bilgilerini tutmadıkları için tarih vekil anahtar özelliklerini kullanmaktır. Örneğin, aşağıdaki sorgu kuruluşun ayarlarından bağımsız olarak 2020'nin başından bu yana oluşturulan tüm iş öğelerini döndürür.

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

Performans yönergeleri

Do's

Hayır,

Dikkat edilmesi gerekenler

Önleme

✔️ DO, performans yönergesi uygulama etkisini ölçme

Tüm performans önerilerinde olduğu gibi bunları da körü körüne uygulamamalısınız. Bunun yerine, her zaman temeli yakalayın ve yaptığınız değişikliklerin etkisini ölçün . Tüm yönergeler, belirli gereksinimleri ve zorlukları olan Analytics müşterileri ile etkileşimleri temel alınarak oluşturulmuştur. Bu öneriler, benzer sorgular tasarlayan herkes için genel ve potansiyel olarak yararlı olarak kabul edildi. Ancak, nadir durumlarda, yönergeleri izlemenin performans üzerinde hiçbir etkisi veya olumsuz bir etkisi olabilir. Fark etmek için farkı ölçmeniz gerekir. Bu durumda, Geliştirici Topluluğu portalında geri bildirim sağlayın.

Performansı ölçmek için birçok seçenek vardır. En basiti, aynı sorgunun iki sürümünü doğrudan tarayıcıda çalıştırmaktır. Geliştirici araçlarında geçen süreyi gözlemleyin. Örneğin, Microsoft Edge F12 Geliştirici Araçları'nda Ağ panelini kullanabilirsiniz). Bir diğer seçenek de Fiddler Web Hata Ayıklayıcısı Aracı'nı kullanarak bu bilgileri yakalamaktır.

Yaklaşımınız ne olursa olsun, her iki sorguyu birden çok kez çalıştırın. Örneğin, yeterince büyük bir örnek kümesine sahip olmak için sorguları her birinde 30 kez çalıştırın. Ardından performans özelliklerini öğrenin. Analiz, çok kiracılı mimariyi izler. Bu nedenle, aynı anda gerçekleşen diğer işlemler sorgularınızın süresini etkileyebilir.

✔️ DO toplama uzantılarını kullanma

Sorgularınızın performansını geliştirmek için yapabileceğiniz en iyi şey, veri toplama için odata uzantısı olan toplama uzantısını kullanmaktır. Toplama uzantısıyla, hizmetten veri sunucusu tarafında özetlemesi ve aynı işlev istemci tarafı uygulayarak getirebileceğinizden daha küçük bir yanıt döndürmesini isteyin. Son olarak, Analytics bu tür sorgular için iyileştirilmiştir, bu nedenle bunu kullanın.

Daha fazla bilgi edinmek için bkz . Verileri toplama.

✔️ DO yan tümcesinde $select sütunları belirtme

Yan tümcesinde $select ilgilendiğiniz sütunları belirtin. Analiz, Columnstore Index teknolojisinin üzerine kurulmuştur. Bu, verilerin hem depolama hem de sorgu işlemenin sütun tabanlı olduğu anlamına gelir. Özellik kümesini azaltarak in yan tümcesine $select başvurarak taranacak sütun sayısını azaltabilir ve sorgunun genel performansını geliştirebilirsiniz.

Örneğin, aşağıdaki sorgu iş öğelerinin sütunlarını belirtir.

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

Dekont

Azure DevOps, işlem özelleştirmeyi destekler. Bazı yöneticiler bu özelliği kullanır ve yüzlerce özel alan oluşturur. Yan tümcesini $select atlarsanız, sorgunuz özel alanlar da dahil olmak üzere tüm alanları döndürür.

✔️ DO yan tümcesinin $select içindeki genişletme seçeneğinde $expand sütunları belirtme

Yan tümce yönergelerine $select benzer şekilde, yan tümcesindeki $select genişletme seçeneğinde $expand özellikleri belirtin. Kolayca unutabilirsiniz, ancak bunu atlarsanız, yanıtınız genişletilmiş nesnenin tüm özelliklerini içerir.

Örneğin, aşağıdaki sorgu hem iş öğesinin hem de üst öğesinin sütunlarını belirtir.

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

✔️ GEÇMIŞ iş öğeleri verilerini (WorkItemRevisionsveya WorkItemSnapshot varlık kümelerini) sorgularken üzerinde RevisedDateSK bir filtre tanımlama

Geçmiş verileri sorguladığınızda, en son dönemle (örneğin, 30 gün, 90 gün) ilgilenme olasılığınız vardır. İş öğeleri varlıklarının nasıl uygulandığından, harika bir performans elde etmek için bu tür sorgular yazmanın kullanışlı bir yolu vardır. Bir iş öğesini her güncelleştirdiğinizde yeni bir düzeltme oluşturur ve bu eylemi System.RevisedDate alana kaydeder ve bu da geçmiş filtreleri için mükemmel olmasını sağlar.

Analytics'te, düzeltilen tarih (Edm.DateTimeOffset) ve RevisedDateSK (Edm.Int32) özelliklerinde RevisedDate gösterilir. En iyi performans için ikincisini kullanın. Bu tarih vekil anahtarıdır ve bir düzeltmenin oluşturulduğu tarihi veya etkin, tamamlanmamış düzeltmeler için sahip null olduğu tarihi temsil eder. Bu tarihten bu yana {startDate} tüm tarihleri istiyorsanız, sorgunuza aşağıdaki filtreyi ekleyin.

RevisedDateSK eq null or RevisedDateSK gt {startDateSK}

Örneğin, aşağıdaki sorgu 2020'nin başından bu yana her gün için iş öğelerinin sayısını döndürür. Sütundaki belirgin filtrenin dışında üzerinde DateSK ikinci bir filtre RevisedDateSKolduğuna dikkat edin. Yedekli görünse de, sorgu altyapısının kapsamda olmayan düzeltmeleri filtrelemesine yardımcı olur ve sorgu performansını önemli ölçüde geliştirir.

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)
    )

Dekont

Burndown pencere öğeleri üzerinde çalışırken bu öneriyi bulduk. Başlangıçta yalnızca için DateSK filtreler tanımladık, ancak bu sorguyu büyük veri kümelerine sahip kuruluşlar için iyi ölçeklendirilecek şekilde alamadık. Sorgu profili oluşturma sırasında düzeltmeleri iyi filtrelemediğini DateSK fark ettik. Ancak filtre RevisedDateSK ekledikten sonra uygun ölçekte harika bir performans elde edebildik.
~ Ürün Ekibi

✔️ DO, uzun bir zaman aralığına yayılan eğilim sorguları için haftalık veya aylık anlık görüntüler kullanır

Varsayılan olarak, tüm anlık görüntü tabloları günlük anlık görüntü olgu tabloları olarak modellenir. Bir zaman aralığı sorgularsanız, her gün için bir değer alır. Uzun zaman aralıkları çok sayıda kayıtla sonuçlanır. Bu kadar yüksek hassasiyete ihtiyacınız yoksa haftalık ve hatta aylık anlık görüntüleri kullanabilirsiniz.

Belirli bir hafta veya ayı bitirmeyen günleri kaldırmak için bunu diğer filtre ifadeleriyle yapabilirsiniz. IsLastDayOfPeriod Bu senaryo göz önünde bulundurularak Analytics'e eklenen özelliğini kullanın. Bu özellik türündedir Microsoft.VisualStudio.Services.Analytics.Model.Period ve bir günün farklı dönemlerde (örneğin, haftalar, aylar vb.) bitip bitmediğini belirleyebilir.

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

Microsoft.VisualStudio.Services.Analytics.Model.Period Bayraklı bir sabit listesi olarak tanımlandığından, OData has işlecini kullanın ve dönem değişmez değerleri için tam tür belirtin.

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

Örneğin, aşağıdaki sorgu her ayın son gününde tanımlanan iş öğelerinin sayısını döndürür.

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, etiketlere göre filtreleme yaparken iş öğelerinde koleksiyon özelliğini kullanma Tags

Bir çalışmanın belirli bir etiketle işaretlenip işaretlenmediğini belirlemek için özelliğini işleviyle contains birlikte kullanabilirsinizTagNames. Ancak bu yaklaşım, özellikle aynı anda birden çok etiket denetlenirken yavaş sorgulara neden olabilir. En iyi performans ve sonuçlar için bunun yerine gezinti özelliğini kullanın Tags .

Örneğin, aşağıdaki sorgu ile {tag}etiketlenmiş tüm iş öğelerini alır.

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

Bu yaklaşım, birden çok etikete filtre uygulamanız gerektiğinde de harika çalışır. Örneğin, aşağıdaki sorgu veya ile {tag1}etiketlenmiş tüm iş öğelerini döndürür{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

Bu filtreleri bir "ve" işleciyle de birleştirebilirsiniz. Örneğin, aşağıdaki sorgu hem hem de {tag1}ile etiketlenmiş tüm iş öğelerini alır{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

✔️ Bir iş öğesindeki tüm etiketleri metin olarak görüntülemek istiyorsanız DO use TagNames özelliği

Önceki bölümde açıklanan gezinti özelliği Tags, filtreleme için mükemmeldir. Bununla birlikte, sorgu iç içe yerleştirilmiş bir koleksiyonda etiketler döndürdüğünden, bunlarla çalışmak bazı zorluklara neden olur. Veri modeli ayrıca etiket tüketimi senaryolarını basitleştirmek için eklediğimiz bir TagNames ilkel özellik ()Edm.String içerir. Noktalı virgül "; " ayırıcısıyla birleştirilmiş tüm etiketlerin listesini içeren tek bir metin değeridir. Tek ilgilendiğiniz etiketleri birlikte görüntülemek olduğunda bu özelliği kullanın. Daha önce açıklanan etiket filtreleri ile birleştirebilirsiniz.

Örneğin, aşağıdaki sorgu ile {tag}etiketlenmiş tüm iş öğelerini alır. İş öğesi kimliğini, başlığını, durumunu ve birleştirilmiş etiketlerin metin gösterimini döndürür.

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

Önemli

Özelliğin TagNames uzunluk sınırı 1024 karakterdir. Bu sınıra uyan bir etiket kümesi içerir. Bir iş öğesinin çok sayıda etiketi varsa veya etiketler çok uzunsa TagNames , tam kümeyi içermez ve Tag bunun yerine gezinti özelliği kullanılmalıdır.

❌Büyük/küçük harfe duyarsız karşılaştırma yapmak için ve toupper işlevlerini KULLANMAYIN tolower

Diğer sistemlerle çalıştıysanız, büyük/küçük harfe duyarlı olmayan karşılaştırma için veya toupper işlevlerini kullanmayı tolower bekleyebilirsiniz. Analytics ile tüm dize karşılaştırmaları varsayılan olarak büyük/küçük harfe duyarlı değildir, bu nedenle açıkça işlemek için herhangi bir işlev uygulamanız gerekmez.

Örneğin, aşağıdaki sorgu tüm iş öğelerini "QUALITY", "quality" veya bu sözcüğün başka bir harf bileşimiyle etiketlenir.

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

❌ ile ilişkisiz genişletme kullanma $levels=max

OData, hiyerarşik yapının tüm düzeylerini genişletme özelliğine sahiptir. Örneğin, iş öğesi izleme, ilişkisiz genişletmenin uygulanabileceği bazı varlıklara sahiptir. Bu işlem yalnızca az miktarda veriye sahip kuruluşlarda çalışır. Daha büyük veri kümeleri için iyi ölçeklendirilmiyor. Şu durumlara karşı hiç kullanmayın:

  • Büyük veri kümeleriyle çalışıyorsunuz.
  • Bir pencere öğesi geliştiriyorsun ve pencere öğesinin nereye yükleneceği üzerinde hiçbir denetiminiz yok.

✔️ DO sunucu temelli disk belleği kullanma

Tek bir yanıtta gönderilemeyecek kadar büyük bir küme istiyorsanız Analytics sayfalama uygular. Yanıt, yalnızca kısmi bir küme ve sonraki kısmi öğe kümesinin alınmasına izin veren bir bağlantı içerir. Bu strateji, OData belirtimi - OData Sürüm 4.0'da açıklanmıştır. Bölüm 1: Protokol - Sunucu Temelli Sayfalama. Hizmetin disk belleğini denetlemesine izin vererek, her varlığın olabildiğince verimli olması için dikkatli bir şekilde tasarlanmasından dolayı en iyi performansı skiptoken elde edersiniz.

Sonraki sayfanın bağlantısı özelliğine @odata.nextLink eklenir.

{
  "@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"}

Dekont

Mevcut OData istemcilerinin çoğu sunucu tabanlı disk belleğini otomatik olarak işleyebilir. Örneğin, bu strateji şu araçlar tarafından zaten kullanılıyor: Power BI, SQL Server Integration Services ve Azure Data Factory.

❌İstemci temelli disk belleği uygulamak için ve sorgu seçeneklerini kullanma $top$skip

Diğer REST API'lerde ve $skip sorgu seçenekleriyle $top istemci temelli disk belleği uygulamış olabilirsiniz. Bunları Analytics ile kullanmayın. Bu yaklaşımla ilgili birkaç sorun vardır ve performans bunlardan biridir. Bunun yerine, önceki bölümde açıklanan sunucu temelli disk belleği stratejisini benimseyin.

✔️ Do use $top query option to limit the number of records

Sorgu seçeneği $top yalnızca ile $skipbirlikte kullanıldığında önerilmez. Raporlama senaryonuzda yalnızca bir kayıt alt kümesine (örneğin, örnek) ihtiyacınız varsa sorgu seçeneğini kullanabilirsiniz $top . Ayrıca, kayıtları bazı ölçütlere göre sıralamanız gerekiyorsa, en yüksek dereceli kayıtlarla kararlı bir sonuç elde etmek için her zaman ile $orderby birlikte kullanmanız $top gerekir.

✔️ Az sayıda kayıt döndürmek için sorgu yazmayı GÖZ ÖNÜNDE BULUNDURUN

Az sayıda kayıt döndürmek için sorgu yazmak en sezgisel kılavuzdur. Her zaman yalnızca gerçekten önemsediğiniz verileri getirmeyi hedefleyin. Güçlü filtreleme özelliklerinin çoğunu OData sorgu dilinde kullanılabilir hale getirerek bunu başarabilirsiniz.

✔️ Seçili özelliklerin sayısını en düşük değerle sınırlamayı GÖZ ÖNÜNDE BULUNDURUN

Bazı proje yöneticileri özel alanlar ekleyerek işlemlerini yoğun bir şekilde özelleştirir. Ağır özelleştirme, geniş varlıklardaki tüm kullanılabilir sütunları getirirken performans sorunlarına yol açabilir (örneğin, WorkItems). Analiz, Columnstore Index teknolojisinin üzerine kurulmuştur. Bu, verilerin hem depolama hem de sorgu işlemenin sütun tabanlı olduğu anlamına gelir. Bu nedenle, sorgu ne kadar çok özelliğe başvurursa, işlenmesi o kadar pahalı olur. Sorgularınızdaki özellik kümesini her zaman raporlama senaryonuzda gerçekten önemsediğiniz özelliklerle sınırlamayı hedefleyin.

✔️ Tarih vekil anahtar özelliklerine göre filtrelemeyi GÖZ ÖNÜNDE BULUNDURUN (DateSK sonek)

Tarih filtresi tanımlamanın birçok yolu vardır. Date özelliğine doğrudan (örneğin, CreatedDate), gezinti karşılık gelenine (örneğin, CreatedOnDate) veya vekil anahtar gösterimine (örneğin, CreatedDate) filtreleyebilirsiniz. Son seçenek en iyi performansı verir ve raporlama gereksinimleri buna izin verince tercih edilir.

Örneğin, aşağıdaki sorgu 2020'nin başından bu yana oluşturulan tüm iş öğelerini alır.

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

✔️ Vekil anahtar sütunlarında filtrelemeyi GÖZ ÖNÜNDE BULUNDURUN

İlgili bir nesnenin değerindeki verileri filtrelemek istiyorsanız (örneğin, proje adında bir iş öğesini filtrelemek), her zaman iki seçeneğiniz vardır. Gezinti özelliğini (örneğin, Project/ProjectName) kullanabilir veya vekil anahtarı önceden yakalayıp doğrudan sorguda kullanabilirsiniz (örneğin, ProjectSK).

Pencere öğesi oluşturuyorsanız ikinci seçeneği kullanmanızı öneririz. Anahtar sorgunun bir parçası olarak geçirildiğinde, dokunulması gereken varlık kümelerinin sayısı azalır ve performans artar.

Örneğin, aşağıdaki sorgu gezinti özelliği yerine Project/ProjectName özelliği kullanarak ProjectSK filtrelenirWorkItems.

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

❌veya $expand yan tümcelerinde $filter , Childrenveya Revisions özelliklerini kullanmaktan ParentKAÇıNıN

İş öğeleri, veri modelinin tamamında en pahalı varlıklardır. İlgili iş öğelerine erişmek için kullanabileceğiniz çeşitli gezinti özellikleri vardır: Parent, Children, Revisions. Ancak bunları bir sorgu içinde her kullandığınızda performansta düşüş olmasını beklersiniz. Bu özelliklerden birine gerçekten ihtiyacınız olup olmadığını ve tasarımınızı güncelleştirme olasılığınız olup olmadığını her zaman sorgularsınız.

Örneğin, genişletmek Parentyerine daha fazla iş öğesi getirebilir ve tam hiyerarşi istemci tarafını yeniden yapılandırmak için özelliğini kullanabilirsiniz ParentWorkItemId . Bu iyileştirmeyi büyük/küçük harf temelinde gerçekleştirin.

✔️ Üst bilgide tercih geçirmeyi VSTS.Analytics.MaxSize GÖZ ÖNÜNDE BULUNDURUN

Sorguyu yürütürken, sorgunun döndürdüğü kayıt sayısını bilmezsiniz. Toplamalarla başka bir sorgu gönderin veya sonraki tüm bağlantıları izleyin ve veri kümesinin tamamını getirin. Analiz tercihe VSTS.Analytics.MaxSize saygı gösterir ve bu sayede veri kümesinin istemcinizin kabul edebildiğinden daha büyük olduğu durumlarda hızlı bir şekilde başarısız olabilirsiniz.

Bu seçenek, veri dışarı aktarma senaryolarında yararlıdır. Bunu kullanmak için HTTP isteğinize üst bilgi eklemeniz Prefer ve negatif olmayan bir değere ayarlamanız gerekir VSTS.Analytics.MaxSize . değer, VSTS.Analytics.MaxSize kabul edebilirsiniz kayıt sayısı üst sınırını temsil eder. Sıfır olarak ayarlarsanız varsayılan 200 K değeri kullanılır.

Örneğin, veri kümesi daha küçükse veya 1000 kayda eşitse aşağıdaki sorgu iş öğelerini döndürür.

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}

Veri kümesi 1000 kayıt sınırını aşarsa sorgu hemen aşağıdaki hatayla başarısız olur.

Sorgu sonucu 1.296 satır içerir ve izin verilen en büyük boyut olan 1000'i aşıyor. Lütfen ek filtreler uygulayarak kayıt sayısını azaltın

En büyük sayfa boyutunu ayarlama hakkında bilgi için bkz . ODataPreferenceHeader.MaxPageSize özelliği.

Sorgu stili yönergeleri

✔️ TOPLAMA yöntemlerinde SANAL özellik kullanma $count

Bazı varlıklar özelliği kullanıma sunar Count . Veriler farklı bir depolama alanına aktarıldığında bazı raporlama senaryolarını kolaylaştırır. Ancak, OData sorgularındaki toplamalarda bu sütunları kullanmamalısınız. $count Bunun yerine sanal özelliğini kullanın.

Örneğin, aşağıdaki sorgu toplam iş öğesi sayısını döndürür.

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

❌ URL segmentinde sanal özelliği kullanmaktan $count KAÇıNıN

OData standardı, varlık kümeleri için sanal özelliği (örneğin, ) kullanmanıza $count izin verse de, _odata/v1.0/WorkItems/$counttüm istemciler yanıtı doğru yorumlayamayabilir. Bu nedenle, bunun yerine toplamaları kullanmanız önerilir.

Örneğin, aşağıdaki sorgu toplam iş öğesi sayısını döndürür.

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

✔️ Sorgunun geçici bölümlerini ayırmak için parametre diğer adlarını kullanmayı GÖZ ÖNÜNDE BULUNDURUN

Parametre diğer adları, ana sorgu metninden parametre değerleri gibi geçici parçaları ayıklamak için zarif bir çözüm sağlar. Bunları değerlendiren ifadelerde kullanabilirsiniz:

  • İlkel değer
  • Karmaşık bir değer
  • İlkel veya karmaşık değerler koleksiyonu.

Daha fazla bilgi için bkz . OData Sürüm 4.0. Bölüm 2: URL Kuralları - 5.1.1.13 Parametre Diğer Adları. Sorgu metni, kullanıcı tarafından sağlanan değerlerle örneklenebilir bir şablon olarak kullanıldığında parametreler kullanışlıdır.

Örneğin, aşağıdaki sorgu değeri filtre ifadesinden ayırmak için parametresini kullanır @createdDateSK .

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

❌ Tek bir sorguda karıştırmaktan $apply ve $filter yan tümcelerden KAÇıNıN

Sorgunuza eklemek filter istiyorsanız iki seçeneğiniz vardır. Bunu yan tümcesiyle $filter veya bileşimiyle $apply=filter() yapabilirsiniz. Bu seçeneklerin her biri tek başına harika çalışır, ancak bunları bir araya getirmek bazı beklenmeyen sonuçlara yol açabilir.

Beklentiye rağmen OData, değerlendirme sırasını açıkça tanımlar. Ayrıca, yan tümcesi $apply üzerinde $filterönceliğe sahiptir. Bu nedenle, birini veya başka birini seçmelisiniz, ancak tek bir sorguda bu iki filtre seçeneğini kullanmaktan kaçınmalısınız. Sorguların otomatik olarak oluşturulması önemlidir.

Örneğin, aşağıdaki sorgu önce iş öğelerini ölçütüne göre StoryPoint gt 5filtreler, sonuçları şunlara göre toplar ve son olarak sonucu ölçütüne StoryPoints gt 2göre filtreler. Bu değerlendirme sırası ile sorgu her zaman boş bir küme döndürür.

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)
    )

✔️ Sorgunuzu OData değerlendirme sırasına uyacak şekilde yapılandırmayı GÖZ ÖNÜNDE BULUNDURUN

Tek bir sorguda ve filter yan tümcelerinin karıştırılması $apply olası karışıklığa neden olabileceğinden, sorgu yan tümcelerinizi değerlendirme sırasına uyacak şekilde yapılandırmanızı öneririz.

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

✔️ Meta veri ek açıklamalarında açıklanan OData özelliklerini gözden geçirmeyi GÖZ ÖNÜNDE BULUNDURUN

Analytics'in hangi OData özelliklerini desteklediğinden emin değilseniz meta verilerde ek açıklamaları arayabilirsiniz. TC GitHub deposundaki OASIS Açık Veri Protokolü (OData) Teknik Komitesi, kullanılabilir ek açıklamaların listesini tutar.

Örneğin, desteklenen filtre işlevlerinin listesi varlık kapsayıcısında ek açıklama olarak Org.OData.Capabilities.V1.FilterFunctions kullanılabilir.

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

Yan tümcesinde hangi gezinti özelliklerini kullanamamanızı açıklayan bir diğer yararlı ek açıklamadırOrg.OData.Capabilities.V1.ExpandRestrictions$expand. Örneğin, aşağıdaki ek açıklama, varlık kümesinde WorkItems genişletilememe durumunu açıklarRevisions.

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