Dela via


Definiera grundläggande frågor med OData Analytics

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019

Med Hjälp av Analytics för Azure DevOps kan du skapa grundläggande och filtrerade frågor för att returnera data av intresse. Du kan köra dessa frågor direkt i webbläsaren eller i Power BI.

Den här artikeln bygger vidare på information som tillhandahålls i Skapa OData-frågor för analys - och metadatareferens för Azure Boards Analytics. Dessutom fokuserar frågorna i den här artikeln på att hämta entitetsuppsättningar för arbetsspårning, men principerna gäller för att fråga andra entitetsuppsättningar.

I den här artikeln får du lära dig hur du definierar frågor som returnerar följande data:

  • Antal objekt (inga andra data)
  • Antal objekt och data
  • Egenskaper som definierats för områden eller iterationssökvägar
  • Markerade kolumner eller fält
  • Filtrerade data
  • Returnera data för fälten Identitet, Områdessökväg och Iteration Path
  • Filtrera efter en navigeringsegenskap
  • Fråga efter ett datumintervall
  • Nest expand-uttryck
  • Sortera resultat, orderby-alternativ

Kommentar

Analytics-tjänsten aktiveras automatiskt och stöds i produktion för alla Azure DevOps Services. Power BI-integrering och åtkomst till OData-flödet i Analytics Service är allmänt tillgängliga. Vi rekommenderar att du använder den och ger oss feedback. Tillgängliga data är versionsberoende. Den senaste versionen som stöds är v2.0, och den senaste förhandsversionen är v4.0-preview. Mer information finns i OData API-versionshantering.

Kommentar

Analytics-tjänsten installeras automatiskt och stöds i produktion för alla nya projektsamlingar för Azure DevOps Server 2020 och senare versioner. Power BI-integrering och åtkomst till OData-flödet i Analytics Service är allmänt tillgängliga. Vi rekommenderar att du använder den och ger oss feedback. Om du har uppgraderat från Azure DevOps Server 2019 kan du installera Analytics-tjänsten under uppgraderingen.

Tillgängliga data är versionsberoende. Den senaste versionen som stöds är v2.0, och den senaste förhandsversionen är v4.0-preview. Mer information finns i OData API-versionshantering.

Kommentar

Analytics-tjänsten är en förhandsversion för Azure DevOps Server 2019. Du kan aktivera eller installera den för en projektsamling. Power BI-integrering och åtkomst till OData-flödet för Analystjänsten finns i förhandsversion. Vi rekommenderar att du använder den och ger oss feedback.

Tillgängliga data är versionsberoende. Den senaste versionen som stöds är v2.0, och den senaste förhandsversionen är v4.0-preview. Mer information finns i OData API-versionshantering.

Förutsättningar

  • Åtkomst: Vara medlem i ett projekt med minst grundläggande åtkomst.
  • Behörigheter: Som standard har projektmedlemmar behörighet att fråga Analytics och skapa vyer.
  • Mer information om andra förutsättningar för tjänst- och funktionsaktivering och allmänna dataspårningsaktiviteter finns i Behörigheter och krav för åtkomst till analys.

Kommentar

I den här artikeln definieras OData-fråge-URL:en för Azure DevOps Services. Information om hur du skapar en liknande fråga för en lokal server finns i vägledningen i Skapa OData-frågor för Analys. Vi rekommenderar att du justerar de frågor som tillhandahålls för din organisation och ditt projekt för att bekanta dig med att fråga OData med hjälp av webbläsaren.

Returnera ett antal objekt (inga andra data)

Om du vill veta mer om antalet objekt eller entiteter som definierats i en organisation eller ett projekt anger du $apply=aggregate($count as Count) frågealternativ. Följande frågor returnerar till exempel antalet projekt, arbetsobjekt, områdessökvägar och användare som definierats för en organisation.

https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Projects?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/WorkItems?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Areas?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Users?$apply=aggregate($count as Count)

Dricks

Frågor mellan projekt misslyckas när användaren som kör frågan inte har åtkomst till alla projekt. Läs mer om kraven i projekt- och organisationsomfattande frågor.

