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 IterationSK
eller 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
, startswith
och 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
desc
respektive . 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 |