Basisquery's definiëren met OData Analytics

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Gebruik OData-query's van Analytics om werktraceringsgegevens op te halen uit Azure DevOps in uw browser of in clienthulpprogramma's zoals Excel en Power BI. Dit artikel bevat informatie over het tellen van items, het selecteren van specifieke velden met $select, filteren met $filter, uitbreidende navigatie-eigenschappen met $expand, het opvragen van datumbereiken en sorteren met $orderby.

De voorbeelden richten zich op Azure Boards voor het bijhouden van entiteitssets, maar dezelfde principes zijn van toepassing op andere entiteitssets. Zie OData-query's maken voor analyse - en metagegevensreferenties voor Azure Boards Analytics voor meer informatie.

Vereisten

Een telling van items verkrijgen

Als u alleen een telling wilt retourneren zonder andere gegevens, voegt u $apply=aggregate($count as Count) toe aan elke entiteitenset-URL. De volgende query's tellen bijvoorbeeld projecten, werkitems, gebiedspaden en gebruikers binnen 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)

De Projects query voor de fabrikam organisatie retourneert:

{
  "value": [
    {
      "Count": 16
    }
  ]
}

Haalt het aantal items en hun gegevens op

Om een telling samen met de gegevens te retourneren, voegt u $count=true toe aan een query die een $select clausule bevat. De volgende query's retourneren een telling plus geselecteerde eigenschappen voor werkitems, vlakpaden en gebruikers in een project:

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

Zie voor geldige eigenschapsnamen de naslaginformatie over metagegevens van Azure Boards Analytics en de naslaginformatie over kalenderdatum, Project en gebruikersmetagegevens.

De volgende query retourneert bijvoorbeeld het aantal en de gebruikersnamen in het Fabrikam Fiber-project :

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Users?$count=true&$select=UserName

Het antwoord bevat het totale aantal in @odata.count en de overeenkomende records in value:

{
  "@odata.count": 5,
  "value": [
    { "UserName": "Microsoft.VisualStudio.Services.TFS" },
    { "UserName": "fabrikamfiber1@hotmail.com" },
    { "UserName": "Jamal Hartnett" },
    { "UserName": "fabrikamfiber5@hotmail.com" },
    { "UserName": "fabrikamfiber2@hotmail.com" }
  ]
}

Specifieke eigenschappen of velden selecteren

Voeg een $select component toe om alleen de eigenschappen te retourneren die u nodig hebt. Eigenschapsnamen zijn hoofdlettergevoelig, kunnen geen spaties bevatten en overeenkomen met veldnamen van werkitems. Retourneert bijvoorbeeld $select=WorkItemId,WorkItemType,Title,State deze vier velden.

Zie naslaginformatie voor metagegevens voor Azure Boards voor eigenschapsopzoekingen, inclusief aangepaste velden.

De volgende query retourneert de id, het type, de titel en de status voor de drie belangrijkste werkitems in het Fabrikam Fiber-project:

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

{
  "value": [
    { "WorkItemId": 31, "Title": "About screen", "WorkItemType": "Task", "State": "New" },
    { "WorkItemId": 30, "Title": "Change background color", "WorkItemType": "Task", "State": "Active" },
    { "WorkItemId": 32, "Title": "Standardize on form factors", "WorkItemType": "Task", "State": "Active" }
  ]
}

Gegevens filteren

Voeg een $filter component toe om alleen items te retourneren die voldoen aan specifieke criteria. Gebruik vergelijkingsoperatoren zoals eq, ne, gt, ge, lt en le, en combineer voorwaarden met and en or. De volgende query retourneert bijvoorbeeld functies die worden uitgevoerd:

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

Meerdere filtervoorwaarden combineren

Gebruik haakjes om voorwaarden binnen een breder or filter te groeperenand. De volgende query retourneert gebruikersverhalen, bugs en een aangepast type in specifieke staten.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,AssignedTo,State&$filter=(WorkItemType eq 'User Story' or WorkItemType eq 'Bug' or WorkItemType eq 'Backlog Work') and (State eq 'New' or State eq 'Committed' or State eq 'Active')

{
  "value": [
    { "WorkItemId": 210, "Title": "Slow response on form", "State": "Active" },
    ...
    { "WorkItemId": 160, "Title": "Game store testing", "State": "New" }
  ]
}

U kunt ook tekenreeksfuncties zoals contains, startswithen endswith in filterexpressies gebruiken. Zie Ondersteunde functies voor meer informatie.

Eigenschappen van pad naar querygebied of iteratiepad

Voor sommige query's is de surrogaatsleutel (AreaSK of IterationSK) vereist in plaats van de padtekenreeks. Gebruik de entiteit Gebieden of Iteraties om de sleutel voor een specifiek pad op te zoeken.

