Skapa OData-frågor för analys i Azure DevOps

  • Artikel

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019

Analytics, rapporteringsplattformen för Azure DevOps, kan besvara kvantitativa frågor om tidigare eller nuvarande tillstånd för dina projekt. Analytics stöder OData-frågor för dess metadata och entitetsuppsättningsdata. Genom att använda enkla frågor från webbläsaren kan du bekanta dig med datamodellen och frågeprocessen.

I den här artikeln får du lära dig följande:

  • Skapa en Analytics OData-fråga för molnet eller lokalt
  • Så här frågar du efter analysmetadata
  • Så här frågar du Analytics OData efter en entitetsuppsättning
  • Vilka frågealternativ som stöds och den rekommenderade sekvensen
  • När sidindelning på serversidan tillämpas

Du kan köra frågor mot Analytics från valfri webbläsare som stöds. Andra verktyg som du kan använda för att köra frågor mot Analytics finns i Analysfrågeverktyg.

Kommentar

OData, ett protokoll på programnivå för att interagera med data via RESTful-gränssnitt (där REST=Representational State Transfer) har stöd för beskrivningen av datamodeller samt redigering och frågekörning av data enligt dessa modeller. Entitetsdatamodellen (EDM) eller metadata beskriver den information som är tillgänglig från Analys, inklusive entiteter, entitetstyper, egenskaper, relationer och uppräkningar som du använder för att köra frågor mot data för att skapa rapporter. En översikt över OData finns i Välkommen till OData.

Förutsättningar

  • Om du vill visa analysdata och fråga tjänsten måste du vara medlem i ett projekt med grundläggande åtkomst eller större. Som standard beviljas alla projektmedlemmar behörighet att köra frågor mot Analytics och definiera analysvyer.
  • Mer information om andra förutsättningar för tjänst- och funktionsaktivering och allmänna dataspårningsaktiviteter finns i Behörigheter och krav för åtkomst till analys.

URL-komponenter för att köra frågor mot metadata

Analytics exponerar entitetsmodellen vid metadata-URL:en, som bildas genom att lägga $metadata till tjänstens rot-URL. Analytics tillhandahåller tjänströtter för ett projekt eller en hel organisation i Azure DevOps.

Du kan söka efter något av följande dataelement genom att köra frågor mot metadata.

  • Entitetstyper och entitetsuppsättningar
  • Egenskaper och navigeringsegenskaper
  • Surrogatnycklar
  • Uppräknade listor
  • EntitySet
  • Containers
  • Filterfunktioner (Org.OData.Capabilities.V1.FilterFunctions)
  • Sammansättningar som stöds (Org.OData.Aggregation.V1.ApplySupported)
  • Batch-stöd (Org.OData.Capabilities.V1.BatchSupportType)

Vilken URL du använder beror på om du frågar efter data för Azure DevOps Services (molnet) eller en lokal Azure DevOps Server.

Om du vill köra frågor mot metadata för en organisation eller ett projekt som finns i molnet anger du URL-syntaxen enligt nedan i en webbläsare. Ersätt {OrganizationName} och {ProjectName} med organisationsnamnet och namnet på det projekt som du vill fråga efter. Om du vill returnera alla metadata för organisationen anger du inte projektnamnet.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/version/$metadata 
\______________________________/\______________________________/\______________/\_________/
               |                                 |                       |           |
    Analytics service root URL         Organization/Project        OData version  return metadata

Kommentar

Den senaste Analytics OData-versionen är v4.0-preview. Du kan använda den här versionen för alla frågor mot den värdbaserade tjänsten. Mer information om analysversioner och tillgängliga data finns i Datamodell för analys.

Här är ett exempel för fabrikam-organisationen som finns i Azure DevOps Services.

https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata

Tolka metadatasvaret

Analytics returnerar en XML-fil för datamodellen. Använd webbläsarens sökfunktion för att hitta information som är specifik för entiteten av intresse.

Dricks

Beroende på vilken webbläsare du använder kanske den här filen formateras på ett läsbart sätt. Om den inte är formaterad kan du hitta en kostnadsfri XML-formaterare online via en webbläsarsökning.

De två huvudscheman som definieras i Analysmetadata är Microsoft.VisualStudio.Services.Analytics.Model, som definierar entitetstyper och uppräknade typer och deras medlemmar, och Default schemat, som definierar entitetscontainrar och entitetsuppsättningar och OData-filter-, transformerings- och anpassade aggregeringsfunktioner som stöds. Mer information finns i Analys-OData-metadata.

<?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>

Alla entitetstyper är associerade med egenskaper och navigeringsegenskaper. Du kan filtrera dina frågor för entitetsuppsättningar med båda dessa typer av egenskaper. Dessa visas i metadata under EntityType som en Property eller NavigationalProperty. Du använder relaterade entiteter för att ange ytterligare filter, till exempel iterationssökvägar, områdessökvägar eller Teams.

Följande kodfragment ger en partiell vy över metadata för entiteten WorkItem . Egenskaper motsvarar ett arbetsobjektfält samt specifika data som samlas in av Analys, till exempel LeadTimeDays och CycleTimeDays. Navigeringsegenskaper motsvarar andra entitetsuppsättningar eller specifika Analysdata som samlas in för entitetstypen, till exempel Revisions, Links, Childrenoch 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-komponenter för att fråga entiteter

