Definování základních dotazů pomocí OData Analytics
Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019
Pomocí Analytics pro Azure DevOps můžete vytvořit základní a filtrované dotazy, které vrátí data, která vás zajímají. Tyto dotazy můžete spouštět přímo v prohlížeči nebo v Power BI.
Tento článek sestaví informace poskytnuté v dotazech OData pro analýzu a metadata pro Azure Boards Analytics. Dotazy v tomto článku se také zaměřují na načítání sad entit sledování práce, ale zásady platí pro dotazování jiných sad entit.
V tomto článku se dozvíte, jak definovat dotazy, které vracejí následující data:
- Počet položek (žádná jiná data)
- Počet položek a dat
- Vlastnosti definované pro oblasti nebo cesty iterace
- Vybrané sloupce nebo pole
- Filtrovaná data
- Vrácení dat pro pole Cesta k identitě, cestě oblasti a cestě iterace
- Filtrování podle navigační vlastnosti
- Dotazování rozsahu dat
- Vnoření příkazů rozbalení
- Řazení výsledků, možnost orderby
Poznámka:
Služba Analytics je automaticky povolená a podporovaná v produkčním prostředí pro všechny služby Azure DevOps Services. Integrace Power BI a přístup k datovému kanálu OData služby Analytics jsou obecně dostupné. Doporučujeme, abyste ho používali a poskytli nám zpětnou vazbu.
Dostupná data jsou závislá na verzi. Nejnovější podporovaná verze je v2.0
a nejnovější verze Preview je v4.0-preview
. Další informace najdete v tématu Správa verzí rozhraní API OData.
Poznámka:
Služba Analytics se automaticky nainstaluje a podporuje v produkčním prostředí pro všechny nové kolekce projektů pro Azure DevOps Server 2020 a novější verze. Integrace Power BI a přístup k datovému kanálu OData služby Analytics jsou obecně dostupné. Doporučujeme, abyste ho používali a poskytli nám zpětnou vazbu. Pokud jste upgradovali z Azure DevOps Serveru 2019, můžete během upgradu nainstalovat službu Analytics.
Dostupná data jsou závislá na verzi. Nejnovější podporovaná verze je v2.0
a nejnovější verze Preview je v4.0-preview
. Další informace najdete v tématu Správa verzí rozhraní API OData.
Poznámka:
Služba Analytics je ve verzi Preview pro Azure DevOps Server 2019. Můžete ji povolit nebo nainstalovat pro kolekci projektů. Integrace Power BI a přístup k datovému kanálu OData služby Analytics jsou ve verzi Preview. Doporučujeme, abyste ho používali a poskytli nám zpětnou vazbu.
Dostupná data jsou závislá na verzi. Nejnovější podporovaná verze je v2.0
a nejnovější verze Preview je v4.0-preview
. Další informace najdete v tématu Správa verzí rozhraní API OData.
Požadavky
- Přístup: Buďte členem projektu s alespoň základním přístupem.
- Oprávnění: Ve výchozím nastavení mají členové projektu oprávnění k dotazování na Analýzy a vytváření zobrazení.
- Další informace o dalších požadavcích týkajících se povolení služeb a funkcí a obecných aktivit sledování dat najdete v tématu Oprávnění a požadavky pro přístup k Analýzám.
Poznámka:
V tomto článku je definována adresa URL dotazu OData pro Azure DevOps Services. Pokud chcete vytvořit podobný dotaz pro místní server, přečtěte si pokyny uvedené v dotazech OData konstruktoru pro analýzu. Doporučujeme vám upravit dotazy poskytované pro vaši organizaci a projekt, abyste se seznámili s dotazováním OData pomocí prohlížeče.
Vrácení počtu položek (žádná jiná data)
Pokud se chcete dozvědět o počtu položek nebo entit definovaných v organizaci nebo projektu, zadejte $apply=aggregate($count as Count)
možnost dotazu. Například následující dotazy vrátí počet projektů, pracovních položek, cest oblastí a uživatelů definovaných pro organizaci.
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
Dotazy napříč projekty selžou, když uživatel, který dotaz spouští, nemá přístup ke všem projektům. Přečtěte si další informace o požadavcích v dotazech v Projectu a dotazech v oboru organizace.
Počet projektů
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(Count)"
value
0
@odata.id null
Count 28
Počet pracovních položek
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)"
value
0
@odata.id null
Count 1166
Počet oblastí
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value
0
@odata.id null
Count 70
Počet uživatelů
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value
0
@odata.id null
Count 16
Vrácení počtu položek a dat
Pokud chcete vrátit počet položek spolu s vybranými daty pro položky, zadejte $count=true
možnost dotazu. Například následující dotazy vrátí počet pracovních položek, cest oblastí a uživatelů definovaných pro projekt spolu se zadanými vlastnostmi. Platné vlastnosti najdete v referenčních informacích k metadatám pro azure Boards Analytics a kalendářní datum, projekt a uživatelská metadata pro Azure DevOps Analytics.
Tip
Pokud nezadáte vlastnosti, které se mají vrátit, vrátí Analýza všechny vlastnosti definované pro zadaný typ entity.
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
Vlastnosti oblastí nebo iterací
Pokud chcete vyhledat AreaSK
nebo IterationSK
nebo jinou vlastnost cesty oblasti nebo cesty iterace, použijte následující dotazy.
Vrácení areaSK pro konkrétní cestu k oblasti
Následující dotaz určuje vrácení AreaSK
vlastnosti definované pro Fabrikam Fiber\Service Delivery\Internet Area Path. Pokud chcete zadat další vlastnosti definované pro Areas
sadu entit, přečtěte si referenční informace k metadatům pro analýzy Azure Boards, oblasti.
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Areas?$filter=AreaPath eq 'Fabrikam Fiber\Service Delivery\Internet' &$select=AreaSK
Dotaz vrátí následující 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"
}
]
}
Vrácení iteračního znaku (ITerationSK) pro konkrétní cestu iterace
Následující dotaz určuje vrácení IterationSK
vlastnosti definované pro cestu iterace Fabrikam Fiber\Release 1\Sprint 3. Pokud chcete zadat další vlastnosti definované pro Iterations
sadu entit, přečtěte si referenční informace k metadatům pro Azure Boards Analytics a iterace.
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Iterations?$filter=IterationPath eq 'Fabrikam Fiber\Release 1\Sprint 3' &$select=IterationSK
Dotaz vrátí následující 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"
}
]
}
Vrácení konkrétních vlastností nebo polí
Pokud chcete vrátit konkrétní vlastnosti nebo pole pracovních položek, přidejte $select
klauzuli, která určuje názvy vlastností.
Pokud chcete například vrátit ID pracovní položky, typ pracovní položky, název a stav pracovních položek, přidejte do dotazu následující klauzuli. Tato klauzule určuje vlastnosti, které odpovídají pojmenovaným polím.
Poznámka:
Názvy vlastností neobsahují žádné mezery. Pokud přidáte mezery, dotaz se nezdaří. Dotazy OData vyžadují pozornost jak pro mezery, tak velikost písmen. Informace o tom, jak jsou vlastnosti vlastního pole označené, najdete v referenčních informacích k metadatům pro Azure Boards, vlastní vlastnosti.
Tady určíme, že se mají vrátit první tři pracovní položky.
https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$top=3
Analýza vrátí následující 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"
.
Filtrování dat
Pokud chcete filtrovat entitu nastavenou tak, aby vracela vybrané položky, zadejte $filter
klauzuli, která určuje kritéria, která musí položky splňovat. Na základě posledního dotazu zde přidáme klauzuli filtru, která vrátí pouze typy pracovních položek funkce , které jsou ve stavu Probíhá .
/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
Analýza vrátí následující 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"
Zadání několika klauzulí filtru
Můžete použít AND
a OR
zadat několik klauzulí filtru.
Například následující dotaz určuje, že se mají vracet pracovní položky typu Uživatelský scénář, Chyba a Práce backlogu (vlastní typ pracovní položky), které jsou ve stavu Nové, Potvrzeno nebo Aktivní . Pomocí závorek můžete podle potřeby seskupit klauzule filtru.
Kromě toho můžete použít různé funkce, jako contains
je , startswith
endswith
a další. Viz podporované funkce a klauzule OData, Podporované funkce.
Vrácení dat pro pole Cesta k identitě, cestě oblasti a cestě iterace
Výběrové vlastnosti jsou přidružené k navigačním vlastnostem a nejsou přímo přístupné pomocí příkazu $select
. K vrácení dat, která vás zajímají, musíte použít $expand
příkaz. Tyto vlastnosti jsou často spojeny s několika vlastními vlastnostmi. Pomocí polí Identita můžete například zadat, aby se vrátilo uživatelské jméno nebo e-mail uživatele.
Následující tabulka obsahuje příklady, jak rozbalit několik těchto vlastností.
Pole typu | Odkazovaná vlastnost | Příklady klauzulí, které se mají zahrnout |
---|---|---|
DateTime | DateSK |
$expand=CreatedDate($select=Date) nebo$expand=CreatedDate($select=WeekStartingDate) |
Identita | UserSK |
$expand=AssignedTo($select=UserName) nebo$expand=AssignedTo($select=UserEmail) |
Plocha | AreaSK |
$expand=Area($select=AreaName) nebo$expand=Area($select=AreaPath) |
Iterace | IterationSK |
$expand=Iteration($select=IterationName) nebo$expand=Iteration($select=IterationPath) nebo$expand=Iteration($select=StartDate) |
Projekt | ProjectSK |
$expand=Project($select=ProjectName) |
Tým | TeamSK |
$expand=Teams($select=TeamName) |
Chcete-li zadat několik vlastností, které je třeba rozbalit, zadáte je v jediné rozbalovací klauzuli v seznamu oddělených čárkami.
$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath)
Filtrování podle navigační vlastnosti
Když jako součást kritérií filtru zadáte navigační vlastnost, musíte ji zadat v požadovaném formátu.
Například následující klauzule určuje filtrování pracovních položek na základě iterace 1 definované pro projekt.
/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'
V tomto příkladu Iteration
je název navigační vlastnosti a IterationPath
odpovídá úplné cestě pro iteraci. Chcete-li použít jinou entitu jako filtr, umístěte navigační vlastnost následovanou lomítkem následovaným názvem pole, podle které chcete filtrovat.
A tady je úplný dotaz OData:
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'
Tady je další příklad, který požaduje prvních pět pracovních položek v cestě Fabrikam Fiber\Service Delivery\Voice Area Path.
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
Navigační vlastnost nelze použít přímo v $select
příkazu. Místo toho musíte použít $expand
.
Předchozí příklad filtrování pro cestu iterace nevrací cestu iterace, protože je obsažen v související entitě. Pokud chcete vrátit data v související entitě, přidejte příkaz $expand
:
/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration
Tady je příklad, který vrací informace přiřazené k pracovní položce s 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"
Jak vidíte, cesta iterace se ve výsledku rozbalí a vrátí se všechna data iterace. Pravděpodobně je to více dat, než chcete.
Pokud chcete vrátit méně dat, přidejte $select
také příkaz proti iteraci:
/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration($select=Name,IterationPath)
Pak vrátí následující 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"
}
}
]
}
Dotazování rozsahu dat
Následující příklad vrátí pracovní položky, jejichž změněné datum je větší než 1. ledna 2021.
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-01-01Z
Následující příklad vrátí pracovní položky, jejichž změněné datum nastane v týdnu od 26. do 30. dubna 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
Vnoření příkazů rozbalení
V OData můžete vnořit $expand
příkazy. Můžete například napsat předchozí příkaz dotazu, který zobrazí projekt, na kterém je iterace součástí:
/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($expand=Project)
Vrátí následující 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
}
}
}
]
}
Můžete také kombinovat $expand
a $select
příkazy. Předchozí dotaz můžete například změnit tak, aby vracel pouze název iterace a cestu iterace:
/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($select=IterationId,IterationPath;$expand=Project)
Vrátí následující 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
}
}
}
]
}
Všimněte si, že výsledek zde zobrazuje pouze IterationId a IterationPath a že Project je vnořený objekt ve výsledku JSON. Další klíčovou položkou k poznámce je samotná adresa URL. Při použití $select
příkazu a $expand
klauzule je nutné použít středník (;) před $expand
. Cokoli jiného způsobí chybu.
Seřadit výsledky, orderby
možnost
$orderby
Zadejte možnost řazení výsledků nebo určete posloupnost, ve které se vrátí výsledky. Můžete řadit vzestupně nebo sestupně pomocí klíčových slov asc
nebo desc
v uvedeném pořadí. Tady je několik příkladů.
Seřadit podle | Klauzule, která se má zahrnout |
---|---|
ID pracovní položky | /WorkItems?$orderby=WorkItemId |
ID pracovní položky sestupně | /WorkItems?$orderby=WorkItemId desc |
Typ a stav pracovní položky | /WorkItems?$orderby=WorkItemType,State |