Share via

Basisquery's definiëren met OData Analytics

  • Artikel

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

Met behulp van Analytics voor Azure DevOps kunt u eenvoudige en gefilterde query's maken om interessante gegevens te retourneren. U kunt deze query's rechtstreeks uitvoeren in uw browser of in Power BI.

In dit artikel wordt informatie uitgetrokken die wordt gegeven in OData-query's maken voor naslaginformatie over analyse en metagegevens voor Azure Boards Analytics. De query's in dit artikel zijn ook gericht op het ophalen van entiteitssets voor het bijhouden van werk, maar de principes zijn van toepassing op het uitvoeren van query's op andere entiteitssets.

In dit artikel leert u hoe u query's definieert die de volgende gegevens retourneren:

  • Aantal items (geen andere gegevens)
  • Aantal items en gegevens
  • Eigenschappen gedefinieerd voor gebieden of iteratiepaden
  • Geselecteerde kolommen of velden
  • Gefilterde gegevens
  • Gegevens retourneren voor de velden Identiteit, Gebiedspad en Iteratiepad
  • Filteren op een navigatie-eigenschap
  • Een datumbereik opvragen
  • Uitvouwinstructies nesten
  • Resultaten sorteren, orderby-optie

Notitie

De Analytics-service wordt automatisch ingeschakeld en ondersteund in productie voor alle Azure DevOps-services. Power BI-integratie en -toegang tot de OData-feed van de Analytics-service zijn algemeen beschikbaar. We raden u aan deze te gebruiken en ons feedback te geven. Beschikbare gegevens zijn afhankelijk van versie. De meest recente ondersteunde versie is v2.0en de nieuwste preview-versie is v4.0-preview. Zie OData API-versiebeheer voor meer informatie.

Notitie

De Analytics-service wordt automatisch geïnstalleerd en ondersteund in productie voor alle nieuwe projectverzamelingen voor Azure DevOps Server 2020 en nieuwere versies. Power BI-integratie en -toegang tot de OData-feed van de Analytics-service zijn algemeen beschikbaar. We raden u aan deze te gebruiken en ons feedback te geven. Als u een upgrade hebt uitgevoerd van Azure DevOps Server 2019, kunt u de Analytics-service installeren tijdens de upgrade.

Beschikbare gegevens zijn afhankelijk van versie. De meest recente ondersteunde versie is v2.0en de nieuwste preview-versie is v4.0-preview. Zie OData API-versiebeheer voor meer informatie.

Notitie

De Analytics-service is in preview voor Azure DevOps Server 2019. U kunt deze in- of installeren voor een projectverzameling. Power BI-integratie en toegang tot de OData-feed van de Analytics-service zijn in preview. We raden u aan deze te gebruiken en ons feedback te geven.

Beschikbare gegevens zijn afhankelijk van versie. De meest recente ondersteunde versie is v2.0en de nieuwste preview-versie is v4.0-preview. Zie OData API-versiebeheer voor meer informatie.

Vereisten

Notitie

In dit artikel wordt de OData-query-URL gedefinieerd voor Azure DevOps Services. Als u een vergelijkbare query voor een on-premises server wilt maken, raadpleegt u de richtlijnen in Construct OData-query's voor Analyse. We raden u aan om de query's voor uw organisatie en project aan te passen om vertrouwd te raken met het uitvoeren van query's op OData met behulp van uw browser.

Een aantal items retourneren (geen andere gegevens)

Voor meer informatie over het aantal items of entiteiten dat is gedefinieerd in een organisatie of project, geeft u $apply=aggregate($count as Count) de queryoptie op. De volgende query's retourneren bijvoorbeeld het aantal projecten, werkitems, gebiedspaden en gebruikers die zijn gedefinieerd voor een organisatie.

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)

Tip

Query's tussen projecten mislukken wanneer de gebruiker die de query uitvoert, geen toegang heeft tot alle projecten. Lees meer over vereisten in Project- en organisatiequery's.

Aantal projecten

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

Aantal werkitems

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

Aantal gebieden

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

Aantal gebruikers

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

Een aantal items en gegevens retourneren

Als u een aantal items wilt retourneren, samen met geselecteerde gegevens voor de items, geeft u de $count=true queryoptie op. De volgende query's retourneren bijvoorbeeld een telling van werkitems, vlakpaden en gebruikers die zijn gedefinieerd voor een project, samen met de opgegeven eigenschappen. Zie de naslaginformatie over metagegevens voor Azure Boards Analytics en kalenderdatum, Project en Metagegevens van gebruikers voor Azure DevOps Analytics voor geldige eigenschappen.

