OData ile analiz için sorgu yönergeleri

  • Makale
  • Okumak için 26 dakika

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019

Uzantı geliştiricileri, Azure DevOps analizine karşı verimli OData sorguları tasarlamak için bu makalede belirtilen yönergeleri izleyerek faydalanabilir. Bu yönergelerin ardından, sorguların yürütme süresi ve kaynak tüketimi için iyi performansa sahip olduğundan emin olmanıza yardımcı olur. Bu yönergelere bağlı olmayan sorgular, uzun rapor bekleme süreleriyle, izin verilen kaynak tüketimini aşan sorgular veya hizmet engelleme gibi performans düşüklemine neden olabilir.

Not

Analiz hizmeti tüm Azure DevOps Services için otomatik olarak etkinleştirilir. Üretimde kullanım için desteklenir. Power BI tümleştirme ve analiz hizmetinin OData akışına erişimi önizleme aşamasındadır. Bunu kullanmanızı ve bize geri bildirim sağlamanızı öneririz. .

Not

Analytics hizmeti, Azure DevOps Server 2020 için tüm yeni proje koleksiyonlarına otomatik olarak yüklenir. Üretimde kullanım için desteklenir. Power BI tümleştirme ve analiz hizmetinin OData akışına erişimi önizleme aşamasındadır. Bunu kullanmanızı ve bize geri bildirim sağlamanızı öneririz. Azure DevOps Server 2019 ' den yükselttiyseniz, yükseltme sırasında analiz hizmetini yüklemeye yönelik seçenek sunulur.

Not

analiz hizmeti Azure DevOps Server 2019 için önizlemededir. Analiz, bir proje koleksiyonu için etkinleştirerek veya yükleyerek erişebilirsiniz. Power BI tümleştirme ve analiz hizmetinin OData akışına erişimi önizleme aşamasındadır. Bunu kullanmanızı ve bize geri bildirim sağlamanızı öneririz.

Yönergeler , koşulların önünealınması, göz önünde bulundurulması, kaçınmamak ve olmaması bakımından basit öneriler olarak düzenlenir. Analiz tarafından zorlanan kısıtlayıcı kurallar [engellenen] önekini içerir. Bu kılavuzlarla, farklı çözümler arasındaki ticaretleri anlamanız gerekir. Belirli koşullarda, bir veya daha fazla Kılavuzu ihlal etmeye zorlayan veri gereksinimlerinize sahip olabilirsiniz. Bu tür durumlar nadir olmalıdır. Bu tür kararlar için açık ve etkileyici bir nedeniniz olması önerilir.

Not

bu belgede gösterilen örneklerde Azure DevOps Services url 'si temel alınır ve Azure DevOps Server url 'nizin yerine getirmeniz gerekir.

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

Not

{version}Değer olarak biçimlendirilir v1.0 . Desteklenen en son sürüm v2.0 ve en son önizleme sürümü v4.0-preview . Daha fazla bilgi için bkz. OData API sürümü oluşturma.

Hata ve uyarı iletileri

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

Yürütüğiniz her sorgu, önceden tanımlanmış bir dizi kurala göre denetlenir. İhlaller, aşağıdaki OData yanıtında geri döndürülür @vsts.warnings . Sorgunuzu geliştirme hakkında geçerli ve içeriğe duyarlı bilgiler sağladıklarında 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."
  ],
  ...
}

✔️ OData hata iletilerini gözden geçirin

OData hata kuralını ihlal eden sorgular, 400 (Hatalı Istek) durum kodu ile başarısız bir yanıt oluşmasına neden olur. İletileri ilişkilendir özelliği içinde görünmüyor @vsts.warnings . Bunun yerine, JSON yanıtında özelliğinde bir hata mesajı oluşturur message .

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

Seçmeyi

Engellendi

Önleme

✔️, sorguyu erişiminizin olduğu proje (ler) e sınırla

sorgunuz, erişiminiz olmayan bir projeden verileri hedefliyorsa, sorgu bir "Project erişim reddedildi" iletisi döndürür. Erişiminizin olduğundan emin olmak için, Görünüm Analizi izninizin, Sorgulayabileceğiniz tüm projelere izin ver olarak ayarlandığından emin olun. Daha fazla bilgi edinmek için bkz. Analize erişim için gerekli izinler.

İşte bir projeye erişiminiz yoksa göreceğiniz ileti:

Sorgu sonuçları, erişiminiz olmayan bir veya daha fazla projedeki verileri içerir. ' WorkItems ' varlığında erişiminizin olduğu proje (ler) i belirtmek için bir veya daha fazla proje filtresi ekleyin. $Expand veya gezinti özellikleri 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 ilerleyen kısımlarında açıklandığı gibi Proje kapsamlı uç noktası kullanabilirsiniz.

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

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

$expandgenişletmeleriniz diğer, erişilemez olabilecek projelere veri içeriyorsa yan tümce içinde proje filtresi ✔️ belirtin

