OData-lekérdezések létrehozása az Azure DevOps Analyticshez

  • Cikk

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

  • Az Analytics-adatok megtekintéséhez és a szolgáltatás lekérdezéséhez egy alapszintű hozzáféréssel rendelkező vagy annál nagyobb hozzáférésű projekt tagjának kell lennie. Alapértelmezés szerint minden projekttag rendelkezik az Analytics lekérdezéséhez és az Analytics-nézetek meghatározásához szükséges engedélyekkel.
  • 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 az Analytics eléréséhez szükséges engedélyek és előfeltételek című témakörben olvashat.

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.Modeldefiniá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>

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:

Példa: Adott entitáskészlet lekérdezése

Ha egy adott entitáskészletet szeretne lekérdezni, például WorkItems, Areasvagy Projectsadja hozzá az entitáskészlet nevét: /WorkItems, /Areasvagy /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 /ProjectsProjectName é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, groupby, , aggregate, computeexpand,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 $selecthaszná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=truea 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.

Következő lépések

Alapszintű lekérdezések létrehozása az OData Analytics használatával