De AreaSK voor een specifiek gebiedspad retourneren

De volgende query retourneert het AreaSK voor het Fabrikam Fiber\Production Planning\Web gebiedspad. Zie Gebieden voor andere beschikbare eigenschappen.

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

{
  "value": [
    { "AreaSK": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" }
  ]
}

Geef de IterationSK terug voor een specifiek iteratiepad

De volgende query geeft het IterationSK terug voor het Fabrikam Fiber\Release 1\Sprint 3 iteratiepad. Zie Iteraties voor andere beschikbare eigenschappen.

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

Filteren op navigatie-eigenschappen

Navigatie-eigenschappen zoals Iteration, Areaen AssignedTo vertegenwoordigen relaties met andere entiteiten. Als u wilt filteren op een veld van een gerelateerde entiteit, gebruikt u het volledige pad in de indeling NavigationProperty/Field. Verwijst bijvoorbeeld Iteration/IterationPath naar het IterationPath veld via de Iteration navigatie-eigenschap:

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

De volgende query retourneert de vijf belangrijkste werkitems in een specifieke iteratie, met behulp van het volledige navigatiepad:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Iteration/IterationPath eq 'Fabrikam Fiber\3Week Sprints\Sprint 3'&$select=WorkItemId,WorkItemType,Title,State&$orderby=WorkItemId asc

Gegevens uit gerelateerde entiteiten uitvouwen

Filteren op een navigatie-eigenschap bevat geen gegevens in het antwoord. Als u velden van een gerelateerde entiteit wilt retourneren, gebruikt u $expand. Zonder $expand, kunt u geen toegang krijgen tot navigatie-eigenschapsvelden via $select.

De volgende query retourneert werkitem 480 met alle velden uit de uitgebreide Iteration entiteit:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration

Omdat er geen $select wordt toegepast op de Iteration uitbreiding, bevat het antwoord elk Iteration veld:

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "IterationSK": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "StartDate": "2025-12-04T00:00:00-12:00",
        "EndDate": "2025-12-25T23:59:59.999-12:00",
        "IterationLevel1": "Fabrikam Fiber",
        "IterationLevel2": "3Week Sprints",
        "IterationLevel3": "Sprint 3",
        ...
        "Depth": 2,
        "IsEnded": false
      }
    }
  ]
}

Gebruik 'Select' in uitbreidingsinstructies

Als u de velden wilt beperken die worden geretourneerd door een uitgebreide entiteit, voegt u een $select clausule toe binnen de $expand met de syntaxis $expand=Entity($select=Field1,Field2). De volgende query breidt Iteration uit, maar retourneert alleen IterationName en IterationPath:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath)

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3"
      }
    }
  ]
}

In de volgende tabel ziet u $expand met $select voorbeelden voor algemene typen navigatie-eigenschappen.

Als u meerdere navigatie-eigenschappen in één query wilt uitvouwen, gebruikt u een door komma's gescheiden lijst:

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

Gebruik geneste uitbreidingsverklaringen

Als u een navigatie-eigenschap binnen een al uitgevouwen entiteit wilt uitbreiden, nestt u de $expand ene binnen de andere. De volgende query breidt Iteration en vervolgens Project uit binnen Iteration om weer te geven tot welk project de iteratie behoort.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($expand=Project)

Om geneste uitbreidingen met $select te combineren, gebruikt u een puntkomma (;) om $select te scheiden van $expand binnen de haakjes. Zonder de puntkomma retourneert de query een fout. De volgende query retourneert alleen IterationName en IterationPath van Iteration, plus het geneste Project:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath;$expand=Project)

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "Project": {
          "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber"
        }
      }
    }
  ]
}

Een datumbereik opvragen

De volgende voorbeeldquery retourneert werkitems waarvan de laatste wijzigingsdatum groter is dan of gelijk is aan 1 januari 2025.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-01-01Z

De volgende voorbeeldquery retourneert werkitems waarvan de laatste wijzigingsdatum plaatsvond in de week van 31 oktober tot en met 7 november 2025.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-10-31Z and ChangedDate le 2025-11-07Z

Resultaten sorteren

Voeg toe $orderby om resultaten te sorteren op een of meer eigenschappen. Resultaten sorteren standaard in oplopende volgorde; toevoegen desc voor aflopend. Scheid meerdere sorteervelden met komma's.

Volgende stap

Verwante inhoud

• OData-query's maken voor Analyse
• Gegevens aggregeren met behulp van Analytics
• Naslaginformatie over metagegevens voor Azure Boards Analytics
• Aanbevolen procedures voor het uitvoeren van query's op Analytics
• Ondersteunde OData-functies
• OData v4.0 Deel 2: URL Conventions Plus Errata 02