Gezinti özelliklerini genişlettiğinizde, diğer, erişilemeyen projelerden gelen verilere yönelik verileri sonlandırmanın bir olasılığı vardır. Erişilemeyen verilere başvurulmanız durumunda, daha önce listelenen aynı hata iletisini alırsınız, "" sorgu sonuçları bir veya daha fazla projede verileri içerir...". Benzer şekilde, genişletilmiş verileri denetlemek için açık proje filtreleri ekleyerek bu sorunu çözebilirsiniz.

Bunu $filter basit gezinti özellikleri için normal yan tümce içinde yapabilirsiniz. Örneğin, aşağıdaki sorgu, WorkItemLinks hem bağlantının hem de hedefinin aynı projede nerede mevcut olduğunu açıkça ister.

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, $filter yan tümcesindeki Genişlet seçeneğine filtresini taşıyabilirsiniz $expand . Ancak, sorgunun anlam boyutunu değiştirir. Örneğin, aşağıdaki sorgu belirli bir projeden tüm bağlantıları alır ve hedefi yalnızca aynı projede varsa koşullu olarak genişletir. Geçerli olsa da, bu yaklaşım bir özelliğin genişletilmediği veya filtrelenmediği için genişletilmediğini belirlemek zor olabileceğinden karışıklıklara neden olabilir null . Bu çözümü yalnızca gerçekten bu davranışa ihtiyaç duyuyorsanız 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)

Genişletme $filter seçeneğinin varlık kümesi gibi genişletme koleksiyonu özelliğini kullandığınızda yararlı olduğunu göreceksiniz ChildrenWorkItems . Örneğin, aşağıdaki sorgu, belirli bir projeden 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 belirtmeniz gerekir:

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

✔️ Proje kapsamındaki uç noktayı kullanarak sorgulamayı düşünün

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

Bu basitleştirme ile, önceki bölümdeki sorgular aşağıdaki biçime yeniden yazılabilir. Genişletme yan tümcesindeki filtrenin kaybolması, ancak aynı zamanda ana varlık kümesindeki filtreye gerek yoktur.

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

İş öğesi alt öğeleri sorgusu da çok daha kısa ve daha basittir.

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

Bu çözümü, yalnızca odaklanmanız tek bir projeden veri olduğunda uygulayabilirsiniz. Projeler arası raporlama için, önceki bölümlerde açıklanan filtreleme stratejilerini kullanmanız gerekir.

Sorgunuz kullanım sınırlarını aşarsa ✔️ bekleyin veya işlemi durdurun

Birçok sorgu çalıştırırsanız veya sorguların çalışması için çok fazla kaynak gerekiyorsa, hizmet sınırlarını aşabilirsiniz ve geçici olarak engellenmiş olursunuz. Hizmet sınırlarını aşarsanız, göndereceğiniz sonraki sorgunun aynı hata iletisiyle başarısız olacağı ihtimallerden dolayı işleminizi durdurun.

' {Namespace} ' ad alanındaki ' {Resource} ' kaynağının kullanımı aşılmasından dolayı istek engellendi.

Hız sınırlaması hakkında daha fazla bilgi için bkz. oran limitleri. Verimli OData sorguları tasarlama hakkında bilgi edinmek için bu makalenin ilerleyen bölümlerinde performans yönergelerine bakın.

Sorgunuz bir zaman aşımı ile başarısız olursa ✔️ bekleyin veya işlemi durdurun

Kullanım sınırlarını aşarak, sorgunuz bir zaman aşımı ile geliyorsa işlemi beklemeniz veya durdurmanız gerekir. Geçici bir sorunu işaret edebilir, bu nedenle sorunun çözümlendiğini görmek için bir kez daha yeniden deneyebilirsiniz. Ancak, kalıcı zaman aşımları sorgunun çalıştırmanın çok pahalı olduğunu gösterir. Daha fazla yeniden deneme yalnızca kullanım sınırlarını aşarak engellenecek.

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

Zaman aşımları bir sorgunun iyileştirme gerektirdiğini gösterir. Verimli OData sorguları tasarlama hakkında bilgi edinmek için bu makalenin ilerleyen bölümlerinde performans yönergeleri bölümüne bakın.

❌ [Engellendı] toplamaların dışında bir şey için anlık görüntü varlıkları kullanmayın

Son ek içeren anlık görüntü varlık kümeleri, SnapshotSnapshotolarak modellendiği için özeldir. Bunları, geçmişte her bir günün sonunda oldukları gibi varlıkların bir durumunu almak için kullanabilirsiniz. Örneğin, tek bir sorgulama yaptıysanız WorkItemSnapshot ve tek bir filtre oluşturduysanız WorkItemId , iş öğesi oluşturulduktan bu yana her gün için bir kayıt alırsınız. Bu verilerin tümünün doğrudan yüklenmesi pahalıdır ve büyük olasılıkla kullanım sınırları aşılacağından engellenmektedir. Ancak, bu varlıklara yönelik toplamaların her ikisi de izin verilir ve önerilir. Aslında, anlık görüntü varlık kümeleri, toplama senaryolarında göz önünde bulundurularak tasarlanmıştır.

