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

  • Artikel

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

Analysen, die Berichtsplattform für Azure DevOps, können 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, können Sie sich mit dem Datenmodell und dem Abfrageprozess vertraut machen.

In diesem Artikel erfahren Sie Folgendes:

  • Erstellen einer Analyse-OData-Abfrage für die Cloud oder lokal
  • Abfragen von Analysemetadaten
  • Abfragen von Analyse-OData für einen Entitätssatz
  • Welche Abfrageoptionen unterstützt werden, und die empfohlene Sequenz
  • Beim Erzwungenen serverseitigen Paging

Sie können Analysen von jedem unterstützten Webbrowser abfragen. Weitere Tools, die Sie zum Abfragen von Analysen 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

  • Um Analytics-Daten anzuzeigen und den Dienst abzufragen, müssen Sie Mitglied eines Projekts mit oder höherer Basiszugriff sein. Standardmäßig erhalten alle Projektmitglieder Berechtigungen zum Abfragen von Analytics und zum Definieren von Analytics-Ansichten.
  • Weitere Informationen zu weiteren Voraussetzungen für die Dienst- und Featureaktivierung sowie allgemeine Datennachverfolgungsaktivitä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)
  • Batchunterstützung (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 wird, geben Sie die URL-Syntax ein, wie unten in einem Webbrowser gezeigt. Ersetzen Sie {OrganizationName} den Namen Ihrer Organisation und {ProjectName} den Namen des Projekts, 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 Ihre Browser-Suchfunktion, um informationen zu finden, die für die entität von Interesse spezifisch sind.

Tipp

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

Die beiden in den Analysemetadaten definierten Standard Schemas sind Microsoft.VisualStudio.Services.Analytics.Model, die die Entitätstypen und enumerationierten Typen und deren Member sowie das Default Schema definiert, das die Entitätscontainer und Entitätssätze und unterstützte OData-Filter-, Transformations- und benutzerdefinierte Aggregationsfunktionen definiert. Weitere Informationen finden Sie unter Analyse-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 oder Property .NavigationalProperty 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, z LeadTimeDays . B. und CycleTimeDays. Navigationseigenschaften entsprechen anderen Entitätssätzen oder bestimmten Analysedaten, die für den Entitätstyp erfasst werden, z Revisions. B. , , Links, Childrenund 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, z WorkItems. B. , , WorkItemSnapshotund 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 arbeitsaufgaben 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 Arbeitsaufgaben von 1399 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 Klausel einschließen, erhalten Sie eine Warnung, z. B. "Es entspricht dem Ausführen einer Select-Anweisung für den Entitätssatz" und dem Zurückgeben aller Elemente, aller Spalten und aller Zeilen.If you don't include a $select or $apply clause, you'll receive a warning, such as "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." It's equivalent to perform a select statement on the entity set and returning everything, all columns and all rows. Wenn Sie über eine große Anzahl von Datensätzen verfügen, kann es mehrere Sekunden dauern. Wenn Sie mehr als 10.000 Arbeitsaufgaben haben, wird die servergesteuerte Paging erzwungen.

Um zu vermeiden, dass Nutzungsgrenzwerte gelten, schließen Sie immer eine oder $apply eine $select 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, z WorkItems. B. , Areasoder Projectsfügen Sie den Namen des Entitätssatzes hinzu: /WorkItems, , /Areasoder /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 die Eigenschaft abfragen /Projects 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 Hinweise
$apply Gruppe von Transformationen, die Sie auf eine Abfrage anwenden können, z. B.: filter, groupby, , aggregate, , , computeexpand,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$filterOder $orderby Ausdruck verwendet werden können.
$filter Dient zum Filtern der Liste der zurückgegebenen Ressourcen. Der mit $filter diesem Ausdruck angegebene Ausdruck wird für jede Ressource in der Auflistung ausgewertet, und nur Elemente, bei denen der Ausdruck als "true" ausgewertet wird, werden in die Antwort einbezogen. 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 Abfragearbeitsnachverfolgungsdaten 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 Project- und Organisationsbezogene Abfragen.
$select/$expand Hier können $select Sie die Spalten angeben, die Sie zum Erstellen des Berichts benötigen. Wird verwendet $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, und $search$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 die Eingabetaste $count ein, um nur die Anzahl der Datensätze zurückzugeben. Geben Sie $count=trueein, 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 Mischen $apply und $filter Klauseln in einer einzelnen Abfrage. Um Ihre Abfrage zu filtern, haben Sie zwei Optionen: (1) verwenden eine $filter Klausel oder (2) eine $apply=filter() Kombinationsklausel. Jede dieser Optionen eignet sich hervorragend, aber die Kombination dieser Optionen kann zu unerwarteten Ergebnissen führen.

Serverseitiges Paging erzwingen

Analyse erzwingt das Paging, wenn Abfrageergebnisse 10000 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. 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