Freigeben über

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

  • Artikel

Azure DevOps Server | Azure DevOps Server 2022 - Azure DevOps Server 2019

Analytics, die Berichtsplattform für Azure DevOps, kann quantitative Fragen zu der Vergangenheit oder dem aktuellen Status Ihrer Projekte beantworten. Analytics unterstützt OData-Abfragen seiner Metadaten- und Entitätssatzdaten. Wenn Sie einfache Abfragen aus Ihrem Webbrowser ausführen, sind Sie mit dem Datenmodell und dem Abfrageprozess vertraut.

In diesem Artikel lernen Sie Folgendes:

  • Erstellen einer Analytics-OData-Abfrage für die Cloud oder lokal
  • Abfragen von Analysemetadaten
  • Abfragen von Analytics-OData für einen Entitätssatz
  • Welche Abfrageoptionen unterstützt werden, und die empfohlene Sequenz
  • Wann das serverseitige Paging erzwungen wird

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.

Hinweis

OData, ein Protokoll auf Anwendungsebene für die Interaktion mit Daten über RESTful(where REST=Representational State Transfer)-Schnittstellen), unterstützt die Beschreibung von Datenmodellen sowie das Bearbeiten und Abfragen von Daten gemäß diesen Modellen. 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.

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.

URL-Komponenten zum Abfragen der Metadaten

Analytics macht das 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 ein Projekt oder eine gesamte Organisation in Azure DevOps.

Sie können eines der folgenden Datenelemente nachschlagen, indem Sie die Metadaten abfragen.

  • Entitätstypen und Entitätssätze
  • Eigenschaften und Navigationseigenschaften
  • Ersatzschlüssel
  • Aufzählungslisten
  • EntitySet
  • Container
  • Filterfunktionen (Org.OData.Capabilities.V1.FilterFunctions)
  • Unterstützte Aggregationen (Org.OData.Aggregation.V1.ApplySupported)
  • Batch-Support (Org.OData.Capabilities.V1.BatchSupportType)

Die verwendete URL hängt davon ab, ob Sie Daten für Azure DevOps Services (Cloud) oder einen lokalen Azure DevOps Server abfragen.

Um die Metadaten für eine Organisation oder ein Projekt abzufragen, die in der Cloud gehostet werden, geben Sie die URL-Syntax ein, wie unten in einem Webbrowser gezeigt. Ersetzen Sie {OrganizationName} und {ProjectName} durch den Namen Ihrer Organisation und den Namen des Projekts, die oder das Sie abfragen möchten. Um alle Metadaten für die Organisation zurückzugeben, geben Sie nicht den Projektnamen an.

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

Hinweis

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

Hier ist ein Beispiel für die fabrikam-Organisation, die in Azure DevOps Services gehostet wird.

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

Interpretieren der Metadatenantwort

Analytics gibt eine XML-Datei des Datenmodells zurück. Verwenden Sie die Suchfunktion Ihres Browsers, um Informationen zu der Entität zu finden, die Sie interessiert.

Tipp

Je nachdem, welchen Browser Sie verwenden, kann diese Datei in lesbarer Weise formatiert werden. Wenn sie nicht formatiert ist, finden Sie einen kostenlosen Online-XML-Formatierer über eine Webbrowsersuche.

Die beiden in den Analysemetadaten definierten Hauptschemas sind Microsoft.VisualStudio.Services.Analytics.Model, die Entitätstypen und aufgezählten Typen und deren Member sowie das Default-Schema, das die Entitätscontainer und Entitätssätze definiert und unterstützte OData-Filter-, Transformations- und benutzerdefinierte Aggregationsfunktionen definiert. Weitere Informationen finden Sie unter Analytics-OData-Metadaten.

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

Alle Entitätstypen sind Eigenschaften und Navigationseigenschaften zugeordnet. Sie können Ihre Abfragen von Entitätssätzen mithilfe dieser Eigenschaftentypen filtern. Diese werden in den Metadaten unter der EntityType als eine Property oder NavigationalProperty aufgelistet. Sie verwenden verwandte Entitäten, um zusätzliche Filter anzugeben, z. B. Iterationspfade, Bereichspfade oder Teams.

Der folgende Codeausschnitt stellt eine partielle Ansicht der Metadaten für die WorkItem-Entität bereit. Eigenschaften entsprechen einem Arbeitsaufgabenfeld sowie bestimmten Daten, die von Analytics erfasst werden, wie LeadTimeDays und CycleTimeDays. Navigationseigenschaften entsprechen anderen Entitätssätzen oder bestimmten Analysedaten, die für den Entitätstyp erfasst werden, wie 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"/>
...

URL-Komponenten zum Abfragen von Entitäten

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.

Die folgende URL wird verwendet, um eine bestimmte EntitySet abzufragen, wie WorkItems, WorkItemSnapshot und 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 ist ein Beispiel für die fabrikam-Organisation, die die Anzahl der Arbeitselemente zurückgibt, die für das Fabrikam Fiber-Projekt definiert sind.

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