Örneğin, aşağıdaki sorgu çalışma öğelerinin sayısını tarihe göre, Ocak 2017 ' de nasıl gret olduğunu gözlemleyecek şekilde alır.

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

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

DateSKDateValuegroupby anlık görüntü tablolarının üzerine topladığınızda ✔️ include veya Column yan tümcesi

Tüm anlık görüntü varlıkları günlük anlık görüntü tablolarıolarak modellendiği için, DateValue Gruplandırma yan tümcesindeki gün özelliklerinden birini (veya) her zaman dahil etmelisiniz. Aksi halde, sonuç yanlış biçimde görünmeyebilir.

Örneğin, WorkItemSnapshot yalnızca özelliğe göre gruplandırırsanız AssignedTo ve sayı ile ayırarak, kişilere atanan iş öğelerinin tüm sayısı, her atamanın etkin olduğu gün sayısıyla çarpılacaklardır. İstediğiniz sonuca ait bir durumunuz olsa da, bu tür durumlar nadir olabilir.

❌ [Engellendı] varlık adresleme için kaynak yollarında varlık anahtarları kullanmayın

OData sözdizimi, kendi anahtarlarını doğrudan URL kesimlerine ekleyerek belirli bir varlığa erişmek için bir yol sağlar. Daha fazla bilgi için bkz . OData sürüm 4,0. Bölüm 2: URL kuralları-4,3 varlıkları adresleme. OData böyle bir adresleme 'ye izin verse de, analiz bunu engeller. Bir sorgu içine dahil etme aşağıdaki hatayla sonuçlanır.

URI 'de belirtilen sorgu geçerli değil. Analytics, WorkItems (ID) veya WorkItem (ID)/AssignedTo. gibi anahtar veya özellik gezintisini desteklemez Bu hatayı PowerBI 'da alıyorsanız, N + 1 sorununa neden olan yanlış katlamayı önlemek için sorgunuzu yeniden yazın.

Hata iletileri ipuçları olarak, belirli istemci araçları kötüye kullanımı doğrudan varlık adreslemesini sağlayabilir. Tek bir istekteki tüm verileri yüklemek yerine, bu tür istemciler her bir varlık için bağımsız olarak sorgu seçebilir. Bu uygulama, yüksek sayıda istek oluşmasına neden olduğu için önerilmez. Bunun yerine, aşağıdaki bölümde açıklandığı gibi açık varlık adreslemesini kullanmanızı öneririz.

filtre yan tümceleri olan varlıkların açık olarak ele ✔️

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

Örneğin, aşağıdaki sorgu, tanımlayıcısına göre tek bir iş öğesini alır.

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

Bu tür bir filtreye hangi özelliklerden dahil ettiğinizden emin değilseniz, meta verilerde arama yapabilirsiniz. Bkz. Analytics OData meta verilerini araştırma. Özellikleri Key öğesinin öğesidir EntityType . Örneğin, WorkItemId ve Revision varlık için anahtar sütunlarıdır WorkItemRevision .

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

❌ [Engellendı] Revisions varlık üzerinde genişletme WorkItem

Analiz veri modeli belirli türde genişleenlere izin vermez. Bunlardan biri, varlığa göre ortaya çıkmış olabilecek, Revisions varlığındaki koleksiyon özelliğidir WorkItem . Bu özelliği genişletmeyi denerseniz, aşağıdaki hata iletisini alırsınız.

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

Bu kısıtlama, herkesin WorkItemRevisions aşağıdaki bölümde açıklanacak şekilde düzeltmeler getirilirken önerilen çözümü kullanmasını teşvik etmek için oluşturulmuştur.

WorkItemRevisionsbelirli bir iş öğesi için tüm düzeltmeleri yüklemek üzere varlık kümesini kullanın ✔️

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

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

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şiyle ilgileniyorsa, gezinti özelliğinde bir filtre kullanarak bunu yapın WorkItem . Ö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

❌ [Engellendı] DISTINCT sütunlarda gruplandırma

Kayıt sayısını azaltmak için bir gruplandırma işlemi kullanırsınız. Yan tümcesindeki ayrı sütunların kullanılması groupby bir sorunu gösterir ve sorgu hemen başarısız olur. Yanlışlıkla bu durumda çalıştırmanız gerekir, aşağıdaki hata iletisini alırsınız.

Bu sorgunun GroupBy yan tümcesinde belirtilen bir veya daha fazla sütun önerilmez.

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

❌ [Engellendı] toplama kullanma countdistinct

countdistinctOData, OData olmasına 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şma ile sonuçlanabileceğinden toplamalardan KAÇıNıN ❌