Antal projekt

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(Count)"
value	
   0	
     @odata.id	null
     Count	    28

Antal arbetsobjekt

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)"
value	
  0	
     @odata.id	null
     Count	    1166

Antal områden

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value	
  0	
     @odata.id	null
     Count	    70

Antal användare

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value	
  0	
     @odata.id	null
     Count	    16

Returnera ett antal objekt och data

Om du vill returnera ett antal objekt tillsammans med välj data för objekten anger du frågealternativet $count=true . Följande frågor returnerar till exempel antalet arbetsobjekt, områdessökvägar och användare som definierats för ett projekt tillsammans med de angivna egenskaperna. Giltiga egenskaper finns i Metadatareferens för Azure Boards Analytics och kalenderdatum, Project och användarmetadatareferens för Azure DevOps Analytics.

Dricks

Om du inte anger vilka egenskaper som ska returneras returnerar Analytics alla egenskaper som definierats för den angivna entitetstypen.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/WorkItems?$count=true&$select=WorkItemId,Title,WorkItemType 
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/Areas?$count=true&$select=AreaName,AreaPath 
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/Users?$count=true&$select=UserName,UserEmail

Egenskaper för områden eller iterationer

Om du vill söka efter AreaSK egenskapen eller IterationSKeller för en områdessökväg eller iterationssökväg använder du följande frågor.

Returnera AreaSK för en specifik områdessökväg

Följande fråga anger att den AreaSK egenskap som definierats för Fabrikam Fiber\Service Delivery\Internet Area Path ska returneras. Information om hur du anger andra egenskaper som definierats för entitetsuppsättningen Areas finns i Metadatareferens för Azure Boards Analytics, Områden.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Areas?$filter=AreaPath eq 'Fabrikam Fiber\Service Delivery\Internet' &$select=AreaSK

Frågan returnerar följande data.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Areas(AreaSK)",
  "value": [
    {
      "AreaSK": "637dc203-0549-4415-9663-b6358ac27d21"
    }
  ]
}

Returnera IterationSK för en specifik iterationssökväg

Följande fråga anger att den IterationSK egenskap som definierats för Iterationssökvägen Fabrikam Fiber\Release 1\Sprint 3 ska returneras. Information om hur du anger andra egenskaper som definierats för entitetsuppsättningen Iterations finns i Metadatareferens för Azure Boards Analytics, Iterations.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Iterations?$filter=IterationPath eq 'Fabrikam Fiber\Release 1\Sprint 3' &$select=IterationSK

Frågan returnerar följande data.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Iterations(IterationSK)",
  "value": [
    {
      "IterationSK": "862e961a-ac7a-4fcc-9ebc-8afd0c12fed5"
    }
  ]
}

Returnera specifika egenskaper eller fält

Om du vill returnera specifika egenskaper eller arbetsobjektfält lägger du till en $select sats som anger egenskapsnamnen.

Om du till exempel vill returnera arbetsobjektets ID, Typ av arbetsobjekt, Rubrik och Tillstånd för arbetsobjekt lägger du till följande sats i frågan. Den här satsen anger de egenskaper som motsvarar de namngivna fälten.

Kommentar

Egenskapsnamn innehåller inga blanksteg. Frågan misslyckas om du lägger till blanksteg. OData-frågor kräver att uppmärksamhet ägnas åt både avstånd och hölje. Information om hur anpassade fältegenskaper är märkta finns i Metadatareferens för Azure Boards, Anpassade egenskaper.

Här anger vi för att returnera de tre viktigaste arbetsobjekten.

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$top=3

Analytics returnerar följande data.

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value	
   0	
      WorkItemId    462
      Title         "Test case"
      WorkItemType  "Test Case"
      State         "Design"
   1	
      WorkItemId	   491
      Title          "Change color settings"
      WorkItemType   "Shared Steps"
      State          "Active"
   2	
      WorkItemId	   461
      Title          "Test impediment"
      WorkItemType   "Impediment"
      State          "Open"

.

Filtrera dina data