Tip

Als u niet de eigenschappen opgeeft die moeten worden geretourneerd, retourneert Analytics alle eigenschappen die zijn gedefinieerd voor het opgegeven entiteitstype.

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

Eigenschappen van gebieden of iteraties

Gebruik de volgende query's om de AreaSK of IterationSKof andere eigenschap van een gebiedspad of iteratiepad op te zoeken.

De AreaSK voor een specifiek gebiedspad retourneren

De volgende query geeft aan dat de AreaSK eigenschap moet worden geretourneerd die is gedefinieerd voor het pad Fabrikam Fiber\Service Delivery\Internet Area. Als u andere eigenschappen wilt opgeven die zijn gedefinieerd voor de Areas entiteitsset, raadpleegt u de metagegevensreferentie voor Azure Boards Analytics, Gebieden.

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

De query retourneert de volgende gegevens.

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

De IterationSK retourneren voor een specifiek iteratiepad

De volgende query geeft aan dat de IterationSK eigenschap moet worden geretourneerd die is gedefinieerd voor het iteratiepad Fabrikam Fiber\Release 1\Sprint 3. Als u andere eigenschappen wilt opgeven die zijn gedefinieerd voor de Iterations entiteitsset, raadpleegt u de metagegevensverwijzing voor Azure Boards Analytics, iteraties.

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

De query retourneert de volgende gegevens.

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

Specifieke eigenschappen of velden retourneren

Als u specifieke eigenschappen of werkitemvelden wilt retourneren, voegt u een $select component toe waarmee de eigenschapsnamen worden opgegeven.

Als u bijvoorbeeld de werkitem-id, het werkitemtype, de titel en de status van werkitems wilt retourneren, voegt u de volgende component toe aan uw query. Met deze component worden de eigenschappen opgegeven die overeenkomen met de benoemde velden.

Notitie

Eigenschapsnamen bevatten geen spaties. Uw query mislukt als u spaties toevoegt. OData-query's vereisen dat aandacht wordt besteed aan zowel afstand als behuizing. Als u wilt weten hoe eigenschappen van aangepaste velden worden gelabeld, raadpleegt u Metagegevensreferenties voor Azure Boards, Aangepaste eigenschappen.

Hier geven we op om de drie belangrijkste werkitems te retourneren.

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

Analytics retourneert de volgende gegevens.

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

.

Uw gegevens filteren

Als u een entiteit wilt filteren die is ingesteld om items te retourneren, geeft u een $filter component op die de criteria aangeeft waaraan de items moeten voldoen. Verder bouwend op de laatste query voegen we hier een filtercomponent toe om alleen functiewerkitemtypen te retourneren die de status Wordt uitgevoerd hebben.

/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 retourneert de volgende gegevens.

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

Verschillende filtercomponenten opgeven

U kunt verschillende filtercomponenten gebruiken AND en OR opgeven.

De volgende query geeft bijvoorbeeld aan om werkitems van het type Gebruikersverhaal, Bug en Backlog Work (een aangepast werkitemtype) te retourneren die de status Nieuw, Doorgevoerd of Actief hebben. Gebruik haakjes om filterclausules indien nodig te groeperen.

Daarnaast kunt u verschillende functies containszoals , startswithendswith en meer toepassen. Zie de ondersteunde OData-functies en -componenten, ondersteunde functies.

Gegevens retourneren voor de velden Identiteit, Gebiedspad en Iteratiepad

Selecteereigenschappen zijn gekoppeld aan navigatie-eigenschappen en zijn niet rechtstreeks toegankelijk met behulp van de $select instructie. U moet een $expand instructie gebruiken om de interessegegevens te retourneren. Deze eigenschappen zijn vaak gekoppeld aan verschillende eigenschappen van hun eigen eigenschappen. Met identiteitsvelden kunt u bijvoorbeeld opgeven dat de gebruikersnaam of het e-mailadres van de gebruiker moet worden geretourneerd.

De volgende tabel bevat voorbeelden van het uitbreiden van verschillende van deze eigenschappen.