Nadir durumlarda, bir toplama sorgusu aritmetik taşma ile ilgili sorunlar yaşayabilirsiniz. Örneğin, StackRank iş öğesi varlıklarında olduğu gibi, toplamak için tasarlanmamış bazı sayısal özellikleri aldığınızda bu durum oluşabilir. Veri toplama standardı Için OData uzantısı bir özelliği farklı bir türe dönüştürmek için bir yol sağlamadığından, bu sorunu çözmenin tek yolu, sorunlu özelliği toplama işleminden kaldırmadır.

✔️ uzun sorgular için Batch uç noktası kullanma

Uzun sorgularla ilgili sorunlara neden olabilirsiniz. Özellikle, şu durumlarda sorunlar oluşabilir:

  • Birçok özel alan içeren bir projeyi sorgulayın.
  • Sorgunuz programlı olarak oluşturulur.

İle gönderilen OData sorgularının geçerli limiti HTTP GET 3.000 karakterdir. Bu dosyayı aşarsanız, bir "404 bulunamadı" yanıtını geri alacaksınız.

HTTP/1.1 404 Not Found
Content-Length: 0

Bu sorunu gidermek için, OData sürüm 4,0 belirtiminde açıklandığı şekilde OData Batch uç noktasını kullanın . 1. kısım: protokol-11,7 Batch Istekleri. Batch özelliği öncelikle birden çok işlemi tek bir istek yükünde gruplamak üzere tasarlanmıştır HTTP , ancak bunu sorgu uzunluğu sınırlaması için geçici bir çözüm olarak da kullanabilirsiniz. HTTP POSTİstek göndererek, rastgele uzunlukta bir sorgu geçirebilirsiniz ve hizmet tarafından doğru bir şekilde yorumlanır.

❌ [Engellendı] birden çok sorgu göndermek için Batch uç noktası kullanmayın

Birden çok isteğin toplu iş bitiş noktasının kullanımını kısıtlamamız. Tek bir isteğin yalnızca bir sorgusu olabilir. Birkaç sorgu toplu iş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ölmek olur.

Analytics, geçerli toplu iş iletisinin içerdiği birden çok işlemin işlenmesini desteklemez. Analytics, POST isteklerini desteklemek için OData Batch kullanır, ancak işlemi tek bir istekle sınırlandırmanıza gerek duyar.

❌ [Engellendı] 800 sütundan fazla sonuç veren sorgular kullanmayın

800 sütundan daha fazlasına neden olan sorguları kısıtlarız. Sorgunuzun döndürdüğü sütunlarda yeterince seçmeli değilseniz aşağıdaki hata iletisini alabilirsiniz.

VS403670: belirtilen 800 sütundan daha yüksek olan ' N ' sütunları, belirtilen sorgu retruns. Sütun sayısını sınırlandırmak için lütfen açık $select ($expand dahil) seçeneğini kullanın.

Sorgunuza $select bir yan tümce ekleyin ve bu sınırı aşmamak için Sorgunuzdaki işlemleri $expand.

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

Uzun bir sorgu oluşturduğunuzda yaklaşımınızı değerlendirmenizi öneririz. Uzun bir sorguya ihtiyacı olan çok sayıda senaryo (örneğin, karmaşık filtreler veya uzun bir özellikler listesi) olsa da, genellikle bir genel bakış tasarımının erken bir 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çerek diğer bazı kriterleri tanımlamaya çalışın. 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ını daha kolay hale getirir ve daha iyi çalışmak daha fazla olabilir.

Çok sayıda tek tarih (örneğin,) dahil ettiğinizde uzun sorgu oluşturma eğilimi gösteren başka bir senaryo da oluşur DateSK eq {dateSK 1} or DateSK eq {dateSK 2} or ... . Daha soyut bir filtre oluşturmak için kullanabileceğiniz başka bir model 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

✔️ Tarih sütunlarında filtrelerken saat dilimini belirtin

Saat dilimi ( Edm.DateTimeOffset ), Edm.DateTimeOffseteşleşen bir uzaklığa sahip tüm tarih ve saat bilgilerini gösterir. Bu veriler kesin ve aynı anda yorumlamak için basittir. Başka bir açık olmayan sonuç, tüm filtrelerin saat dilimi bilgilerini de iletmektir. Bunu atlarsanız, aşağıdaki hata iletisini alırsınız.

URI 'de belirtilen sorgu geçerli değil. DateTime boşluğu belirtilmedi. Bu iki biçimden birini kullanarak YYYY-AA-GGZ, gece yarısı veya yyyy-MM-ddThh: mm-hh: mm (ISO 8601 standart tarih ve saat gösterimi) değerini belirtin.

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

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

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

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

Bunu çözümlemek için, + karakteri kodlanmış sürümü ile değiştirin %2B . Örneğin, kuruluşun "(UTC + 08:00) Pekin, Chongqing, Hong Kong, Urumçi" saat dilimindeki verileri görüntülemesi için yapılandırıldığı kabul edildiğinde, aşağıdaki sorgu 2017 başlangıcı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 2017-01-01T00:00:00%2B08:00
  &$select=WorkItemId, Title, State