Om du vill filtrera en entitetsuppsättning för att returnera valda objekt anger du en $filter sats som anger de villkor som objekten måste uppfylla. Vi bygger vidare på den senaste frågan och lägger här till en filtersats för att endast returnera funktionsarbetsobjekttyper som är i tillståndet Pågår .

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

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemType eq 'Feature' and State eq 'In Progress'&$select=WorkItemId,Title,AssignedTo,State

Analytics returnerar följande data.

  
@odata.context	"https://analytics.dev.azure.com/kelliott/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,State)"
value	
  0	
      WorkItemId	380
      Title	"Refresh web look, feel, performance factors"
      State	"In Progress"
  1	
      WorkItemId	480
      Title	"Customer Phone - Phase 1"
      State	"In Progress"
  2	
      WorkItemId	493
      Title	"Change initial view"
      State	"In Progress"
  3	
      WorkItemId	479
      Title	"Customer Web - Phase 1"
      State	"In Progress"
  4	
      WorkItemId	551
      Title	"Mobile feedback"
      State	"In Progress"

Ange flera filtersatser

Du kan använda AND och OR ange flera filtersatser.

Följande fråga anger till exempel att arbetsobjekt av typen User Story, Bug och Backlog Work (en anpassad typ av arbetsobjekt) ska returneras i tillstånden Nytt, Bekräftat eller Aktivt . Använd parenteser för att gruppera filtersatser efter behov.

Dessutom kan du använda olika funktioner som contains, startswithoch endswith mycket mer. Se OData-funktioner och -satser som stöds, funktioner som stöds.

Returnera data för fälten Identitet, Områdessökväg och Iteration Path

Välj egenskaper är associerade med navigeringsegenskaper och är inte direkt åtkomliga med hjälp av -instruktionen $select . Du måste använda en $expand instruktion för att returnera intressanta data. Dessa egenskaper är ofta associerade med flera egna egenskaper. Med identitetsfält kan du till exempel ange för att returnera användarnamnet eller användarens e-post.

Följande tabell innehåller exempel på hur du expanderar flera av dessa egenskaper.

Typfält Refererad egenskap Exempelsatser som ska inkluderas
Datum/tid DateSK $expand=CreatedDate($select=Date) eller
$expand=CreatedDate($select=WeekStartingDate)
Identitet UserSK $expand=AssignedTo($select=UserName) eller
$expand=AssignedTo($select=UserEmail)
Ytdiagram AreaSK $expand=Area($select=AreaName) eller
$expand=Area($select=AreaPath)
Iteration IterationSK $expand=Iteration($select=IterationName) eller
$expand=Iteration($select=IterationPath) eller
$expand=Iteration($select=StartDate)
Projekt ProjectSK $expand=Project($select=ProjectName)
Team TeamSK $expand=Teams($select=TeamName)

Om du vill ange flera egenskaper som måste expanderas anger du dem i en enda expanderingssats i en kommaavgränsad lista.

$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath)

Filtrera efter en navigeringsegenskap

När du anger en navigeringsegenskap som en del av filtervillkoren måste du ange den i det format som krävs.

Följande sats anger till exempel att arbetsobjekt ska filtreras baserat på iteration 1 som definierats för projektet.

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

I det här exemplet Iteration är namnet på navigeringsegenskapen och IterationPath motsvarar den fullständiga sökvägen för iterationen. Om du vill använda en annan entitet som ett filter placerar du navigeringsegenskapen följt av ett snedstreck följt av namnet på fältet som ska filtreras på.

Och här är den fullständiga OData-frågan:

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

Här är ett annat exempel som begär att de fem främsta arbetsobjekten under Fabrikam Fiber\Service Delivery\Voice Area Path returneras.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Area/AreaPath eq 'Fabrikam Fiber\Service Delivery\Voice'&$select=WorkItemId, WorkItemType, Title, State&$orderby=WorkItemId asc

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value	
  0	
     WorkItemId	361
     Title        "Hello World Web Site"
     WorkItemType	"Product Backlog Item"
     State        "Removed"
  1	
     WorkItemId	362
     Title        "Resume"
     WorkItemType	"Product Backlog Item"
     State        "New"
  2	
     WorkItemId	363
     Title        "Welcome back page"
     WorkItemType	"Product Backlog Item"
     State        "Done"
  3	
     WorkItemId	365
     Title        "Pause"
     WorkItemType	"Feature"
     State        "New"
  4	
     WorkItemId	374
     Title        "Fix performance issues"
     WorkItemType	"Task"
     State        "To Do"

