Alapszintű lekérdezések definiálása az OData Analytics használatával
Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019
Az Azure DevOps Analytics használatával alapszintű és szűrt lekérdezéseket hozhat létre az érdekes adatok visszaadásához. Ezeket a lekérdezéseket közvetlenül a böngészőben vagy a Power BI-ban is futtathatja.
Ez a cikk az Azure Boards Analytics elemzési és metaadat-referenciáihoz készült OData-lekérdezésekben megadott információkat tartalmazza. A cikkben szereplő lekérdezések a munkakövetési entitáskészletek lekérésére összpontosítanak, azonban az alapelvek más entitáskészletek lekérdezésére is érvényesek.
Ebből a cikkből megtudhatja, hogyan definiálhat olyan lekérdezéseket, amelyek a következő adatokat adják vissza:
- Elemek száma (nincs más adat)
- Elemek és adatok száma
- Területekhez vagy iterációs útvonalakhoz definiált tulajdonságok
- Kijelölt oszlopok vagy mezők
- Szűrt adatok
- Identitás, Terület elérési útja és Iterációs útvonal mezőinek adatainak visszaadása
- Szűrés navigációs tulajdonság alapján
- Dátumtartomány lekérdezése
- Kibontási utasítások beágyazása
- Eredmények rendezése, rendezési lehetőség
Feljegyzés
Az Elemzési szolgáltatás automatikusan engedélyezve és támogatva van az összes Azure DevOps Services esetében az éles környezetben. Az Elemzési szolgáltatás OData-hírcsatornájának Power BI-integrációja és hozzáférése általánosan elérhető. Javasoljuk, hogy használja és küldjön nekünk visszajelzést.
A rendelkezésre álló adatok verziófüggők. A legújabb támogatott verzióv2.0
, és a legújabb előzetes verzió.v4.0-preview
További információ: OData API-verziószámozás.
Feljegyzés
Az Analytics szolgáltatás automatikusan települ és támogatott éles környezetben az Azure DevOps Server 2020 és újabb verziók összes új projektgyűjteményéhez. Az Elemzési szolgáltatás OData-hírcsatornájának Power BI-integrációja és hozzáférése általánosan elérhető. Javasoljuk, hogy használja és küldjön nekünk visszajelzést. Ha az Azure DevOps Server 2019-ről frissített, a frissítés során telepítheti az Analytics szolgáltatást.
A rendelkezésre álló adatok verziófüggők. A legújabb támogatott verzióv2.0
, és a legújabb előzetes verzió.v4.0-preview
További információ: OData API-verziószámozás.
Feljegyzés
Az Analytics szolgáltatás előzetes verzióban érhető el az Azure DevOps Server 2019-hez. Engedélyezheti vagy telepítheti egy projektgyűjteményhez. Az Elemzési szolgáltatás OData-hírcsatornájának Power BI-integrációja és elérése előzetes verzióban érhető el. Javasoljuk, hogy használja és küldjön nekünk visszajelzést.
A rendelkezésre álló adatok verziófüggők. A legújabb támogatott verzióv2.0
, és a legújabb előzetes verzió.v4.0-preview
További információ: OData API-verziószámozás.
Előfeltételek
- Hozzáférési szint: Alapszintű vagy magasabb hozzáféréssel rendelkező projekt tagjának kell lennie.
- Engedély: Alapértelmezés szerint a projekttagok jogosultak az Analytics lekérdezésére és nézetek létrehozására.
- A szolgáltatás- és szolgáltatás-engedélyezéssel, valamint az általános adatkövetési tevékenységekkel kapcsolatos egyéb előfeltételekről további információt az Analytics eléréséhez szükséges engedélyek és előfeltételek című témakörben talál.
Feljegyzés
Ebben a cikkben az OData-lekérdezés URL-címe az Azure DevOps Serviceshez van definiálva. Ha hasonló lekérdezést szeretne létrehozni egy helyszíni kiszolgálóhoz, tekintse meg az OData-lekérdezések létrehozása az Analyticshez című témakör útmutatását. Javasoljuk, hogy módosítsa a szervezet és a projekt számára biztosított lekérdezéseket, hogy megismerkedjen az OData lekérdezésével a böngészőben.
Elemek számának visszaadása (nincs más adat)
A szervezetben vagy projektben meghatározott elemek vagy entitások számának megismeréséhez adja meg $apply=aggregate($count as Count)
a lekérdezési lehetőséget. Az alábbi lekérdezések például a szervezethez definiált projektek, munkaelemek, területelérési utak és felhasználók számát adja vissza.
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)
Tipp.
Projektközi lekérdezések meghiúsulnak, ha a lekérdezést futtató felhasználó nem fér hozzá az összes projekthez. További információ a Project és a szervezeti hatókörű lekérdezések követelményeiről.
Projektszám
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(Count)"
value
0
@odata.id null
Count 28
Munkaelemek száma
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)"
value
0
@odata.id null
Count 1166
Területszám
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value
0
@odata.id null
Count 70
Felhasználók száma
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value
0
@odata.id null
Count 16
Elemek és adatok számának visszaadása
Ha az elemek számát és az elemek adatait szeretné visszaadni, adja meg a $count=true
lekérdezési lehetőséget. Az alábbi lekérdezések például a projekthez definiált munkaelemek, területelérési utak és felhasználók számát adja vissza a megadott tulajdonságok mellett. Érvényes tulajdonságokért tekintse meg az Azure DevOps Analytics metaadat-referenciáját az Azure Boards Analyticshez és a naptár dátumához, a projecthez és a felhasználói metaadatokhoz.
Tipp.
Ha nem adja meg a visszaadandó tulajdonságokat, az Analytics a megadott entitástípushoz definiált összes tulajdonságot visszaadja.
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
Területek vagy iterációk tulajdonságai
A terület elérési útjának vagy iterációs útvonalának vagy IterationSK
egyéb tulajdonságának megkereséséhez AreaSK
használja az alábbi lekérdezéseket.
Adott terület elérési útjának AreaSK-jának visszaadása
Az alábbi lekérdezés a AreaSK
Fabrikam Fibre\Service Delivery\Internet Area Path tulajdonsághoz definiált tulajdonság visszaadására szolgál. Az entitáskészlethez definiált egyéb tulajdonságok megadásához tekintse meg az Areas
Azure Boards Analytics, Területek metaadat-referenciáját.
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Areas?$filter=AreaPath eq 'Fabrikam Fiber\Service Delivery\Internet' &$select=AreaSK
A lekérdezés a következő adatokat adja vissza.
{
"@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Areas(AreaSK)",
"value": [
{
"AreaSK": "637dc203-0549-4415-9663-b6358ac27d21"
}
]
}
Adott iterációs útvonal IterationSK-jának visszaadása
Az alábbi lekérdezés a IterationSK
Fabrikam Fibre\Release 1\Sprint 3 iterációs útvonalhoz definiált tulajdonság visszaadását adja vissza. Az entitáskészlethez definiált egyéb tulajdonságok megadásához tekintse meg az Iterations
Azure Boards Analytics, Iterációk metaadat-referenciáját.
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Iterations?$filter=IterationPath eq 'Fabrikam Fiber\Release 1\Sprint 3' &$select=IterationSK
A lekérdezés a következő adatokat adja vissza.
{
"@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Iterations(IterationSK)",
"value": [
{
"IterationSK": "862e961a-ac7a-4fcc-9ebc-8afd0c12fed5"
}
]
}
Adott tulajdonságokat vagy mezőket ad vissza
Adott tulajdonságok vagy munkaelemmezők visszaadásához adjon hozzá egy $select
záradékot, amely megadja a tulajdonságneveket.
Ha például a munkaelem azonosítóját, a munkaelem típusát, címét és állapotát szeretné visszaadni, adja hozzá a következő záradékot a lekérdezéshez. Ez a záradék az elnevezett mezőknek megfelelő tulajdonságokat határozza meg.
Feljegyzés
A tulajdonságnevek nem tartalmaznak szóközöket. Szóközök hozzáadásakor a lekérdezés sikertelen lesz. Az OData-lekérdezések a térközre és a burkolatra is figyelmet igényelnek. Az egyéni mezőtulajdonságok címkézésének megismeréséhez tekintse meg az Azure Boards és az Egyéni tulajdonságok metaadat-referenciáját.
Itt adhatja meg, hogy az első három munkaelemet adja vissza.
https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$top=3
Az Analytics a következő adatokat adja vissza.
@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"
.
Adatok szűrése
Ha szűrni szeretne egy entitáskészletet a kiválasztott elemek visszaadására, adjon meg egy $filter
záradékot, amely meghatározza az elemeknek meg kell felelnie. Az utolsó lekérdezésre építve itt hozzáadunk egy szűrőzáradékot, amely csak a Folyamatban állapotban lévő Funkció munkaelemtípusokat adja vissza.
/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
Az Analytics a következő adatokat adja vissza.
@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"
Több szűrőzáradék megadása
Több szűrőzáradékot is használhat AND
és OR
adhat meg.
Az alábbi lekérdezés például azt határozza meg, hogy az Új, Véglegesített vagy Aktív állapotban lévő Felhasználói szövegegység, Hiba és Teendőlista munka (egyéni munkaelemtípus) típusú munkaelemeket adja vissza. Zárójel használatával szükség szerint csoportosíthatja a szűrési záradékokat.
Emellett különböző függvényeket is alkalmazhat, például contains
, startswith
endswith
és így tovább. Tekintse meg a támogatott OData-funkciókat és záradékokat, a támogatott függvényeket.
Identitás, Terület elérési útja és Iterációs útvonal mezőinek adatainak visszaadása
A kiválasztott tulajdonságok navigációs tulajdonságokhoz vannak társítva, és nem érhetők el közvetlenül az $select
utasítással. A fontos adatok visszaadásához egy utasítást $expand
kell használnia. Ezek a tulajdonságok gyakran több saját tulajdonsággal vannak társítva. Identitásmezőkkel például megadhatja, hogy a felhasználó nevét vagy a felhasználói e-mailt adja vissza.
Az alábbi táblázat példákat tartalmaz arra, hogyan bonthat ki több tulajdonságot.
Mezők beírása | Hivatkozott tulajdonság | Példák a belefoglalandó záradékokra |
---|---|---|
Dátum/idő | DateSK |
$expand=CreatedDate($select=Date) vagy$expand=CreatedDate($select=WeekStartingDate) |
Identitás | UserSK |
$expand=AssignedTo($select=UserName) vagy$expand=AssignedTo($select=UserEmail) |
Terület | AreaSK |
$expand=Area($select=AreaName) vagy$expand=Area($select=AreaPath) |
Iteráció | IterationSK |
$expand=Iteration($select=IterationName) vagy$expand=Iteration($select=IterationPath) vagy$expand=Iteration($select=StartDate) |
Project | ProjectSK |
$expand=Project($select=ProjectName) |
Csoport | TeamSK |
$expand=Teams($select=TeamName) |
Több kibontandó tulajdonság megadásához egyetlen kibontási záradékban adhatja meg őket egy vesszővel tagolt listában.
$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath)
Szűrés navigációs tulajdonság alapján
Ha egy navigációs tulajdonságot a szűrőfeltételek részeként ad meg, a kívánt formátumban kell megadnia.
Az alábbi záradék például a projekthez definiált 1. iteráció alapján határozza meg a munkaelemek szűrését.
/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'
Ebben a példában a navigációs tulajdonság neve látható, Iteration
és IterationPath
az iteráció teljes elérési útjának felel meg. Ha egy másik entitást szeretne szűrőként használni, helyezze a navigációs tulajdonságot, majd egy perjelet, majd a szűrni kívánt mező nevét.
És itt található a teljes OData-lekérdezés:
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'
Íme egy másik példa, amely a Fabrikam Fibre\Service Delivery\Voice Area Path alatti öt munkaelemet kéri vissza.
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"
Tipp.
A navigációs tulajdonságot nem használhatja közvetlenül egy $select
utasításban. Ehelyett a következőt kell használnia $expand
:
Az iterációs útvonal előző szűrési példája nem adja vissza az iterációs útvonalat, mert egy kapcsolódó entitásban található. Ha adatokat szeretne visszaadni egy kapcsolódó entitásban, adjon hozzá egy utasítást $expand
:
/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration
Íme egy példa, amely a 480-ás munkaelem-azonosítóhoz rendelt adatokat adja vissza.
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"
Amint látható, az iterációs útvonal ki van bontva az eredményben, és az összes iterációs adatot visszaadja. Valószínűleg több adat, mint amennyit szeretne.
Ha kevesebb adatot szeretne visszaadni, adjon hozzá egy utasítást $select
az iterációhoz is:
/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration($select=Name,IterationPath)
Ezután a következő adatokat adja vissza.
{
"@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"
}
}
]
}
Dátumtartomány lekérdezése
Az alábbi példa olyan munkaelemeket ad vissza, amelyek módosított dátuma nagyobb, mint 2021. január 1.
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-01-01Z
Az alábbi példa olyan munkaelemeket ad vissza, amelyek módosított dátuma 2021. április 26. és április 30. között történik.
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
Kibontási utasítások beágyazása
Az OData-ban utasításokat ágyazhat be $expand
. Megírhatja például az előző lekérdezési utasítást annak a projektnek a megjelenítéséhez, amely az iteráció része:
/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($expand=Project)
A következő JSON-t adja vissza:
{
"@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
}
}
}
]
}
Egyesíthet $expand
és $select
utasításokat is használhat. Módosíthatja például az előző lekérdezést, hogy csak az iterációs nevet és az iterációs útvonalat adja vissza:
/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($select=IterationId,IterationPath;$expand=Project)
A következő JSON-t adja vissza:
{
"@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
}
}
}
]
}
Figyelje meg, hogy az itt látható eredmény csak az IterationId és az IterationPath értéket jeleníti meg, a Project pedig egy beágyazott objektum a JSON-eredményben. Egy másik fontos elem, amelyet fel kell jegyezni, maga az URL-cím. Utasítás és $expand
záradék használatakor $select
kettőspontot kell használnia (;) a $expand
. Bármi más hibát fog eredményezni.
Találatok rendezése, orderby
beállítás
Adja meg az $orderby
eredmények rendezésének lehetőségét, vagy adja meg azt a sorrendet, amelyben az eredmények vissza lesznek adva. Növekvő vagy csökkenő sorrendben rendezheti a kulcsszavakat asc
vagy desc
azokat. Néhány példa látható
Rendezési szempont | Belefoglalandó záradék |
---|---|
Munkaelem azonosítója | /WorkItems?$orderby=WorkItemId |
Csökkenő munkaelem-azonosító | /WorkItems?$orderby=WorkItemId desc |
Munkaelem típusa és állapota | /WorkItems?$orderby=WorkItemType,State |