Alternatif bir yaklaşım, tarih yedeği anahtar özelliklerini, saat dilimi bilgilerini tutmayın olarak kullanmaktır. Örneğin, aşağıdaki sorgu, kuruluşun ayarlarından bağımsız olarak 2017 başlangıcı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 20170101
  &$select=WorkItemId, Title, State

Performans yönergeleri

Do

Donönce

Seçmeyi

Önleme

  • ChildrenRevisions$filter Veya $expand yan tümcelerinde,, veya özelliklerinden kaçının ❌

✔️ performans Kılavuzu Uygulama efektini ölçün

Her türlü performans önerilerinde olduğu gibi, bunları bir şekilde uygulamamalısınız. Bunun yerine, her zaman taban çizgisini yakalayın ve yaptığınız değişikliklerin etkisini ölçer . Tüm yönergeler, belirli gereksinimlere ve güçlüklere sahip olan analiz istemcileri ile etkileşimlere göre oluşturulmuştur. Bu öneriler genel olarak değerlendirilir ve benzer sorguları tasarlayan herkes için kullanışlı olabilir. Ancak, nadir durumlarda, yönergelerin takip olmasının hiçbir etkisi olmaz, hatta performans üzerinde olumsuz bir etkiye sahip olabilir. Bunu fark etmek için farkı ölçmenize gerek vardır. bu durum, geliştirici Community portalında geri bildirim sağlamanız gerekir.

Performansı ölçmeye yönelik birçok seçenek vardır. En basit bir sorgu, tarayıcıda doğrudan aynı sorgunun iki sürümünü çalıştırmak için kullanılır. Geliştirici araçlarında geçen süreyi gözlemleyin. örneğin, Microsoft Edge F12 Geliştirici Araçları) ' de ağ panelini kullanabilirsiniz. Diğer bir seçenek de bu bilgileri Fiddler Web hata ayıklayıcı aracınıkullanarak yakalamadı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 her biri 30 kez sorguyu çalıştırın. Daha sonra performans özelliklerini anlamak. Analytics, çok kiracılı mimariyi izler. Bu nedenle, sorgularınızın süresi aynı zamanda gerçekleşen diğer işlemlerden etkilenebilir.

✔️ toplama uzantılarını kullanma

Sorgularınızın performansını artırmak için yapabileceğiniz en iyi şey, veri toplama içintoplama uzantısı-OData uzantısı kullanmaktır. Toplama uzantısıyla, hizmetten veri sunucusu tarafını özetlemeyi isteyin ve aynı işlevi istemci tarafı uygulayarak, daha küçük bir yanıt döndürdiklerinize göre daha küçük bir yanıt döndürün. Son olarak, analiz bu tür bir sorgu için iyileştirilmiştir, bu nedenle onu kullanın.

Daha fazla bilgi için bkz. toplama verileri.

yan tümcedeki sütunları ✔️ belirtme $select

Yan tümce içinde ilgilendiğiniz sütunları belirtin $select . Analiz, bir columnstore dizin teknolojisinin üzerine kurulmuştur. Bu, verilerin depolama ve sorgu işlemenin sütun tabanlı olduğu anlamına gelir. Özellik kümesini azaltarak, yan tümcesine başvurduğunuzda, $select 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

Not

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

$selectyan tümce içindeki Expand seçeneğinde sütunları ✔️ belirtin $expand

$selectYan tümce yönergelerine benzer şekilde, $select yan tümce içindeki genişletme seçeneğinde özellikleri belirtin $expand . Unutmak kolaydır, ancak bunu atlarsanız, yanıtınız genişletilmiş nesnedeki tüm özellikleri içerir.

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

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

✔️ RevisedDateSK geçmiş iş öğesi verileri ( WorkItemRevisions veya WorkItemSnapshot varlık kümeleri) için sorgulama yaptığınızda bir filtre tanımlayın

Geçmiş verileri sorguladığınızda, en son noktayla ilgileniyorsunuz (örneğin, 30 gün, 90 gün). İş öğeleri varlıklarının uygulanma biçimi nedeniyle harika performans almak için bu tür sorgular yazmanız için kullanışlı bir yoldur. Bir iş öğesini her güncelleştirdiğinizde, yeni bir düzeltme oluşturur ve bu eylemi alana kaydeder ve bu işlem System.RevisedDate , geçmiş filtreleri için mükemmeldir.

Analiz ' de, düzeltilen Tarih RevisedDate ( Edm.DateTimeOffset ) ve RevisedDateSK ( Edm.Int32 ) özellikleri ile temsil edilir. En iyi performans için, ikincisini kullanın. Bu, Tarih yedek anahtarıdır ve bir düzeltmenin oluşturulduğu veya etkin, tamamlanmamış düzeltmeler için olan tarihi temsil eder. Dahil olmak üzere tüm tarihleri isterseniz {startDate} , sorgunuza aşağıdaki filtreyi ekleyin.

