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

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

Analytics, die Azure DevOps-Berichterstellungsplattform, kann quantitative Fragen zu der Vergangenheit oder dem aktuellen Status Ihrer Projekte beantworten. Analytics unterstützt OData-Abfragen seiner Metadaten- und Entitätssatzdaten. Sie können mehr über das Datenmodell und den Abfrageprozess erfahren, indem Sie einfache Abfragen aus Ihrem Webbrowser ausführen.

Hinweis

OData, ein Protokoll auf Anwendungsebene für die Interaktion mit Daten über REST-Schnittstellen (Representational State Transfer), unterstützt die Beschreibung, Bearbeitung und Abfrage von Datenmodellen. Das Entitätsdatenmodell (Entity Data Model, EDM) oder Metadaten beschreibt die Informationen, die in Analytics verfügbar sind, einschließlich der Entitäten, Entitätstypen, Eigenschaften, Beziehungen und Enumerationen, die Sie zum Abfragen der Daten zum Erstellen von Berichten verwenden. Eine Übersicht über OData finden Sie unter Willkommen bei OData.

In diesem Artikel wird Folgendes erläutert:

Erstellen einer Analytik-OData-Abfrage.
Abfrageanalysemetadaten.
OData-Abfrageanalyse für einen Entitätensatz.
Verwenden Sie Abfrageoptionen in der empfohlenen Sequenz.
Serverseitiges Paging verstehen.

Sie können Analytics von jedem unterstützten Webbrowser abfragen. Weitere Tools, die Sie zum Abfragen von Analytics verwenden können, finden Sie unter Analyseabfragetools.

Voraussetzungen

Kategorie	Anforderungen
Zugriffsebenen	- Projektmitglied. - Mindestens Basis-Zugriff.
Berechtigungen	Standardmäßig verfügen Projektmitglieder über die Berechtigung zum Abfragen von Analysen und Erstellen von Ansichten. Weitere Informationen zu anderen Voraussetzungen für die Dienst- und Featureaktivierung sowie allgemeine Datenverfolgungsaktivitäten finden Sie unter Berechtigungen und Voraussetzungen für den Zugriff auf Analytics.

Abfragen der Metadaten

Analytics macht das OData-Entitätsmodell an der Metadaten-URL verfügbar, die durch Anfügen $metadata an die Stamm-URL des Diensts gebildet wird. Analytics bietet Dienststammangaben für Azure DevOps-Projekte oder ganze Organisationen und Sammlungen.

Sie können die Metadaten abfragen, um eines der folgenden Datenelemente nachzuschlagen:

Entitätstypen und Entitätssätze
Eigenschaften und Navigationseigenschaften
Ersatzschlüssel
Aufzählungslisten
Entitätssätze
Container
Filterfunktionen mit Org.OData.Capabilities.V1.FilterFunctions
Unterstützte Aggregationen mit Org.OData.Aggregation.V1.ApplySupported
Typ der Batchunterstützung mit Org.OData.Capabilities.V1.BatchSupportType

Geben Sie die folgende URL-Syntax in einen Webbrowser ein, um die Metadaten für eine Organisation oder ein in der Cloud gehostetes Projekt abzufragen. Ersetzen Sie <OrganizationName> und <ProjectName> durch die Namen der Organisation und des Projekts, die Sie abfragen möchten. Wenn Sie alle Metadaten für eine Organisation zurückgeben möchten, geben Sie keinen Projektnamen an.

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

Im folgenden Beispiel werden Metadaten für die fabrikam Organisation abgefragt.

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

In der Abfragezeichenfolge analytics.dev.azure.com ist die Stamm-URL des Analysediensts, gefolgt vom Namen der Organisation, dem Projektnamen, der OData-Version und $metadata der Bezeichnung.

Um die Metadaten für einen Server abzufragen, geben Sie die folgende URL-Syntax in einen Webbrowser ein. Ersetzen Sie <ServerName>, <CollectionName> und <ProjectName> durch die Namen des Servers, der Sammlung und des Projekts, das Sie abfragen möchten. Wenn Sie alle Metadaten für eine Auflistung zurückgeben möchten, geben Sie keinen Projektnamen an.

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

Im folgenden Beispiel werden die Metadaten für einen Server mit dem Namen fabrikam-devops und dessen Namen DefaultCollectionabgerufen.

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

Hinweis

Die neueste OData-Version von Analytics ist v4.0-preview. Sie können diese Version für alle Abfragen für Azure DevOps verwenden. Weitere Informationen zu Analytics-Versionen und verfügbaren Daten finden Sie unter Datenmodell für Analytics.

Interpretieren der Metadatenantwort