Velden typen Eigenschap Waarnaar wordt verwezen Voorbeeldclausules die moeten worden opgenomen
Datum en tijd DateSK $expand=CreatedDate($select=Date) of
$expand=CreatedDate($select=WeekStartingDate)
Identiteit UserSK $expand=AssignedTo($select=UserName) of
$expand=AssignedTo($select=UserEmail)
Gebied AreaSK $expand=Area($select=AreaName) of
$expand=Area($select=AreaPath)
Iteratie IterationSK $expand=Iteration($select=IterationName) of
$expand=Iteration($select=IterationPath) of
$expand=Iteration($select=StartDate)
Project ProjectSK $expand=Project($select=ProjectName)
Team TeamSK $expand=Teams($select=TeamName)

Als u verschillende eigenschappen wilt opgeven die moeten worden uitgevouwen, geeft u deze op in één uitvouwcomponent in een door komman gescheiden lijst.

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

Filteren op een navigatie-eigenschap

Wanneer u een navigatie-eigenschap opgeeft als onderdeel van uw filtercriteria, moet u deze opgeven in de vereiste indeling.

De volgende component geeft bijvoorbeeld aan om werkitems te filteren op basis van iteratie 1 die voor het project zijn gedefinieerd.

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

In dit voorbeeld Iteration is dit de naam van de navigatie-eigenschap en IterationPath komt overeen met het volledige pad voor de iteratie. Als u een andere entiteit wilt gebruiken als filter, plaatst u de navigatie-eigenschap gevolgd door een slash gevolgd door de naam van het veld waarop u wilt filteren.

En hier is de volledige OData-query:

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

Hier volgt een ander voorbeeld waarbij de vijf belangrijkste werkitems onder het pad Fabrikam Fiber\Service Delivery\Voice Area worden geretourneerd.

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"

Tip

U kunt de navigatie-eigenschap niet rechtstreeks in een $select instructie gebruiken. In plaats daarvan moet u gebruiken $expand.

Het vorige filtervoorbeeld voor het iteratiepad retourneert het iteratiepad niet omdat het is opgenomen in een gerelateerde entiteit. Als u gegevens in een gerelateerde entiteit wilt retourneren, voegt u een $expand instructie toe:

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

Hier volgt een voorbeeld dat informatie retourneert die is toegewezen aan werkitem-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"

Zoals u kunt zien, wordt het iteratiepad uitgebreid in het resultaat en worden alle iteratiegegevens geretourneerd. Het zijn waarschijnlijk meer gegevens dan u wilt.

Als u minder gegevens wilt retourneren, voegt u ook een $select instructie toe aan de iteratie:

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

Vervolgens worden de volgende gegevens geretourneerd.

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

Een datumbereik opvragen

In het volgende voorbeeld worden werkitems geretourneerd waarvan de gewijzigde datum groter is dan 1 januari 2021.

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

In het volgende voorbeeld worden werkitems geretourneerd waarvan de gewijzigde datum plaatsvindt in de week van 26 april tot en met 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

Uitvouwinstructies nesten

In OData kunt u instructies nesten $expand . U kunt bijvoorbeeld de vorige query-instructie schrijven om het project weer te geven waarvan de iteratie deel uitmaakt:

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

Hiermee wordt de volgende JSON geretourneerd:

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

U kunt ook instructies combineren $expand en $select verklaringen. U kunt bijvoorbeeld de vorige query wijzigen zodat alleen de iteratienaam en het iteratiepad worden geretourneerd:

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

Hiermee wordt de volgende JSON geretourneerd:

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

U ziet dat in het resultaat hier alleen de IterationId en IterationPath worden weergegeven en dat het project een genest object is binnen het JSON-resultaat. Een ander belangrijk item dat u moet noteren, is de URL zelf. Wanneer u een $select instructie en een $expand component gebruikt, moet u een puntkomma (;) vóór de $expand. Als u iets anders doet, treedt er een fout op.

Resultaten sorteren, orderby optie

Geef de $orderby optie op om uw resultaten te sorteren of geef de volgorde op waarin de resultaten worden geretourneerd. U kunt sorteren in oplopende of aflopende volgorde met trefwoorden asc of descrespectievelijk. Enkele voorbeelden worden weergegeven

Sorteren op Component die moet worden opgenomen
Werkitem-id /WorkItems?$orderby=WorkItemId
Id van werkitem aflopend /WorkItems?$orderby=WorkItemId desc
Type werkitem en status /WorkItems?$orderby=WorkItemType,State

Volgende stappen

Query's binnen project- en organisatiebereik