RevisedDateSK eq null or RevisedDateSK gt {startDateSK}

Örneğin, aşağıdaki sorgu, 2017 başlangıcından bu yana her gün için iş öğelerinin sayısını döndürür. Sütundaki açık filtrenin DateSK ikinci bir filtre olduğuna dikkat edin RevisedDateSK . Yedekli görünebilir ancak sorgu altyapısının kapsamda olmayan düzeltmeleri filtrelemesine ve sorgu performansını önemli ölçüde iyileştirmesine yardımcı olur.

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

Not

Burndown pencere öğeleri üzerinde çalışırken bu öneriyle karşılaştık. Başlangıçta yalnızca filtrelerini tanımlamış DateSK , ancak büyük veri kümelerine sahip kuruluşlar için bu sorguyu de ölçeklendirmek için alamadık. Sorgu profili oluşturma sırasında, DateSK düzeltmeleri iyi filtreleyemediğini fark ettik. Yalnızca üzerine bir filtre eklendikten sonra RevisedDateSK ölçekte harika performans sağlayabiliriz.
~ ~

✔️ uzun bir dönemi kapsayan 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ığı için sorgulama yaparsanız, her gün için bir değer alır. Uzun zaman aralıkları çok sayıda kayıt oluşmasına neden olacak. Bu tür yüksek duyarlığa ihtiyacınız yoksa, haftalık veya hatta aylık anlık görüntüler kullanabilirsiniz.

Bu işlemi, belirli bir haftayı veya ayı bitirememesi gereken günleri kaldırmak için diğer filtre ifadeleriyle yapabilirsiniz. IsLastDayOfPeriodBu senaryoya göre Analize 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, hafta, ay vb.) sonlanmadığını 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 Ve bayraklar ile enum olarak tanımlandığından, OData has işlecini kullanın ve nokta 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ımlanmış olan iş öğesi 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)
    )

Tagsetiketlere göre filtrelerken iş öğelerinde koleksiyon özelliğini kullanın ✔️

TagNamescontains Bir çalışmanın belirli bir etiketle işaretlenip işaretlenmediğini anlamak için özelliğini işleviyle birlikte kullanabilirsiniz. Ancak, bu yaklaşım, özellikle birden çok etiketi aynı anda denetlerken yavaş sorgulara neden olabilirler. En iyi performans ve sonuçlar için Tags bunun yerine gezinti özelliğini kullanın.

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

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

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

Ayrıca, bu filtreleri bir "and" işleci ile birleştirebilirsiniz. Örneğin, aşağıdaki sorgu, ve ile etiketlenmiş tüm iş öğelerini alır. {tag1}{tag1}{tag2}

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

TagNamesçalışma öğesinde metin olarak tüm etiketleri göstermek istiyorsanız özelliği kullanın ✔️

TagsÖnceki bölümde açıklanan gezinti özelliği filtreleme için harika. Bununla birlikte, sorgu iç içe geçmiş bir koleksiyonda Etiketler döndürdüğünden, bunlarla çalışma bazı güçlükler sunar. Veri modeli ayrıca TagNamesEdm.String , etiketlerin tüketim senaryolarını basitleştirecek şekilde eklediğimiz temel bir özelliği () içerir. Noktalı virgül ";" ayırıcısıyla birleştirilmiş tüm etiketlerin listesini içeren tek bir metin değeridir. Tüm ilgilendiğiniz Etiketler birlikte görüntülenirken bu özelliği kullanın. Daha önce açıklanan Etiketler filtreleriyle birleştirebilirsiniz.

Örneğin, aşağıdaki sorgu, ile etiketlenmiş tüm iş öğelerini alır {tag} . Çalışma öğesi KIMLIĞI, başlık, durum ve Birleşik 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

Özellikte TagNames 1024 karakterlik bir uzunluk sınırı vardır. Bu sınır içinde sığan bir etiket kümesi içerir. Bir iş öğesinin çok fazla etiketi varsa veya Etiketler çok uzunsa, TagNames bunun yerine tam set ve Tag Navigation özelliğinin kullanılması gerekir.

❌ tolower Ve işlevleri, toupper büyük/küçük harfe duyarsız karşılaştırma yapmak için kullanın

Diğer sistemlerle çalıştıysanız, tolowertoupper büyük/küçük harfe duyarsız karşılaştırma için veya işlevleri kullanmanız gerekebilir. Analiz ile tüm dize karşılaştırmaları, varsayılan olarak büyük/küçük harfe duyarlıdır; bu nedenle açıkça işlemek için herhangi bir işlev uygulamanız gerekmez.