Im Beispiel werden 1399 Arbeitselemente zurückgegeben.

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

Hinweis

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.". Dies entspricht dem Ausführen einer select-Anweisung für den Entitätssatz und dem Zurückgeben aller Elemente, aller Spalten und aller Zeilen. Wenn Sie über eine große Anzahl von Datensätzen verfügen, kann der Vorgang mehrere Sekunden dauern. Bei mehr als 10.000 Arbeitselemente wird das servergesteuerte Paging erzwungen.

Um zu vermeiden, dass Nutzungsgrenzwerte gelten, schließen Sie immer eine $select oder $apply-Klausel ein.

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

Beispiel: Abfragen eines bestimmten Entitätssatzes

Um einen bestimmten Entitätssatz abzufragen, wie WorkItems, Areas oder Projects fügen Sie den Namen des Entitätssatzes hinzu: /WorkItems, /Areas oder /Projects. 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. Für die Fabrikam-Organisation ist die URL wie unten dargestellt.

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

Analytics gibt die Projektnamen dieser Projekte zurück, die für die fabrikam-Organisation definiert sind.

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

Abfrageoptionen

Eine Abfrageoption ist ein Satz von Abfragezeichenfolgenparametern, die auf eine Ressource angewendet werden, die helfen kann, die Menge der Daten zu steuern, die für die Ressource in der URL zurückgegeben werden.

Abfrageoptionen sollten in der Reihenfolge angegeben werden, die in der folgenden Tabelle aufgeführt ist.

Abfrageoption Notizen
$apply Gruppe von Transformationen, die Sie auf eine Abfrage anwenden können, z. B.: filter, groupby, aggregate, compute, expand,concat
Beispiele finden Sie unter Aggregierte Arbeitsverfolgungsdaten mithilfe von Analytics.
$compute Eine unterstützte OData-Funktion, die Sie angeben können, um berechnete Eigenschaften zu definieren, die in einem $select-, $filter-, oder $orderby-Ausdruck verwendet werden können.
$filter Dient zum Filtern der Liste der zurückgegebenen Ressourcen. Der mit $filter angegebene Ausdruck wird für jede Ressource in der Sammlung ausgewertet, und nur Elemente, bei denen der Ausdruck als wahr bewertet wird, werden in die Antwort aufgenommen. Ressourcen, für die der Ausdruck als „false” oder „null” ausgewertet wird oder welche Referenzeigenschaften aufgrund von Berechtigungen nicht verfügbar sind, werden aus der Antwort weggelassen.
Beispiele finden Sie unter Abfragen von Arbeitsverfolgungsdaten mithilfe von Analytics.
$orderby Dient zum Angeben der Reihenfolge, in der Datensätze zurückgegeben werden sollen.
Beispiele finden Sie unter Abfragen von Arbeitsverfolgungsdaten mithilfe von Analytics.
$top/$skip Wird verwendet, um die Anzahl der zurückgegebenen Datensätze einzuschränken.
Beispiele finden Sie unter Projekt- und organisationsbezogene Abfragen.
$select/$expand Verwenden Sie $select, um die Spalten angeben, die Sie zum Erstellen des Berichts benötigen. Verwenden Sie $expand, um andere Abfrageoptionen zu verschachteln. Jede expandItem wird relativ zur Entität ausgewertet, die die Navigations- oder Datenstromeigenschaft enthält, die erweitert wird.

Durch Semikolons getrennte Liste der Abfrageoptionen, die in Klammern eingeschlossen sind, zum 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 Wird verwendet, um eine angegebene Anzahl von Datensätzen zu überspringen.
$count oder $count=true Geben Sie $count ein, um nur die Anzahl der Datensätze zurückzugeben. 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, haben Sie zwei Optionen: (1) Verwenden der $filter-Klausel oder (2) der $apply=filter()-Kombinationsklausel. Jede dieser Optionen eignet sich hervorragend, die Kombination dieser Optionen kann jedoch zu unerwarteten Ergebnissen führen.

Serverseitiges Paging erzwingen

Analytics erzwingt das Paging, wenn Abfrageergebnisse 10.000 Datensätze überschreiten. In diesem Fall erhalten Sie die erste Seite mit Daten und einen Link, der sich zur nächste Seite führt. Den Link (@odata.nextLink) finden Sie am Ende der JSON-Ausgabe. Es sieht wie eine ursprüngliche Abfrage aus, gefolgt von $skip oder $skiptoken. Zum Beispiel:

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

Hinweis

Wenn Sie Daten in Clienttools wie Power BI Desktop oder Excel abrufen, folgen Tools automatisch dem nächsten Link und laden alle erforderlichen Datensätze.

Nächste Schritte

Erstellen grundlegender Abfragen mit OData Analytics