Erstellen von OData-Abfragen für Analytics in Azure DevOps

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Analytics macht Azure DevOps-Projektdaten über einen OData-Endpunkt verfügbar, den Sie von jedem unterstützten Webbrowser oder Clienttool abfragen können. Dieses Lernprogramm führt Sie durch die Abfrage-URL-Struktur – Metadaten, Entitätssätze und Abfrageoptionen – damit Sie mit der Erstellung Eigener Anforderungen beginnen können. Einen Vergleich der Abfragetools finden Sie unter Analyseabfragetools.

In diesem Tutorial erfahren Sie, wie:

Voraussetzungen

Abfragen der Metadaten

Um das OData-Entitätsmodell abzurufen, hängen Sie $metadata an die Stamm-URL des Analytics-Dienstes an. Die Metadaten beschreiben die Datenelemente, die Sie in Abfragen verwenden können, einschließlich:

• Entitätstypen, Entitätssätze und Container
• Eigenschaften und Navigations-Eigenschaften
• Ersatzschlüssel und aufgezählte Listen
• Unterstützte Filterfunktionen (Org.OData.Capabilities.V1.FilterFunctions)
• Unterstützte Aggregationen (Org.OData.Aggregation.V1.ApplySupported)
• Batchunterstützungstyp (Org.OData.Capabilities.V1.BatchSupportType)

https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/version/$metadata 

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

https://<ServerName>/<CollectionName>/<ProjectName>/_odata/version/$metadata 

https://fabrikam/DefaultCollection/_odata/v4.0-preview/$metadata  

Die Metadatenantwort interpretieren

Der Metadatenendpunkt gibt ein XML-Dokument zurück, das zwei Hauptschemas enthält:

• Microsoft.VisualStudio.Services.Analytics.Model — definiert Entitätstypen, Aufzählungstypen und deren Mitglieder.
• Default — definiert Entitätscontainer, Entitätssätze und unterstützte OData-Filter-, Transformations- und Aggregationsfunktionen.

Das folgende Beispiel zeigt die allgemeine Struktur:

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

Weitere Informationen finden Sie unter Analytics-OData-Metadaten.

Eigenschaften und Navigationseigenschaften

Die Metadaten für jeden Entitätstyp listet zwei Arten von Mitgliedern auf, die Sie in Abfragen verwenden können:

• Eigenschaften (Property) – entsprechen Arbeitsaufgabenfeldern und analysespezifischen Daten wie LeadTimeDays und CycleTimeDays. Verwenden Sie Eigenschaften in $select, $filterund $orderby Klauseln.
• Navigationseigenschaften (NavigationProperty) – Verknüpfung mit verwandten Entitätssätzen wie Revisions, , Links, Children, Parentund Teams. Verwenden Sie Navigationseigenschaften, um nach verwandten Entitäten wie Iterationspfaden, Bereichspfaden oder Teams und in $expand Klauseln zu filtern.

Der folgende Codeausschnitt zeigt eine teilweise Ansicht der Entitätsmetadaten WorkItem :

<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="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>
...
<NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>
<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="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project" Nullable="false">
   <ReferentialConstraint Property="ProjectSK" ReferencedProperty="ProjectSK"/>
</NavigationProperty>
...

Vollständige Eigenschaften- und Beziehungsdetails für jeden Servicebereich finden Sie unter:

• Kalenderdatum, Projekt und Benutzermetadatenverweis.
• Metadatenreferenz für Azure Boards.
• Metadatenreferenz für Azure-Pipelines.
• Metadatenreferenz für Testpläne.

Abfrageentitätssätze

Um Berichte zu erstellen, fragen Sie einen Entitätssatz wie WorkItems, WorkItemSnapshot, oder PipelineRuns. Eine vollständige Liste der unterstützten Entitäten finden Sie unter Analytics OData-Metadaten.

https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/version/<EntitySet>?<QueryOptions>

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

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

https://<ServerName>/<CollectionName>/<ProjectName>/_odata/version/<EntitySet>?<QueryOptions>

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

{
"@odata.context": "http://fabrikam/DefaultCollection/Fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)",
"value": [
   {
      "@odata.id": null,
      "Count": 44
   }
 ]
}

Beispiel: Auflisten von Projekten mit $select

Im folgenden Beispiel wird mit $select nur die ProjectName-Eigenschaft aus dem Projects-Entitätssatz zurückgegeben. Eine vollständige Liste der Entitätssätze finden Sie unter Datenmodell für Analytics.

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

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

https://fabrikam/DefaultCollection/_odata/v4.0-preview/Projects?$select=ProjectName

{
  "@odata.context": "http://fabrikam/DefaultCollection/_odata/v4.0-preview/$metadata#Projects(ProjectName)",
  "value": [
    { "ProjectName": "Fabrikam Fiber" },
    { "ProjectName": "Fabrikam" },
    { "ProjectName": "Fabrikam Florida" }
  ]
}

Verwenden von Abfrageoptionen

Fügen Sie Abfrageoptionen an die URL an, um die Antwort zu gestalten. Geben Sie sie in der hier gezeigten Reihenfolge an.

Grundlegendes zur serverseitigen Paging

Wenn eine Abfrage mehr als 10.000 Datensätze zurückgibt, werden die Ergebnisse von Analytics automatisch aufgeteilt. Die Antwort enthält eine @odata.nextLink URL, die auf die nächste Seite verweist. Clienttools wie Power BI Desktop und Excel folgen diesen Links automatisch.

Das folgende Beispiel zeigt eine paginierte Antwort:

{
  "@odata.context":"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#WorkItems",
  "value":[
   // first 10,000 records
  ],
  "@odata.nextLink":"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/WorkItems?$skiptoken=10000"
}

Wenn Sie aus dem Code abfragen, folgen Sie jedem @odata.nextLink, bis die Antwort keines mehr enthält.

Nächster Schritt

Verwandte Inhalte

• Was ist Analytics?
• OData Analytics-Abfragerichtlinien
• Berechtigungen und Voraussetzungen für den Zugriff auf Analytics in Azure DevOps