Örneğin, aşağıdaki sorgu, "QUALITY", "Quality" veya bu sözcüğün herhangi bir başka bir durum birleşimiyle etiketlenmiş tüm iş öğelerini alır.

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

❌ İle sınırsız genişletme kullanmayın $levels=max

OData, hiyerarşik bir yapının tüm düzeylerini genişletme özelliğine sahiptir. Örneğin, iş öğesi izlemenin, sınırsız bir Genişlemeden uygulanabilen bazı varlıkları vardır. Bu işlem yalnızca az miktarda veri olan kuruluşlar için geçerlidir. Daha büyük veri kümelerinde iyi ölçeklenmez. Şu durumlarda kullanmayın:

  • Büyük veri kümeleriyle çalışıyorsunuz.
  • Pencere öğesi geliştirirsiniz ve pencere öğesinin yükleneceği yer üzerinde denetiminiz yoktur.

✔️ Sunucu odaklı sayfalama kullanma

Tek bir yanıtta gönderilmek üzere çok büyük bir küme için sorun yaparsanız, analiz disk belleği uygular. Yanıt yalnızca kısmi bir küme ve bir sonraki kısmi öğe kümesini almaya izin veren bir bağlantı içerir. Bu strateji OData belirtimi- OData sürüm 4,0 ' de açıklanmaktadır. 1. kısım: protokol-sayfalama Server-Driven. Hizmetin disk belleğine denetimine izin vererek, skiptoken her bir varlık için dikkatle tasarlanarak mümkün olduğunca verimli olması için en iyi performansı elde edersiniz.

Sonraki sayfaya bağlantı, özelliğine dahil edilir @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"}

Not

Mevcut OData istemcilerinin çoğu, sunucu odaklı sayfalama 'yi otomatik olarak işleyebilir. örneğin, bu strateji şu araçlar tarafından zaten kullanılıyor: Power BI, SQL Server tümleştirme hizmetleri ve Azure Data Factory.

❌ Kullanma $top ve $skip sorgu seçeneklerini istemci odaklı sayfalama uygulama

Diğer REST API 'Leri ile, $top ve sorgu seçenekleriyle istemci odaklı sayfalama uygulamış olabilirsiniz $skip . Bunları analiz ile kullanmayın. Bu yaklaşımda birçok sorun vardır ve performans bunlardan biridir. Bunun yerine, önceki bölümde açıklanan sunucu odaklı sayfalama stratejisini benimseyin.

$topkayıt sayısını sınırlandırmak için sorgu seçeneğini kullanın ✔️

Sorgu seçeneği $top yalnızca ile birlikte kullanıldığında önerilmez $skip . Raporlama senaryosundaki bir kayıt alt kümesine ihtiyacınız varsa (örneğin, örnek), sorgu seçeneğini kullanmak iyi bir $top seçenektir. Ayrıca, bazı ölçütlere göre kayıtları derecelendirmelisiniz, $top$orderby en üst dereceye sahip kayıtlarla kararlı bir sonuç almak için her zaman ile birlikte kullanmanız gerekir.

✔️ az sayıda kayıt döndürmek için bir sorgu yazmayı düşünün

Az sayıda kayıt döndürecek bir sorgu yazmak en sezgisel kılavuzlardır. Her zaman yalnızca gerçekten ilgilendiğiniz verileri getirmeye hedefleyin. OData sorgu dilinde birçok güçlü filtreleme özelliğini kullanılabilir hale getirerek bu özelliği elde edebilirsiniz.

✔️ Seçili özelliklerin sayısını minimum olarak sınırlamayı düşünün

Bazı proje yöneticileri, özel alanlar ekleyerek süreçlerini büyük ölçüde özelleştirir. Ağır özelleştirme, tüm kullanılabilir sütunları geniş varlıklarda (örneğin,) getirilirken performans sorunlarına yol açabilir WorkItems . Analiz, bir columnstore dizin teknolojisinin üzerine kurulmuştur. Bu, verilerin depolama ve sorgu işlemenin sütun tabanlı olduğu anlamına gelir. Bu nedenle, bir sorgunun başvurduğu daha fazla özellik, işlemek için daha pahalı bir işlemdir. Sorgularınızdaki özellik kümesini, raporlama senaryounuzda gerçekten ilgilendikleriniz ile sınırlamak için her zaman hedefleyin.

✔️ tarihi vekil anahtar özellikleri (sonek) üzerinde filtrelemeyi göz önünde bulundurun DateSK

Bir tarih filtresi tanımlayabileceğiniz birçok yol vardır. Tarih özelliği üzerinde doğrudan (örneğin, CreatedDate ), gezinti karşılığına (örneğin,) CreatedOnDate veya vekil anahtar gösterimine (örneğin,) filtre uygulayabilirsiniz CreatedDate . Son seçenek en iyi performansı verir ve raporlama gereksinimleri buna izin verdikleri zaman tercih edilir.

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

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

✔️ Vekil anahtar sütunlarında filtrelemeyi düşünün

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

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

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

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

