OData-query's maken voor analyse in Azure DevOps
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
Analyse, het rapportageplatform voor Azure DevOps, kan kwantitatieve vragen beantwoorden over de huidige of eerdere status van uw projecten. Analytics ondersteunt OData-query's van de metagegevens en entiteitssetgegevens. Door eenvoudige query's uit te oefenen vanuit uw webbrowser, kunt u vertrouwd raken met het gegevensmodel en het queryproces.
In dit artikel leert u het volgende:
- Een OData-query voor Analytics maken voor de cloud of on-premises
- Query's uitvoeren op metagegevens van Analytics
- OData van Analytics opvragen voor een entiteitsset
- Welke queryopties worden ondersteund en de aanbevolen reeks
- Wanneer paging aan de serverzijde wordt afgedwongen
U kunt query's uitvoeren op Analytics vanuit elke ondersteunde webbrowser. Zie Analytics-queryhulpprogramma's voor andere hulpprogramma's die u kunt gebruiken voor het uitvoeren van query's.
Notitie
OData, een protocol op toepassingsniveau voor interactie met gegevens via RESTful (waarbij REST=Representational State Transfer)-interfaces worden gebruikt, ondersteunt de beschrijving van gegevensmodellen en het bewerken en opvragen van gegevens op basis van die modellen. In het EDM (Entity Data Model) of metagegevens worden de gegevens beschreven die beschikbaar zijn in Analytics, waaronder de entiteiten, entiteitstypen, eigenschappen, relaties en opsommingen die u gebruikt om een query uit te voeren op de gegevens om rapporten te maken. Zie Welkom bij OData voor een overzicht van OData.
Vereisten
- Toegang: Wees lid van een project met ten minste basistoegang .
- Machtigingen: projectleden zijn standaard gemachtigd om query's uit te voeren op Analytics en weergaven te maken.
- Zie Machtigingen en vereisten voor toegang tot Analyse voor meer informatie over andere vereisten met betrekking tot het inschakelen van services en functies en algemene activiteiten voor het bijhouden van gegevens.
URL-onderdelen om een query uit te voeren op de metagegevens
Analyse maakt het entiteitsmodel beschikbaar op de metagegevens-URL, gevormd door toe te $metadata voegen aan de basis-URL van de service. Analytics biedt serviceroots voor een project of een hele organisatie in Azure DevOps.
U kunt een van de volgende gegevenselementen opzoeken door een query uit te voeren op de metagegevens.
- Entiteitstypen en entiteitssets
- Eigenschappen en navigatie-eigenschappen
- Surrogaatsleutels
- Geïnventariseerd lijsten
- EntitySet
- Containers
- Filterfuncties (
Org.OData.Capabilities.V1.FilterFunctions) - Ondersteunde aggregaties (
Org.OData.Aggregation.V1.ApplySupported) - Batch-ondersteuning (
Org.OData.Capabilities.V1.BatchSupportType)
De URL die u gebruikt, is afhankelijk van of u gegevens opvraagt voor Azure DevOps Services (cloud) of een on-premises Azure DevOps-server.
Als u een query wilt uitvoeren op de metagegevens voor een organisatie of project die in de cloud worden gehost, voert u de URL-syntaxis in zoals hieronder wordt weergegeven in een webbrowser. Vervang en {ProjectName} door {OrganizationName} de naam van uw organisatie en de naam van het project waarop u een query wilt uitvoeren. Als u alle metagegevens voor de organisatie wilt retourneren, geeft u de projectnaam niet op.
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/version/$metadata
\______________________________/\______________________________/\______________/\_________/
| | | |
Analytics service root URL Organization/Project OData version return metadata
Notitie
De nieuwste versie van Analytics OData is v4.0-preview. U kunt deze versie gebruiken voor alle query's voor de gehoste service. Zie Gegevensmodel voor Analyse voor Analyse voor meer informatie over analytics-versies en beschikbare gegevens.
Hier volgt een voorbeeld voor de fabrikam-organisatie die wordt gehost in Azure DevOps Services.
https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata
Het antwoord op metagegevens interpreteren
Analytics retourneert een XML-bestand van het gegevensmodel. Gebruik de zoekfunctie van uw browser om informatie te vinden die specifiek is voor de entiteit van belang.
Tip
Afhankelijk van de browser die u gebruikt, kan dit bestand al dan niet worden opgemaakt op een leesbare manier. Als deze niet is opgemaakt, kunt u een gratis online XML-indeling vinden via een zoekopdracht in een webbrowser.
De twee belangrijkste schema's die zijn gedefinieerd in de metagegevens van Analytics zijn Microsoft.VisualStudio.Services.Analytics.Model, die de entiteitstypen en geïnventareerde typen en hun leden definiëren, en het Default schema, waarmee de entiteitscontainers en entiteitssets en ondersteunde OData-filter-, transformatie- en aangepaste aggregatiefuncties worden gedefinieerd. Zie OData-metagegevens van Analytics voor meer informatie.
<?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>
Gerelateerde entiteiten en navigatie-eigenschappen
Alle entiteitstypen zijn gekoppeld aan eigenschappen en navigatie-eigenschappen. U kunt uw query's van entiteitssets filteren met behulp van beide typen eigenschappen. Deze worden vermeld in de metagegevens onder de EntityType as a Property of NavigationalProperty. U gebruikt gerelateerde entiteiten om extra filters op te geven, zoals iteratiepaden, gebiedspaden of Teams.
Het volgende codefragment biedt een gedeeltelijke weergave van de metagegevens voor de WorkItem entiteit. Eigenschappen komen overeen met een werkitemveld en specifieke gegevens die zijn vastgelegd door Analytics, zoals LeadTimeDays en CycleTimeDays. Navigatie-eigenschappen komen overeen met andere entiteitssets of specifieke analysegegevens die zijn vastgelegd voor het entiteitstype, zoals Revisions, Linksen ChildrenParent.
<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-onderdelen voor het uitvoeren van query's op entiteiten
Als u analysegegevens wilt opvragen en rapporten wilt maken, voert u doorgaans een query uit op een entiteitsset. Zie OData-metagegevens van Analytics voor een overzicht van ondersteunde entiteiten.
De volgende URL wordt gebruikt om een query uit te voeren op een specifieke EntitySet, zoals WorkItems, WorkItemSnapshoten PipelineRuns.
https://analytics.dev.azure.com/OrganizationName/ProjectName/_odata/version/EntityType?{Query-options}
\______________________________/\__________________________/ \____________/\_________/\_____________/
| | | | |
Analytics service root URL Organization/Project OData version Entity Query parts
Hier volgt een voorbeeld voor de fabrikam-organisatie die het aantal werkitems retourneert dat is gedefinieerd voor het Fabrikam Fiber-project.
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?%20$apply=aggregate($count%20as%20Count)
In het voorbeeld worden 1399 werkitems geretourneerd.
{
"@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(Count)",
"value": [
{
"@odata.id": null,
"Count": 1399
}
]
}
Notitie
Als u geen of $apply component opneemt$select, ontvangt u een waarschuwing, zoals "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." het equivalent van het uitvoeren van een select-instructie voor de entiteitsset en het retourneren van alles, alle kolommen en alle rijen. Als u een groot aantal records hebt, kan het enkele seconden duren. Als u meer dan 10.000 werkitems hebt, wordt servergestuurde paging afgedwongen.
Als u wilt voorkomen dat er gebruikslimieten worden bereikt, moet u altijd een $select of $apply meer componenten opnemen.
Zie de volgende artikelen voor informatie over eigenschap en relatie van entiteitsmetagegevens:
- Naslaginformatie over kalenderdatum, project en gebruikersmetagegevens
- Naslaginformatie over metagegevens voor Azure Boards
- Naslaginformatie over metagegevens voor Azure Pipelines
- Naslaginformatie over metagegevens voor testplannen
Voorbeeld: Een query uitvoeren op een specifieke entiteitsset
Als u een query wilt uitvoeren op een specifieke entiteitsset, zoals WorkItems, Areasof Projects, voegt u de naam van de entiteitsset toe: /WorkItems, /Areasof /Projects. Zie Gegevensmodel voor Analyse voor een volledige lijst met entiteitssets.
U kunt bijvoorbeeld een lijst ophalen met projecten die zijn gedefinieerd voor uw organisatie door een query uit te voeren /Projects en te selecteren om de ProjectName eigenschap te retourneren. Voor de fabrikam-organisatie is de URL zoals hieronder wordt weergegeven.
https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/Projects?$select=ProjectName
Analytics retourneert de projectnamen van deze projecten die zijn gedefinieerd voor de fabrikam-organisatie .
{
@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"
}
]
}
Queryopties
Een queryoptie is een set queryreeksparameters die worden toegepast op een resource waarmee u de hoeveelheid gegevens kunt bepalen die worden geretourneerd voor de resource in de URL.
Queryopties moeten worden opgegeven in de volgorde die wordt vermeld in de volgende tabel.
| Queryoptie | Opmerkingen |
|---|---|
$apply |
Set transformaties die u op een query kunt toepassen, zoals: filter, groupby, , computeexpand, aggregate concatZie Gegevens voor het bijhouden van werk aggregeren met behulp van Analytics voor voorbeelden. |
$compute |
Een ondersteunde OData-functie die u kunt opgeven om berekende eigenschappen te definiëren die kunnen worden gebruikt in een $selectof $orderby$filtermeer expressies. |
$filter |
Hiermee filtert u de lijst met resources die worden geretourneerd. De opgegeven $filter expressie wordt geëvalueerd voor elke resource in de verzameling en alleen items waarin de expressie waar wordt geëvalueerd, worden opgenomen in het antwoord. Resources waarvan de expressie onwaar of null is, of welke verwijzingseigenschappen niet beschikbaar zijn vanwege machtigingen, worden weggelaten uit het antwoord.Zie Gegevens voor het bijhouden van werk opvragen met behulp van Analytics voor voorbeelden. |
$orderby |
Gebruik dit om de volgorde op te geven waarin records moeten worden geretourneerd. Zie Gegevens voor het bijhouden van werk opvragen met behulp van Analytics voor voorbeelden. |
$top/$skip |
Gebruik dit om het aantal geretourneerde records te beperken. Zie project- en organisatiequery's voor voorbeelden. |
$select/$expand |
Gebruik $select dit om de kolommen op te geven die u nodig hebt om uw rapport te maken. Gebruik $expand dit om andere queryopties te nesten. Elke expandItem entiteit wordt geëvalueerd ten opzichte van de entiteit die de navigatie- of stroomeigenschap bevat die wordt uitgebreid.Door puntkomma's gescheiden lijst met queryopties, tussen haakjes, naar de naam van de navigatie-eigenschap. Toegestane opties voor systeemquery's zijn $filter, , , $orderby$skip, $top, , $count, en .$expand$search$selectZie Gegevens voor het bijhouden van werk opvragen met behulp van Analytics voor voorbeelden. |
$skiptoken |
Gebruik dit om een opgegeven aantal records over te slaan. |
$count of $count=true |
Voer in $count om alleen het aantal records te retourneren. Voer in $count=trueom zowel een telling van de record als de opgevraagde gegevens te retourneren. Zie Gegevens voor het bijhouden van werk aggregeren met behulp van Analytics voor voorbeelden. |
Tip
Vermijd menging $apply en $filter componenten in één query. Als u uw query wilt filteren, hebt u twee opties: (1) een component gebruiken $filter of (2) een $apply=filter() combinatiecomponent gebruiken. Elk van deze opties werkt zelfstandig, maar het combineren ervan kan leiden tot onverwachte resultaten.
Paging aan serverzijde afdwingen
Analyse dwingt paging af wanneer queryresultaten groter zijn dan 10000 records. In dat geval krijgt u de eerste pagina met gegevens en een koppeling die u moet volgen om de volgende pagina op te halen. Koppeling (@odata.nextLink) vindt u aan het einde van de JSON-uitvoer. Deze ziet eruit als een oorspronkelijke query, gevolgd door $skip of $skiptoken. Bijvoorbeeld:
{
"@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"
}
Notitie
Wanneer u gegevens ophaalt in clienthulpprogramma's zoals Power BI Desktop of Excel, worden automatisch de volgende koppeling gevolgd en worden alle vereiste records geladen.