Analytics gibt eine XML-Datei des Datenmodells zurück. Verwenden Sie Ihre Browser-Suchfunktion, um Informationen für Ihre Interessentität zu finden.

Tipp

Je nach Browser wird diese Datei möglicherweise nicht lesbar formatiert. Sie finden einen kostenlosen Online-XML-Formatierer über eine Websuche.

Analysemetadaten definieren die folgenden Hauptschemas.

Microsoft.VisualStudio.Services.Analytics.Model definiert die Entitätstypen und aufgezählten Typen und deren Mitglieder.
Das Default Schema definiert die Entitätscontainer und Entitätssätze und unterstützte OData-Filter-, Transformations- und benutzerdefinierte Aggregationsfunktionen.

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

Alle Entitätstypen verfügen über Eigenschaften und Navigationseigenschaften, mit denen Sie Ihre Abfragen filtern können. Diese Eigenschaften werden in den Metadaten als Property oder NavigationProperty unter jedem EntityTypeaufgeführt. Sie können verwandte Entitäten verwenden, um weitere Filter anzugeben, z. B. Iterationspfade, Bereichspfade oder Teams.

Der folgende Codeausschnitt zeigt eine partielle Ansicht der Metadaten für die WorkItem Entität. Eigenschaften entsprechen Arbeitsaufgabenfeldern und spezifischen Daten, die von Analytics erfasst werden, wie z. B. LeadTimeDays und CycleTimeDays. Navigationseigenschaften entsprechen anderen Entitätssätzen und bestimmten Analysedaten, die für den Entitätstyp erfasst werden, wie z. B. Revisions, Links, Children und 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"/>
...

Informationen zu Entitätsmetadaten und Beziehungsinformationen finden Sie in den folgenden Artikeln:

Abfrageentitätssätze

Um Analysedaten abzufragen und Berichte zu erstellen, fragen Sie in der Regel einen Entitätssatz ab. Eine Übersicht über unterstützte Entitäten finden Sie unter Analytics-OData-Metadaten.

Verwenden Sie die folgende URL-Syntax, um eine bestimmte EntitySet, z. B. WorkItems, WorkItemSnapshot oder PipelineRuns abzufragen. Ersetzen Sie sie <EntitySet> durch die Entität, die Sie durchsuchen möchten, und <QueryOptions> durch Abfrageoptionen, wie in "Abfrageoptionen verwenden" beschrieben.

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

Im folgenden Beispiel wird die Anzahl der Arbeitsaufgaben im Projekt Fabrikam Fiber der Organisation fabrikam abgefragt.

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

Die Beispielabfrage gibt Ergebnisse zurück, die die Anzahl der 1399 Arbeitsaufgaben anzeigen.

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

Im folgenden Beispiel wird die Anzahl der Arbeitsaufgaben im Fabrikam Projekt im DefaultCollectionfabrikam Server abgerufen.

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

Die Beispielabfrage gibt die folgenden Ergebnisse von 1399 Arbeitsaufgaben zurück.

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

Hinweis

Um zu vermeiden, dass die Nutzungsgrenzen erreicht werden, sollten Sie immer eine $select oder $apply Klausel in Ihre Abfrage einfügen. Wenn Sie keine $select oder $apply Klausel einschließen, erhalten Sie eine Warnung wie 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.

Das Weglassen einer $select- oder $apply-Klausel entspricht einer select-Anweisung für die Entitätsmenge, die alle Spalten und alle Zeilen zurückgibt. Wenn Sie über eine große Anzahl von Datensätzen verfügen, kann die Abfrage mehrere Sekunden dauern. Wenn mehr als 10.000 Elemente vorhanden sind, wird das serverseitige Paging erzwungen.

Beispiel: Abfragen eines bestimmten Entitätssatzes

Um einen bestimmten Entitätssatz abzufragen, fügen Sie z. B. WorkItems, Areas oder Projects den Namen des Entitätssatzes zur Abfrage hinzu. Eine vollständige Liste der Entitätssätze finden Sie unter Datenmodell für Analytics.

Sie können beispielsweise eine Liste der für Ihre Organisation definierten Projekte abrufen, indem Sie Projects abfragen und auswählen, um die ProjectName-Eigenschaft zurückzugeben. Das folgende Beispiel zeigt die Abfrage-URL für die fabrikam Organisation.

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

Analytics gibt die Namen der Projekte in der fabrikam Organisation zurück.

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

Sie können z. B. eine Liste von Projekten abrufen, die für Ihren Server und Ihre Sammlung definiert sind, indem Sie Projects abfragen und die Eigenschaft ProjectName zur Rückgabe auswählen. Das folgende Beispiel zeigt die Abfrage-URL für den DefaultCollection auf dem fabrikam Server.

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