Dricks

Du kan inte använda navigeringsegenskapen direkt i en $select -instruktion. I stället måste du använda $expand.

Det tidigare filtreringsexemplet för iterationssökvägen returnerar inte iterationssökvägen eftersom den finns i en relaterad entitet. Om du vill returnera data i en relaterad entitet lägger du till en $expand instruktion:

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

Och här är ett exempel som returnerar information som tilldelats arbetsobjekts-ID 480.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&&$expand=Iteration
   
@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)"
value	
  0	
      WorkItemId           480
      Title                "Customer Phone - Phase 1"
      WorkItemType	       "Feature"
      State	               "In Progress"
      Iteration	
          ProjectSK	       "56af920d-393b-4236-9a07-24439ccaa85c"
          IterationSK	       "c7063041-ff3a-4d7f-bb46-c433c7030d59"
          IterationId	       "c7063041-ff3a-4d7f-bb46-c433c7030d59"
          IterationName	   "Sprint 1"
          Number	            55297
          IterationPath	    "Fabrikam Fiber\\Release 1\\Sprint 1"
          StartDate	        "2022-01-17T00:00:00-08:00"
          EndDate	            "2022-02-04T23:59:59.999-08:00"
          IterationLevel1	    "Fabrikam Fiber"
          IterationLevel2	    "Release 1"
          IterationLevel3	    "Sprint 1"
          IterationLevel4	    null
          IterationLevel5	    null
          IterationLevel6	    null
          IterationLevel7	    null
          IterationLevel8	    null
          IterationLevel9	    null
          IterationLevel10	null
          IterationLevel11	null
          IterationLevel12	null
          IterationLevel13	null
          IterationLevel14	null
          Depth	            2
          IsEnded	        	true
      AnalyticsUpdatedDate	"2022-01-18T22:18:58.17Z"

Som du ser expanderas iterationssökvägen i resultatet och alla iterationsdata returneras. Det är förmodligen mer data än du vill.

Om du vill returnera mindre data lägger du även till en $select instruktion mot iterationen:

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

Sedan returneras följande data.

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

Fråga efter ett datumintervall

I följande exempel returneras arbetsobjekt vars ändrade datum är större än 1 januari 2021.

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

I följande exempel returneras arbetsobjekt vars ändrade datum inträffar under veckan 26 april till 30 april 2021.

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

Nest expand-uttryck

I OData kan du kapsla $expand instruktioner. Du kan till exempel skriva föregående frågeuttryck för att visa projektet som iterationen är en del av:

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

Den returnerar följande JSON:

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

Du kan också kombinera $expand och $select instruktioner. Du kan till exempel ändra den tidigare frågan så att den endast returnerar iterationsnamnet och iterationssökvägen:

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

Den returnerar följande JSON:

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

Observera att resultatet här endast visar IterationId och IterationPath och att projektet är ett kapslat objekt i JSON-resultatet. Ett annat viktigt objekt att notera är själva URL:en. När du använder en $select -instruktion och en $expand -sats måste du använda ett semikolon (;) före $expand. Allt annat resulterar i ett fel.

Sortera resultat, orderby alternativ

Ange alternativet $orderby för att sortera dina resultat eller ange i vilken ordning resultaten returneras. Du kan sortera i stigande eller fallande ordning med hjälp av nyckelord asc descrespektive . Några exempel visas

Sort by Sats som ska inkluderas
Arbetsobjekts-ID /WorkItems?$orderby=WorkItemId
Arbetsobjekts-ID fallande /WorkItems?$orderby=WorkItemId desc
Typ av arbetsobjekt och tillstånd /WorkItems?$orderby=WorkItemType,State

Nästa steg