OData-lekérdezések létrehozása az Azure DevOps Analyticshez
Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019
Az Azure DevOps jelentéskészítő platformja, az Analytics mennyiségi kérdéseket tud megválaszolni a projektek múltjáról vagy jelenlegi állapotáról. Az Analytics támogatja a metaadatok és az entitáskészlet adatainak OData-lekérdezéseit. Ha egyszerű lekérdezéseket használ a webböngészőből, megismerkedhet az adatmodellel és a lekérdezési folyamattal.
Ebben a cikkben a következőket fogja elsajátítani:
- Analytics OData-lekérdezés létrehozása a felhőhöz vagy a helyszíni környezethez
- Az Analytics metaadatainak lekérdezése
- Az Analytics OData lekérdezése egy entitáskészlethez
- Mely lekérdezési beállítások támogatottak és az ajánlott sorrend
- Kiszolgálóoldali lapozás kényszerítésekor
Az Elemzést bármely támogatott webböngészőből lekérdezheti. Az Elemzés lekérdezéséhez használható egyéb eszközökért tekintse meg az Analytics lekérdezési eszközeit.
Feljegyzés
Az OData egy alkalmazásszintű protokoll az adatok RESTful (ahol REST=Representational State Transfer) felületeken keresztüli kezeléséhez, támogatja az adatmodellek leírását, valamint az adatok ezen modellek szerinti szerkesztését és lekérdezését. Az entitás adatmodellje (EDM) vagy metaadatai az Elemzésből elérhető információkat ismertetik, beleértve az entitásokat, az entitástípusokat, a tulajdonságokat, a kapcsolatokat és az enumerálásokat, a jelentések készítéséhez használt adatokat. Az OData áttekintését az OData üdvözli.
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.
A metaadatok lekérdezéséhez használt URL-összetevők
Az Analytics a szolgáltatás gyökér URL-címéhez való hozzáfűzéssel $metadata
létrehozott metaadat-URL-címen teszi elérhetővé az entitásmodellt. Az Analytics szolgáltatásgyökereket biztosít egy projekthez vagy egy teljes szervezethez az Azure DevOpsban.
A metaadatok lekérdezésével megkeresheti az alábbi adatelemek bármelyikét.
- Entitástípusok és entitáskészletek
- Tulajdonságok és navigációs tulajdonságok
- Helyettesítő kulcsok
- Számbavételi listák
- EntitySet
- Tárolók
- Szűrőfüggvények (
Org.OData.Capabilities.V1.FilterFunctions
) - Támogatott összesítések (
Org.OData.Aggregation.V1.ApplySupported
) - Batch-támogatás (
Org.OData.Capabilities.V1.BatchSupportType
)
A használt URL-cím attól függ, hogy az Azure DevOps Services (felhő) vagy egy helyszíni Azure DevOps Server adatait kérdezi le.
Ha le szeretné kérdezni a felhőben üzemeltetett szervezet vagy projekt metaadatait, írja be az URL-szintaxist a webböngészőben alább látható módon. Cserélje le {OrganizationName}
a {ProjectName}
szervezet nevét és a lekérdezni kívánt projekt nevét. A szervezet összes metaadatának visszaadásához ne adja meg a projekt nevét.
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/version/$metadata
\______________________________/\______________________________/\______________/\_________/
| | | |
Analytics service root URL Organization/Project OData version return metadata
Feljegyzés
Az Analytics OData legújabb verziója a 4.0-s verziójú előzetes verzió. Ezt a verziót az üzemeltetett szolgáltatással kapcsolatos összes lekérdezéshez használhatja. Az Analytics-verziókról és a rendelkezésre álló adatokról az Analytics adatmodellje nyújt további információt.
Íme egy példa az Azure DevOps Servicesben üzemeltetett Fabrikam-szervezetre .
https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata
A metaadat-válasz értelmezése
Az Analytics az adatmodell XML-fájlját adja vissza. A böngésző keresési függvényével megkeresheti az adott entitásra vonatkozó információkat.
Tipp.
A használt böngészőtől függően előfordulhat, hogy ez a fájl olvasható módon formázható vagy nem. Ha nincs formázva, egy webböngészőben kereshet ingyenes online XML-formázót.
Az Analytics metaadataiban Microsoft.VisualStudio.Services.Analytics.Model
definiált két fő séma az entitástípusok és az enumerált típusok és azok tagjai, valamint a Default
séma, amely meghatározza az entitástárolókat és az entitáskészleteket, valamint a támogatott OData-szűrő-, transzformáció- és egyéni összesítési függvényeket. További információ: Analytics OData metaadatok.
<?xml version="1.0" encoding="UTF-8"?>
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
<edmx:DataServices>
<Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Microsoft.VisualStudio.Services.Analytics.Model">
<EntityType Name="Entity Name"/>
</Schema>
<Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Default">
<EntityContainer Name="Container"/>
</Schema>
</edmx:DataServices>
</edmx:Edmx>
Kapcsolódó entitások és navigációs tulajdonságok
Minden entitástípus tulajdonságokhoz és navigációs tulajdonságokhoz van társítva. Az entitáskészletek lekérdezéseit mindkét tulajdonságtípussal szűrheti. Ezek a metaadatok EntityType
között az a Property
vagy NavigationalProperty
. A kapcsolódó entitásokkal további szűrőket adhat meg, például iterációs útvonalakat, területelérési útvonalakat vagy Teamst.
Az alábbi kódrészlet részleges áttekintést nyújt az entitás metaadatairól WorkItem
. A tulajdonságok egy munkaelemmezőnek, valamint az Analytics által rögzített konkrét adatoknak felelnek meg, például LeadTimeDays
és CycleTimeDays
. A navigációs tulajdonságok más entitáskészleteknek vagy az entitástípushoz rögzített adott Analytics-adatoknak felelnek meg, például Revisions
, Links
, Children
és Parent
.
<Key>
<PropertyRef Name="WorkItemId"/>
</Key>
<Property Name="WorkItemId" Type="Edm.Int32" Nullable="false">
<Annotation Term="Ref.ReferenceName" String="System.Id"/>
<Annotation Term="Display.DisplayName" String="Work Item Id"/>
</Property>
<Property Name="InProgressDate" Type="Edm.DateTimeOffset">
<Annotation Term="Display.DisplayName" String="InProgress Date"/>
</Property>
<Property Name="CompletedDate" Type="Edm.DateTimeOffset">
<Annotation Term="Display.DisplayName" String="Completed Date"/>
</Property>
<Property Name="LeadTimeDays" Type="Edm.Double">
<Annotation Term="Display.DisplayName" String="Lead Time Days"/>
</Property>
<Property Name="CycleTimeDays" Type="Edm.Double">
<Annotation Term="Display.DisplayName" String="Cycle Time Days"/>
</Property>
<Property Name="InProgressDateSK" Type="Edm.Int32"/>
<Property Name="CompletedDateSK" Type="Edm.Int32"/>
<Property Name="AnalyticsUpdatedDate" Type="Edm.DateTimeOffset"/>
<Property Name="ProjectSK" Type="Edm.Guid" Nullable="false"/>
<Property Name="WorkItemRevisionSK" Type="Edm.Int32" Nullable="false"/>
...
<NavigationProperty Name="BoardLocations" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.BoardLocation)"/>
<NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>
<NavigationProperty Name="InProgressOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="InProgressDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="CompletedOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="CompletedDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="Revisions" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemRevision)"/>
<NavigationProperty Name="Links" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemLink)"/>
<NavigationProperty Name="Children" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Parent" Type="Microsoft.VisualStudio.Services.Analytics.Model.WorkItem">
<ReferentialConstraint Property="ParentWorkItemId" ReferencedProperty="WorkItemId"/>
</NavigationProperty>
<NavigationProperty Name="Processes" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Process)"/>
<NavigationProperty Name="Descendants" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project" Nullable="false">
<ReferentialConstraint Property="ProjectSK" ReferencedProperty="ProjectSK"/>
<Annotation Term="Display.DisplayName" String="Project"/>
...
URL-összetevők az entitások lekérdezéséhez
Az Analytics-adatok lekérdezéséhez és jelentések készítéséhez általában egy entitáskészletet kell lekérdeznie. A támogatott entitások áttekintéséhez tekintse meg az Analytics OData metaadatait.
A rendszer az alábbi URL-címet használja egy adott EntitySet
, például WorkItems
, WorkItemSnapshot
és PipelineRuns
.
https://analytics.dev.azure.com/OrganizationName/ProjectName/_odata/version/EntityType?{Query-options}
\______________________________/\__________________________/ \____________/\_________/\_____________/
| | | | |
Analytics service root URL Organization/Project OData version Entity Query parts
Íme egy példa a Fabrikam-szervezetre , amely a Fabrikam Fiber-projekthez definiált munkaelemek számát adja vissza.
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?%20$apply=aggregate($count%20as%20Count)
A példa 1399 munkaelemet ad vissza.
{
"@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(Count)",
"value": [
{
"@odata.id": null,
"Count": 1399
}
]
}
Feljegyzés
Ha nem tartalmaz egy vagy $apply
több $select
záradékot, figyelmeztetést fog kapni, például "VS403507: The specified query does not include a $select or $apply clause which is recommended for all queries. Details on recommended query patterns are available here: https://go.microsoft.com/fwlink/?linkid=861060."
ez egyenértékű egy választó utasítás végrehajtásával az entitáskészleten, és visszaad mindent, minden oszlopot és minden sort. Ha sok rekord van, az több másodpercet is igénybe vehet. Ha több mint 10 000 munkaeleme van, a kiszolgálóalapú lapozás kényszerítve lesz.
A használati korlátok elkerülése érdekében mindig adjon meg egy vagy $apply
több záradékot$select
.
Az entitás metaadatainak tulajdonságával és kapcsolatával kapcsolatos információkért tekintse meg az alábbi cikkeket:
- Naptárdátum, projekt és felhasználó metaadatainak referenciája
- Az Azure Boards metaadat-referenciája
- Az Azure Pipelines metaadat-referenciája
- Metaadatok referenciája teszttervekhez
Példa: Adott entitáskészlet lekérdezése
Ha egy adott entitáskészletet szeretne lekérdezni, például WorkItems
, Areas
vagy Projects
adja hozzá az entitáskészlet nevét: /WorkItems
, /Areas
vagy /Projects
. Az entitáskészletek teljes listáját az Analytics adatmodellje tartalmazza.
Lekérheti például a szervezetéhez definiált projektek listáját a tulajdonság lekérdezésével /Projects
ProjectName
és kiválasztásával. A fabrikam szervezet esetében az URL-cím az alábbi módon jelenik meg.
https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/Projects?$select=ProjectName
Az Analytics visszaadja a fabrikam szervezethez definiált projektek projektneveit.
{
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(ProjectName)",
"value": [
{
"ProjectName": "Basic Fabrikam"
},
{
"ProjectName": "Fabrikam Fiber"
},
{
"ProjectName": "MyFirstProject"
},
{
"ProjectName": "Fabrikam Test"
},
{
"ProjectName": "MyPublicProject"
}
]
}
Lekérdezés beállításai
A lekérdezési beállítás egy erőforrásra alkalmazott lekérdezési sztringparaméterek halmaza, amelyek segítenek szabályozni az erőforrás url-címében visszaadott adatok mennyiségét.
A lekérdezési beállításokat az alábbi táblázatban felsorolt sorrendben kell megadni.
Lekérdezési lehetőség | Jegyzetek |
---|---|
$apply |
A lekérdezésekre alkalmazható átalakítások halmaza, például: filter , , , aggregate , compute expand, groupby concat Példák : A munkakövetési adatok összesítése az Analytics használatával. |
$compute |
Támogatott OData-függvény, amelyet megadhatja egy ,,$filter vagy $orderby kifejezésben $select használható számított tulajdonságok definiálásához. |
$filter |
A visszaadott erőforrások listájának szűrésére használható. A megadott $filter kifejezés kiértékelése a gyűjtemény minden erőforrására vonatkozik, és a válasz csak azokat az elemeket tartalmazza, amelyekben a kifejezés igaz értéket ad. A válaszból kihagyja azokat az erőforrásokat, amelyek esetében a kifejezés hamis vagy null értékű, vagy amelyek hivatkozási tulajdonságai engedélyek miatt nem érhetők el.Példák : A munkakövetési adatok lekérdezése az Analytics használatával. |
$orderby |
A rekordok visszaadási sorrendjének megadására használható. Példák : A munkakövetési adatok lekérdezése az Analytics használatával. |
$top /$skip |
A visszaadott rekordok számának korlátozására használható. Ilyenek például a Project és a szervezet hatókörű lekérdezései. |
$select /$expand |
A jelentés létrehozásához szükséges oszlopok megadására használható $select . Más lekérdezési beállítások beágyazására használható $expand . Mindegyik expandItem kiértékelése a kibontott navigációs vagy streamtulajdonságot tartalmazó entitáshoz képest történik.A lekérdezési lehetőségek pontosvesszővel tagolt listája zárójelben a navigációs tulajdonság nevére. Az engedélyezett rendszer-lekérdezési lehetőségek a következők $filter : , $select , $orderby , $skip , $top , $count $search , és $expand .Példák : A munkakövetési adatok lekérdezése az Analytics használatával. |
$skiptoken |
Adott számú rekord kihagyására használható. |
$count vagy $count=true |
Adja meg $count , hogy csak a rekordok számát adja vissza. Adja meg $count=true a rekord és a lekérdezett adatok számát is. Példák : A munkakövetési adatok összesítése az Analytics használatával. |
Tipp.
Kerülje a keverést $apply
és $filter
a záradékokat egyetlen lekérdezésben. A lekérdezés szűréséhez két lehetősége van: (1) használjon záradékot $filter
, vagy (2) használjon kombinációs záradékot $apply=filter()
. Ezek a lehetőségek önmagukban is nagyszerűen működnek, de az egyesítések váratlan eredményekhez vezethetnek.
Kiszolgálóoldali lapozás kényszerítése
Az elemzés arra kényszeríti a lapozást, ha a lekérdezés eredménye meghaladja az 10000 rekordot. Ebben az esetben lekérheti az adatok első oldalát, és a következő oldalhoz követendő hivatkozást fog kapni. A kapcsolat (@odata.nextLink
) a JSON-kimenet végén található. Úgy fog kinézni, mint egy eredeti lekérdezés, amelyet vagy .$skip
$skiptoken
Például:
{
"@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
"value":[
// 10000 values here
],
"@odata.nextLink":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$skiptoken=10000"
}
Feljegyzés
Amikor adatokat kér be az ügyféleszközökre, például a Power BI Desktopba vagy az Excelbe, az eszközök automatikusan követik a következő hivatkozást, és betöltik az összes szükséges rekordot.