Om du vill köra frågor mot Analysdata och skapa rapporter frågar du vanligtvis en entitetsuppsättning. En översikt över entiteter som stöds finns i Analys-OData-metadata.

Följande URL används för att fråga en specifik EntitySet, till exempel WorkItems, WorkItemSnapshotoch PipelineRuns.

https://analytics.dev.azure.com/OrganizationName/ProjectName/_odata/version/EntityType?{Query-options}
\______________________________/\__________________________/ \____________/\_________/\_____________/
               |                             |                    |               |          |
    Analytics service root URL     Organization/Project      OData version    Entity   Query parts

Här är ett exempel för fabrikam-organisationen som returnerar antalet arbetsobjekt som definierats för Fabrikam Fiber-projektet.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?%20$apply=aggregate($count%20as%20Count)

Exemplet returnerar 1399 arbetsobjekt.

{
"@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(Count)",
"value": [
   {
   "@odata.id": null,
   "Count": 1399
   }
 ]
}

Kommentar

Om du inte inkluderar en $select eller $apply -sats får du en varning, till exempel "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." Det motsvarar att utföra en select-instruktion på entitetsuppsättningen och returnera allt, alla kolumner och alla rader. Om du har ett stort antal poster kan det ta flera sekunder. Om du har fler än 10 000 arbetsobjekt tillämpas serverdriven växling.

Om du vill undvika att stöta på användningsgränser måste du alltid inkludera en $select eller $apply -sats.

Information om entitetsmetadataegenskap och relationsinformation finns i följande artiklar:

Exempel: Fråga efter en specifik entitetsuppsättning

Om du vill fråga en specifik entitetsuppsättning, till exempel WorkItems, Areaseller Projects, lägger du till namnet på entitetsuppsättningen: /WorkItems, /Areaseller /Projects. En fullständig lista över entitetsuppsättningar finns i Datamodell för analys.

Du kan till exempel hämta en lista över projekt som definierats för din organisation genom att /Projects fråga och välja att returnera ProjectName egenskapen. För fabrikam-organisationen visas URL:en enligt nedan.

  https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/Projects?$select=ProjectName

Analytics returnerar projektnamnen för de projekt som definierats för fabrikam-organisationen .

{
@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"
   }
 ]
}

Frågealternativ

Ett frågealternativ är en uppsättning frågesträngsparametrar som tillämpas på en resurs som kan hjälpa dig att styra mängden data som returneras för resursen i URL:en.

Frågealternativ bör anges i den ordning som anges i följande tabell.

Frågealternativ Kommentar
$apply Uppsättning transformeringar som du kan använda för en fråga, till exempel: filter, groupby, aggregate, , computeexpand,concat
Exempel finns i Sammanställa arbetsspårningsdata med analytics.
$compute En OData-funktion som stöds som du kan ange för att definiera beräknade egenskaper som kan användas i ett $select,$filtereller $orderby -uttryck.
$filter Använd för att filtrera listan över resurser som returneras. Uttrycket som anges med $filter utvärderas för varje resurs i samlingen och endast objekt där uttrycket utvärderas till sant ingår i svaret. Resurser för vilka uttrycket utvärderas till false eller null, eller vilka referensegenskaper som inte är tillgängliga på grund av behörigheter, utelämnas från svaret.
Exempel finns i Fråga efter arbetsspårningsdata med analytics .
$orderby Använd för att ange i vilken ordning poster ska returneras.
Exempel finns i Fråga efter arbetsspårningsdata med hjälp av analys.
$top/$skip Använd för att begränsa antalet poster som returneras.
Exempel finns i Projekt- och organisationsomfattande frågor.
$select/$expand Använd $select för att ange de kolumner som du behöver för att skapa rapporten. Använd $expand för att kapsla andra frågealternativ. Var och expandItem en utvärderas i förhållande till entiteten som innehåller navigerings- eller strömegenskapen som expanderas.

Semikolonavgränsad lista över frågealternativ, omgivna inom parenteser, till namnet på navigeringsegenskapen. Tillåtna systemfrågealternativ är $filter, $select, $orderby, $skip, $top, $count, $searchoch $expand.
Exempel finns i Fråga efter arbetsspårningsdata med hjälp av analys.
$skiptoken Använd för att hoppa över ett angivet antal poster.
$count eller $count=true Ange $count för att endast returnera antalet poster. Ange $count=trueför att returnera både antalet poster och de data som efterfrågas.
Exempel finns i Sammanställa arbetsspårningsdata med analytics.

Dricks

Undvik blandning $apply och $filter satser i en enda fråga. Om du vill filtrera frågan har du två alternativ: (1) använder en $filter sats eller (2) använder en $apply=filter() kombinationssats. Vart och ett av dessa alternativ fungerar bra på egen hand, men om du kombinerar dem kan det leda till oväntade resultat.

Framtvinga sidindelning på serversidan

Analys tvingar fram växling när frågeresultatet överskrider 10 000 poster. I så fall får du den första sidan med data och en länk att följa för att hämta nästa sida. Länk (@odata.nextLink) finns i slutet av JSON-utdata. Det ser ut som en ursprunglig fråga följt av $skip eller $skiptoken. Till exempel:

{
  "@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"
}

Kommentar

När du hämtar data till klientverktyg som Power BI Desktop eller Excel följer verktyg automatiskt nästa länk och läser in alla nödvändiga poster.

Nästa steg

Skapa grundläggande frågor med OData Analytics