ParentChildrenRevisions$filter Veya $expand yan tümcelerinde,, veya özelliklerinden kaçının ❌

Çalışma öğeleri, tüm veri modelindeki en pahalı varlıklardır. Bunlar, ilgili iş öğelerine erişmek için kullanabileceğiniz çeşitli gezinti özelliklerine sahiptir: Parent , Children , Revisions . Ancak, bunları bir sorgu içinde her kullandığınızda bir performans reddi beklenir. Gerçekten bu özelliklerden birine ihtiyacınız varsa ve tasarımınızı güncelleştirebilir, her zaman soru.

Örneğin, genişletmek yerine Parent daha fazla iş öğesi getirip, ParentWorkItemId tam hiyerarşi istemci tarafını yeniden yapılandırmak için özelliğini kullanabilirsiniz. Bu tür iyileştirmeyi bir servis talebi temelinde gerçekleştirin.

✔️ VSTS.Analytics.MaxSize başlıktaki tercihi GEÇIRMEYI düşünün

Bir sorgu yürüttüğünüzde, sorgunun dönecektir kayıt sayısını bilemezsiniz. Toplamalara sahip başka bir sorgu göndermeniz veya tüm sonraki bağlantıları izlemeniz ve tüm veri kümesini getirmesi gerekir. VSTS.Analytics.MaxSizeVeri kümesinin, istemcinizin kabul edebileceği miktardan daha büyük olduğu durumlarda bu örneklerde hızlı bir şekilde hata vermenizi sağlayan analiz koşulları tercihi.

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

Örneğin, veri kümesi 1000'e eşit veya daha küçükse 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: {OrganizationName}.analytics.visualstudio.com

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

Sorgu stili yönergeleri

✔️ toplama $count yöntemlerinde sanal özelliği kullan

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

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

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

❌ $count URL segmentinde sanal özelliği kullanarak AVOID

OData standardı varlık kümeleri için sanal özelliği (örneğin, ) kullanmana izin verir ancak tüm $count_odata/v1.0/WorkItems/$count istemciler yanıtı doğru yorumlayamaz. Bu nedenle bunun yerine toplamaların kullanılması önerilir.

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

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

✔️ geçici bölümlerini ayırmak için parametre diğer adlarını kullanmayı DÜŞÜNÜN

Parametre diğer adları, ana sorgu metninden parametre değerleri gibi geçici parçaları ayıklamak için şık 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ı. Parametreler, sorgu metni kullanıcı tarafından sağlanan değerlerle örneklenen bir şablon olarak kullanıldığında kullanışlıdır.

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

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

❌ bir sorguda $apply ve $filter yan tümcelerini karıştırmayı ÖNLEME

Sorgunuza eklemek filter istediğiniz iki seçenek vardır. Yan tümcesi veya $filter birleşimiyle bunu $apply=filter() yapabiliriz. Bu seçeneklerin her biri kendi kendine harika çalışır, ancak bunları birlikte birleştirme bazı beklenmeyen sonuçlara yol açabilirsiniz.

Beklentiye rağmen OData, değerlendirmenin bir sıralamayı net bir şekilde tanımlar. Ayrıca yan $apply tümcesi üzerinde önceliğe $filter sahiptir. Bu nedenle, birini veya başka birini seçmeniz gerekir, ancak bu iki filtre seçeneği tek bir sorguda önlenmiş olur. Sorgular otomatik olarak oluşturulursa önemlidir.

Örneğin, aşağıdaki sorgu ilk olarak iş öğelerini ile filtreler, sonuçları ile toplar yol olur StoryPoint gt 5 ve son olarak sonucu değerine göre StoryPoints gt 2 filtreler. Bu değerlendirme sırasıyla, sorgu her zaman boş bir küme geri döner.

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

✔️ OData değerlendirme sırasıyla eş olacak şekilde yapılandırmayı GÖZ ÖNÜNDE BULUNDURABILIRSINIZ

Tek bir sorguda ve yan tümcelerinin karışması olası kafa karışıklığına neden olduğundan, sorgu yan tümcelerinizi değerlendirme sırasına uygun $applyfilter şekilde oluşturmanızı öneririz.

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

✔️ açıklamalarında açıklanan OData özelliklerini gözden geçirmeyi DÜŞÜNÜN

Analytics'in hangi OData özelliklerini desteklediği konusunda emin değilseniz meta verilerde ek açıklamalara bakarak aramanız gerekir. TC Veri Protokolü (OData) Teknik Komitesi, GitHub ek açıklamaların listesini depolar.

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

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

Bir diğer yararlı ek Org.OData.Capabilities.V1.ExpandRestrictions açıklama da yan tümcesinde hangi gezinti özelliklerini kullanamayabilirsiniz? $expand açıklamasıdır. Örneğin, aşağıdaki ek açıklama varlık RevisionsWorkItems kümesinde genişletilene olmadığını açıklar.

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