Das Beispiel gibt die folgenden drei Projektnamen zurück.

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

Verwenden von Abfrageoptionen

Abfrageoptionen sind Abfragezeichenfolgenparameter, mit denen sie steuern können, wie viele Daten für eine Ressource zurückgegeben werden. Geben Sie Abfrageoptionen in der reihenfolge an, die in der folgenden Tabelle aufgeführt ist.

Abfrageoption	Description
`$apply`	Wendet eine Transformation auf eine Abfrage an, z. B. `filter`, `groupby`, `aggregate`, `compute` oder `expand`, `concat`. Beispiele finden Sie unter Aggregierte Arbeitsverfolgungsdaten mithilfe von Analytics.
`$compute`	Definiert berechnete Eigenschaften in einem `$select`, `$filter`oder `$orderby` Ausdruck.
`$filter`	Filtert die Liste der zurückgegebenen Ressourcen. Die Abfrage wertet den Ausdruck, der mit `$filter` für jede Ressource im Abfragebereich angegeben ist, aus und schließt nur Elemente ein, bei denen der Ausdruck zu `true` ausgewertet wird. Ressourcen, bei denen der Ausdruck zu `false` oder `null` ausgewertet wird oder bei denen Referenzeigenschaften aufgrund von Berechtigungen nicht verfügbar sind, werden aus der Antwort weggelassen. Beispiele finden Sie unter Abfragen von Arbeitsverfolgungsdaten mithilfe von Analytics.
`$orderby`	Gibt die Reihenfolge an, in der Datensätze zurückgegeben werden sollen. Beispiele finden Sie unter Abfragen von Arbeitsverfolgungsdaten mithilfe von Analytics.
`$top`/`$skip`	Beschränkt die Anzahl der zurückgegebenen Datensätze. Beispiele finden Sie unter Projekt- und organisationsbezogene Abfragen.
`$select`	Gibt die benötigten Spalten an.
`$expand`	Schachtelt andere Abfrageoptionen. Jede `expandItem` wird relativ zur Entität ausgewertet, die die Navigations- oder Datenstromeigenschaft enthält, die erweitert wird. Stellen Sie eine durch Kommas getrennte Liste von Abfrageoptionen bereit, die in Klammern gesetzt sind, für den Namen der Navigationseigenschaft. Zulässige Systemabfrageoptionen sind `$filter`, `$select`, `$orderby`, `$skip`, `$top`, `$count`, `$search` und `$expand`. Beispiele finden Sie unter Abfragen von Arbeitsverfolgungsdaten mithilfe von Analytics.
`$skiptoken`	Überspringt eine angegebene Anzahl von Datensätzen.
`$count` oder `$count=true`	Gibt nur die Anzahl der Datensätze zurück. Geben Sie `$count=true` ein, um sowohl eine Anzahl des Datensatzes als auch die abgefragten Daten zurückzugeben. Beispiele finden Sie unter Aggregierte Arbeitsverfolgungsdaten mithilfe von Analytics.

Tipp

Vermeiden Sie das Vermischen von $apply- und $filter- Klauseln in einer einzelnen Abfrage. Um Ihre Abfrage zu filtern, können Sie entweder eine $filter Klausel verwenden oder eine $apply=filter() Kombinationsklausel verwenden. Beide Optionen funktionieren, aber die Kombination in einer einzelnen Abfrage kann zu unerwarteten Ergebnissen führen.

Grundlegendes zur serverseitigen Paging

Analyse erzwingt das Paging, wenn Abfrageergebnisse 10.000 Datensätze überschreiten. In diesem Fall erhalten Sie die erste Seite mit Daten und einen Link, dem Sie folgen möchten, um die nächste Seite zu erhalten. Clienttools wie Power BI Desktop oder Excel folgen automatisch dem @odata.nextLink und laden alle erforderlichen Datensätze, wenn Daten abgerufen werden.

Sie finden den @odata.nextLink Link am Ende der JSON-Ausgabe. Der Link sieht wie die ursprüngliche Abfrage aus, gefolgt von $skip oder $skiptoken. Zum Beispiel:

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

Nächster Schritt

Erstellen grundlegender Abfragen mit OData Analytics

Feedback

War diese Seite hilfreich?

Last updated on 2025-12-17

Freigeben über

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

Voraussetzungen

Abfragen der Metadaten

Interpretieren der Metadatenantwort

Abrufen verwandter Entitäten und Navigationseigenschaften

Abfrageentitätssätze

Beispiel: Abfragen eines bestimmten Entitätssatzes

Verwenden von Abfrageoptionen

Grundlegendes zur serverseitigen Paging

Nächster Schritt

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen