OData Analytics kullanarak iş izleme verilerinizi sorgulama

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

Azure DevOps için analiz kullanarak, ilgilendiğiniz iş öğelerini döndürmek için temel ve filtrelenmiş sorgular oluşturabilirsiniz. Bu sorguları doğrudan tarayıcınızda çalıştırabilirsiniz.

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.

Bu makalede, temel kök URL, gösterildiği gibi bir projenin kapsamına alınır:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}
https://{ServerName}:{Port}/tfs/{CollectionName}/{ProjectName}/_odata/{version}

Not

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

Diğer tüm URL bölümleri sorgu dizesinin ek bir bölümü olarak belirtilir.

Önkoşullar

Temel sorgu oluşturma

OData URL 'sini desteklenen bir Web tarayıcısınagirerek temel bir sorgu oluşturursunuz. Belirtilen örneklerde, ve ' yi {OrganizationName} , {ProjectName} kuruluşunuzun adı ve sorgulamak istediğiniz projenin adı ile değiştirin.

OData URL 'sini desteklenen bir Web tarayıcısınagirerek temel bir sorgu oluşturursunuz. Belirtilen örneklerde aşağıdaki değişiklikleri yapın:

  • analytics.dev.azure.com kullanılarak {ServerName}:{Port}/tfs/
  • {OrganizationName} Proje koleksiyonu adınızla (varsayılan değer DefaultCollection)
  • {ProjectName} sorgulamak istediğiniz projenin adı ile.

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.

Tek bir varlık kümesini sorgulama

Iş öğeleri veya alan ya da projeler gibi tek bir varlık kümesini sorgulamak için, varlığın adını ekleyin: /Areas , /Projects veya /WorkItems . Varlık kümelerinin tam listesi için bkz. analiz Için veri modeli.

Örneğin, ekleyerek alanı sorgulayın /Areas . Tam URL:

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

Varlık kümesinde bir SELECT ifadesinin gerçekleştirilmesi ve her şeyi, tüm sütunları ve tüm satırları döndürmeyle eşdeğerdir. Çok sayıda iş öğesi varsa, bu işlem birkaç saniye sürebilir. 10000 ' den fazla iş öğesi varsa, sunucu tarafı Sayfalaması zorlanır.

Belirli sütunları veya alanları seçin

Bir yan tümce ekleyerek belirli alan verilerini döndürün $select .

Örneğin, yalnızca çalışma öğesi KIMLIĞI, çalışma öğesi türü, başlık ve iş öğelerinin durumunu döndürmek için, bu yan tümceyi sorgunuza ekleyin:

/WorkItems?$select=WorkItemId,WorkItemType,Title,State

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

Varlıktaki tüm satırları seçmeye eşdeğerdir, ancak yalnızca bu belirli alanları döndürüyor.

Not

Alan adlarında boşluk yok. Boşluk eklerseniz sorgunuz başarısız olur. OData sorguları ilgilenilmesi gereken her iki aralığa ve büyük küçük harflere de ödenir.

Verilerinizi filtreleme

Bir sorgu filtresi yan tümcesi sağlayarak verileri filtreleyebilirsiniz. Son sorgu üzerinde oluşturma, bu çalışma öğelerini yalnızca "sürüyor" durumuna döndürecek şekilde döndürmek için aşağıdaki filtre yan tümcesini eklersiniz.

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=State eq 'In Progress'

Tam OData sorgusuyla:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=State eq 'In Progress'

Bunun yerine, $select yan tümcesini tamamen hariç tutabilir ve sonuçları şöyle filtreleyebilirsiniz:

/WorkItems?$filter=State eq 'In Progress'

Tam OData sorgusuyla:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=State eq 'In Progress'

Ayrıca, iki veya daha fazla filtreyi birleştirerek birden çok filtre uygulayabilirsiniz. Burada, devam eden görevleri filtreliyoruz:

/WorkItems?$filter=WorkItemType eq 'Task' and State eq 'In Progress'

Tam OData sorgusuyla:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=WorkItemType eq 'Task' and State eq 'In Progress'

Ayrıca, ve gibi çeşitli işlevleri de uygulayabilirsiniz containsstartswithendswith . Desteklenen OData özelliklerine ve yan tümcelerlerine ve desteklenen işlevlerebakın.

Tarih aralığı sorguları

Aşağıdaki örnek, değişen tarihi 1 Ocak 2021 ' den büyük olan iş öğelerini döndürür.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-01-01Z

Aşağıdaki örnek, 30 Nisan 2021 ' ye kadar olan 26 Nisan ' nin haftası sırasında değişiklik tarihi oluşan iş öğelerini döndürür.

https://analytics.dev.azure.com{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-04-26Z&ChangedDate le 2021-04-30Z

İş öğelerinin sorgulanması yararlı olur, ancak sonunda yineleme yolu, alan yolu veya proje gibi diğer verilere göre filtre uygulamak isteyeceksiniz. Bunu yapmak için, varlık modelinin gezinti özelliklerini anlamanız gerekir. URL kullanarak meta verileri alabilirsiniz /$metadata . Ayrıntılar için bkz. Analytics OData meta verilerini araştırma

Iş öğeleri varlığı için meta verilerin kısmi bir görünümü aşağıda verilmiştir:

    <Property ...>
    <Property Name="RequirementType" Type="Edm.String"/>
    <Property Name="RequiresReview" Type="Edm.String"/>
    <Property Name="RequiresTest" Type="Edm.String"/>
    <Property Name="RootCause" Type="Edm.String"/>
    <Property Name="SubjectMatterExpert1" Type="Edm.String"/>
    <Property Name="SubjectMatterExpert2" Type="Edm.String"/>
    <Property Name="SubjectMatterExpert3" Type="Edm.String"/>
    <Property Name="TargetResolveDate" Type="Edm.DateTimeOffset"/>
    <Property Name="TaskType" Type="Edm.String"/>
    <Property Name="UserAcceptanceTest" Type="Edm.String"/>
    <Property Name="Count" Nullable="false" Type="Edm.Int32"/>
    <NavigationProperty Name="Revisions" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemRevision)"/>
    <NavigationProperty Name="BoardLocations" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.BoardLocation)"/>
    <NavigationProperty Name="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project"/>
    <NavigationProperty Name="Area" Type="Microsoft.VisualStudio.Services.Analytics.Model.Area"/>
    <NavigationProperty Name="Iteration" Type="Microsoft.VisualStudio.Services.Analytics.Model.Iteration"/>

Gezinti özellikleri, RevisionsBoardLocations (Kanban meta verileri),, ve içeren meta verilerin alt kısmına doğru görünür ProjectAreaIteration .

Gezinti özelliğine göre filtrele

Sonuçları filtrelemek için gezinti özelliklerini nasıl kullanacaksınız?

İş öğelerini belirli bir yinelemeye göre filtrelemek için aşağıdaki yan tümceyi kullanın, örneğin yineleme 1:

/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

Tam OData sorgusuyla:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

Bu örnekte, Iteration gezinti özelliği adıdır ve IterationPath yinelemenin tam yoluna karşılık gelir. Başka bir varlığı filtre olarak kullanmak için, gezinti özelliğini ve ardından bir eğik çizgi ve ardından süzülecek alanın adını yerleştirin.

İlgili alanları seçmek için gezinti özelliklerini nasıl kullanacaksınız?

Bir kimliğe dayalı özel alanlara yönelik Kullanıcı adı, bir ifade kullanılarak doğrudan erişilemez $select . Aşağıdaki sorgu, $expand Kullanıcı adını almak için bir ifade kullanır:

/WorkItems?$expand=MyIdentityField($select=UserName)

Not

Gezinti özelliğini doğrudan bir $select ifadede kullanamazsınız. Bunun yerine, kullanmanız gerekir $expand .

Yineleme yolu için önceki filtreleme örneği, ilgili bir varlıkta bulunduğundan, sonuçlarda yineleme yolunu döndürmez. İlgili varlıktaki verileri döndürmek için bir $expand ifade ekleyin:

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration

Aşağıdaki JSON 'ı döndürür:

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)",
  "value":[
    {
      "WorkItemId":10000,
      "WorkItemType":"Task",
      "Title":"Some title",
      "State":"Completed",
      "Iteration":{
        "IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46",
        "Name":"Sprint 55",
        "Number":13021,
        "IterationPath":"Fabrikam\\Sprints\\Sprint 55",
        "StartDate":"2013-09-23T00:00:00Z",
        "EndDate":"2013-10-11T00:00:00Z",
        "IterationLevel1":"Fabrikam",
        "IterationLevel2":"Sprints",
        "IterationLevel3":"Sprint 55",
        "Level":2,
        "IsDeleted":false
      }
    }
  ]
}

Gördüğünüz gibi, yineleme yolu JSON sonucuyla genişletilir ve tüm yineleme verileri döndürülür. Büyük olasılıkla istediğiniz kadar çok veri.

Daha az veri döndürmek için $select yinelemeye karşı bir ifade ekleyin:

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration($select=Name,IterationPath)

Aşağıdaki JSON 'ı döndürür:

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration,Iteration(Name,IterationPath))",
  "value":[
    {
      "WorkItemId":10000,
      "WorkItemType":"Task",
      "Title":"Some title",
      "State":"Completed",
      "Iteration":{
        "Name":"Sprint 55",
        "IterationPath":"Fabrikam\\Sprints\\Sprint 55"
      }
    }
  ]
}

OData içinde deyimleri iç içe geçirebilirsiniz $expand . Örneğin, yineleme öğesinin bir parçası olduğu projeyi göstermek için önceki sorgu ifadesini yazabilirsiniz:

/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($expand=Project)

Aşağıdaki JSON 'ı döndürür:

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
  "value":[
    {
      "WorkItemId":10000,
      "Revision":3,
      "Watermark":283397,
      "Title":"Production deployment and testing for Entitlement API v2 and Subscriber database",
      "WorkItemType":"Task",
      "ChangedDate":"2014-07-10T19:29:58.41Z",
      "CreatedDate":"2014-04-19T22:44:58.31Z",
      "State":"Completed",
      "Reason":"Completed",
      "Priority":2,
      "CompletedWork":10.0,
      "OriginalEstimate":20.0,
      "Count":1,
      "Iteration":{
        "IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46",
        "Name":"Sprint 55",
        "Number":13021,
        "IterationPath":"Fabrikam\\Sprints\\Sprint 55",
        "StartDate":"2013-09-23T00:00:00Z",
        "EndDate":"2013-10-11T00:00:00Z",
        "IterationLevel1":"Fabrikam",
        "IterationLevel2":" Sprints",
        "IterationLevel3":"Sprint 55",
        "Level":2,
        "IsDeleted":false,
        "Project":{
          "ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
          "ProjectName":"Fabrikam",
          "IsDeleted":false
        }
      }
    }
  ]
}

Ayrıca, $expand ve deyimlerini birleştirebilirsiniz $select . Örneğin, önceki sorguyu yalnızca yineleme adını ve yineleme yolunu döndürecek şekilde değiştirebilirsiniz:

/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($select=IterationId,IterationPath;$expand=Project)

Aşağıdaki JSON 'ı döndürür:

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(Iteration(IterationId,IterationPath,Project))",
  "value":[
    {
      "WorkItemId":10000,
      "Revision":3,
      "Watermark":283397,
      "Title":"Production deployment and testing for Entitlement API v2 and Subscriber database","WorkItemType":"Task",
      "ChangedDate":"2014-07-10T19:29:58.41Z",
      "CreatedDate":"2014-04-19T22:44:58.31Z",
      "State":"Completed",
      "Reason":"Completed",
      "Priority":2,
      "CompletedWork":10.0,
      "OriginalEstimate":20.0,
      "Count":1,
      "Iteration":{
        "IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46","IterationPath":"Fabrikam\\Sprints\\Sprint 55",
        "Project":{
          "ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
          "ProjectName":"Fabrikam",
          "IsDeleted":false
        }
      }
    }
  ]
}

sonuç olarak yalnızca iterationıd ve iterationpath gösterir ve Project JSON sonucu içinde iç içe geçmiş bir nesne olduğunu görürsünüz. Diğer bir anahtar öğe, URL 'nin kendisidir. Bir $select deyimi ve $expand yan tümcesini kullanırken, noktalı virgül kullanmanız gerekir (;) öğesinden önce $expand . Başka her şey bir hata oluşmasına neden olur.

Sonuçları sıralama

Yan tümcesini kullanarak OData sonuçlarını sıralayabilirsiniz $orderby . Bu yan tümceyi, gösterildiği gibi herhangi bir OData sorgusuna uygulayabilirsiniz:

/WorkItems?$orderby=WorkItemId

Anahtar sözcükleri asc veya karşılık gelenleri kullanarak artan veya azalan sırada sıralayabilirsiniz desc :

/WorkItems?&$orderby=WorkItemId desc

Ve birden çok öğeye göre sıralama yapabilirsiniz:

/WorkItems?$orderby=WorkItemType,State

Sunucu tarafı sayfalama 'yi zorlama

Analiz, sorgu sonuçları 10000 kaydı aştığında, sayfalama işlemini zorlar. Bu durumda, ilk veri sayfasını alacağınız ve sonraki sayfayı almak için takip edilecek bağlantıyı öğreneceksiniz. Link ( @odata.nextLink ) JSON çıkışının sonunda bulunabilir. Orijinal bir sorgu ve ardından veya tarafından izlenen bir şekilde görünür $skip$skiptoken . Ö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 çekme sırasında araçlar otomatik olarak sonraki bağlantıyı izleyip tüm gerekli kayıtları yükler.

Sonraki adımlar

kuruluş kapsamındaki sorguları Project