Abfragen ihrer Arbeitsnachverfolgungsdaten mithilfe von OData Analytics

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019

Mithilfe von Analytics für Azure DevOps können Sie grundlegende und gefilterte Abfragen erstellen, um Arbeitsaufgaben von Interesse zurückzugeben. Sie können diese Abfragen direkt in Ihrem Browser ausführen.

Hinweis

Der Analysedienst wird automatisch für alle Azure DevOps Services aktiviert. Sie wird für die Verwendung in der Produktion unterstützt. Power BI Integration und Zugriff auf den OData-Feed des Analysediensts befinden sich in der Vorschau. Wir empfehlen Ihnen, sie zu verwenden und uns Feedback zu geben.

Hinweis

Der Analysedienst wird automatisch auf allen neuen Projektsammlungen für Azure DevOps Server 2020 installiert. Sie wird für die Verwendung in der Produktion unterstützt. Power BI Integration und Zugriff auf den OData-Feed des Analysediensts befinden sich in der Vorschau. Wir empfehlen Ihnen, sie zu verwenden und uns Feedback zu geben. Wenn Sie ein Upgrade von Azure DevOps Server 2019 durchgeführt haben, erhalten Sie die Möglichkeit, den Analysedienst während des Upgrades zu installieren.

Hinweis

Der Analysedienst befindet sich in der Vorschau für Azure DevOps Server 2019. Sie greifen auf Analytics zu, indem Sie sie für eine Projektsammlung aktivieren oder installieren . Power BI Integration und Zugriff auf den OData-Feed des Analysediensts befinden sich in der Vorschau. Wir empfehlen Ihnen, sie zu verwenden und uns Feedback zu geben.

In diesem Artikel wird die Basisstamm-URL auf ein Projekt festgelegt, wie gezeigt:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}
https://{ServerName}:{Port}/tfs/{CollectionName}/{ProjectName}/_odata/{version}

Hinweis

Die in diesem Dokument gezeigten Beispiele basieren auf einer Azure DevOps Services-URL, sie müssen in Ihrer Azure DevOps Server-URL ersetzen.

Alle anderen URL-Teile werden als zusätzlicher Teil der Abfragezeichenfolge angegeben.

Voraussetzungen

Erstellen einer einfachen Abfrage

Sie erstellen eine einfache Abfrage, indem Sie die OData-URL in einen unterstützten Webbrowser eingeben. Ersetzen {OrganizationName} Sie in den bereitgestellten Beispielen den Namen Ihrer Organisation und {ProjectName} den Namen des Projekts, das Sie abfragen möchten.

Sie erstellen eine einfache Abfrage, indem Sie die OData-URL in einen unterstützten Webbrowser eingeben. Nehmen Sie in den angegebenen Beispielen die folgenden Ersetzungen vor:

  • analytics.dev.azure.com mit {ServerName}:{Port}/tfs/
  • {OrganizationName} mit ihrem Projektsammlungsnamen (Standardeinstellung ist DefaultCollection)
  • {ProjectName} mit dem Namen des Projekts, das Sie abfragen möchten.

Hinweis

Der {version} Wert wird als v1.0formatiert. Die neueste unterstützte Version ist v2.0, und die neueste Vorschauversion ist v4.0-preview. Weitere Informationen finden Sie unter OData-API-Versionsverwaltung.

Abfragen eines einzelnen Entitätssatzes

Um einen einzelnen Entitätssatz abzufragen, z. B. Arbeitselemente oder Bereiche oder Projekte, fügen Sie den Namen der Entität hinzu: /Areas, /Projectsoder /WorkItems. Eine vollständige Liste der Entitätssätze finden Sie unter "Data Model for Analytics".

Sie abfragen z. B. Bereiche durch Hinzufügen /Areasvon Bereichen. Die vollständige URL lautet:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/Areas 

Es entspricht der Ausführung einer Select-Anweisung für den Entitätssatz und zurückgeben alles, alle Spalten und alle Zeilen. Wenn Sie über eine große Anzahl von Arbeitselementen verfügen, kann es mehrere Sekunden dauern. Wenn Sie mehr als 10000 Arbeitselemente haben, werden serverseitige Paging erzwungen.

Auswählen bestimmter Spalten oder Felder

Geben Sie bestimmte Felddaten zurück, indem Sie eine $select Klausel hinzufügen.

Wenn Sie beispielsweise nur die Arbeitselement-ID, den Arbeitselementtyp, den Titel und den Status der Arbeitselemente zurückgeben möchten, fügen Sie diese Klausel ihrer Abfrage hinzu:

/WorkItems?$select=WorkItemId,WorkItemType,Title,State

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State

Es entspricht dem Auswählen aller Zeilen in der Entität, aber es gibt nur diese spezifischen Felder zurück.

Hinweis

Feldnamen enthalten keine Leerzeichen. Ihre Abfrage schlägt fehl, wenn Sie Leerzeichen hinzufügen. OData-Abfragen erfordern, dass sowohl der Abstand als auch das Casing beachtet werden.

Filtern der Daten

Sie können Daten filtern, indem Sie eine Abfragefilterklausel bereitstellen. Auf der letzten Abfrage würden Sie die folgende Filterklausel hinzufügen, um nur diese Arbeitselemente zurückzugeben, um den Status "In Bearbeitung" zurückzugeben.

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=State eq 'In Progress'

Mit der vollständigen OData-Abfrage:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=State eq 'In Progress'

Stattdessen können Sie die $select Klausel vollständig ausschließen und einfach die Ergebnisse wie folgt filtern:

/WorkItems?$filter=State eq 'In Progress'

Mit der vollständigen OData-Abfrage:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=State eq 'In Progress'

Sie können auch mehrere Filter anwenden, indem Sie zwei oder mehr Filter verketten. Hier filtern wir nach In Bearbeitungsaufgaben:

/WorkItems?$filter=WorkItemType eq 'Task' and State eq 'In Progress'

Mit der vollständigen OData-Abfrage:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=WorkItemType eq 'Task' and State eq 'In Progress'

Darüber hinaus können Sie verschiedene Funktionen wie , containsstartswithund endswith vieles mehr anwenden. Siehe die unterstützten OData-Features und -Klauseln, Unterstützte Funktionen.

Datumsbereichsabfragen

Im folgenden Beispiel werden Arbeitselemente zurückgegeben, deren Geändertes Datum größer als 1. Januar 2021 ist.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-01-01Z

Im folgenden Beispiel werden Arbeitselemente zurückgegeben, deren Geändertes Datum während der Woche vom 26. April bis zum 30. April 2021 auftritt.

https://analytics.dev.azure.com{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-04-26Z&ChangedDate le 2021-04-30Z

Das Abfragen von Arbeitselementen ist hilfreich, Sie möchten jedoch schließlich nach anderen Daten wie dem Iterationspfad, dem Bereichspfad oder dem Projekt filtern. Dazu müssen Sie die Navigationseigenschaften des Entitätsmodells verstehen. Sie können Metadaten mithilfe der /$metadata URL abrufen. Ausführliche Informationen finden Sie unter Explore Analytics OData-Metadaten

Nachfolgend finden Sie eine partielle Ansicht der Metadaten für die Entität "Arbeitselemente":

    <Property ...>
    <Property Name="RequirementType" Type="Edm.String"/>
    <Property Name="RequiresReview" Type="Edm.String"/>
    <Property Name="RequiresTest" Type="Edm.String"/>
    <Property Name="RootCause" Type="Edm.String"/>
    <Property Name="SubjectMatterExpert1" Type="Edm.String"/>
    <Property Name="SubjectMatterExpert2" Type="Edm.String"/>
    <Property Name="SubjectMatterExpert3" Type="Edm.String"/>
    <Property Name="TargetResolveDate" Type="Edm.DateTimeOffset"/>
    <Property Name="TaskType" Type="Edm.String"/>
    <Property Name="UserAcceptanceTest" Type="Edm.String"/>
    <Property Name="Count" Nullable="false" Type="Edm.Int32"/>
    <NavigationProperty Name="Revisions" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemRevision)"/>
    <NavigationProperty Name="BoardLocations" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.BoardLocation)"/>
    <NavigationProperty Name="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project"/>
    <NavigationProperty Name="Area" Type="Microsoft.VisualStudio.Services.Analytics.Model.Area"/>
    <NavigationProperty Name="Iteration" Type="Microsoft.VisualStudio.Services.Analytics.Model.Iteration"/>

Die Navigationseigenschaften werden am unteren Rand der Metadaten angezeigt, einschließlich Revisions, BoardLocations (Kanban-Metadaten), Project, Areaund Iteration.

Filtern nach einer Navigationseigenschaft

Wie verwenden Sie Navigationseigenschaften, um Ergebnisse zu filtern?

Verwenden Sie die folgende Klausel, um Arbeitselemente basierend auf einer bestimmten Iteration zu filtern, z. B. Iteration 1:

/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

Mit der vollständigen OData-Abfrage:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

In diesem Beispiel Iteration ist der Name der Navigationseigenschaft und IterationPath entspricht dem vollständigen Pfad für die Iteration. Wenn Sie eine andere Entität als Filter verwenden möchten, platzieren Sie die Navigationseigenschaft gefolgt von einem Schrägstrich gefolgt vom Namen des zu filternden Felds.

Wie verwenden Sie Navigationseigenschaften, um verwandte Felder auszuwählen?

Der Benutzername für benutzerdefinierte Felder basierend auf einer Identität ist nicht direkt über eine $select Anweisung zugänglich. Die folgende Abfrage verwendet eine $expand Anweisung zum Abrufen des Benutzernamens:

/WorkItems?$expand=MyIdentityField($select=UserName)

Hinweis

Sie können die Navigationseigenschaft nicht direkt in einer $select Anweisung verwenden. Stattdessen müssen $expandSie .

Das vorherige Filterbeispiel für den Iterationspfad gibt den Iterationspfad nicht in den Ergebnissen zurück, da es in einer verwandten Entität enthalten ist. Fügen Sie eine $expand Anweisung hinzu, um Daten in einer verwandten Entität zurückzugeben:

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration

Es gibt die folgende JSON zurück:

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)",
  "value":[
    {
      "WorkItemId":10000,
      "WorkItemType":"Task",
      "Title":"Some title",
      "State":"Completed",
      "Iteration":{
        "IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46",
        "Name":"Sprint 55",
        "Number":13021,
        "IterationPath":"Fabrikam\\Sprints\\Sprint 55",
        "StartDate":"2013-09-23T00:00:00Z",
        "EndDate":"2013-10-11T00:00:00Z",
        "IterationLevel1":"Fabrikam",
        "IterationLevel2":"Sprints",
        "IterationLevel3":"Sprint 55",
        "Level":2,
        "IsDeleted":false
      }
    }
  ]
}

Wie Sie sehen können, wird der Iterationspfad im JSON-Ergebnis erweitert und alle Iterationsdaten werden zurückgegeben. Es ist wahrscheinlich mehr Daten als gewünscht.

Um weniger Daten zurückzugeben, fügen Sie eine $select Anweisung auch für die Iteration hinzu:

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration($select=Name,IterationPath)

Es gibt die folgende JSON zurück:

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration,Iteration(Name,IterationPath))",
  "value":[
    {
      "WorkItemId":10000,
      "WorkItemType":"Task",
      "Title":"Some title",
      "State":"Completed",
      "Iteration":{
        "Name":"Sprint 55",
        "IterationPath":"Fabrikam\\Sprints\\Sprint 55"
      }
    }
  ]
}

In OData können Sie Anweisungen verschachteln $expand . Sie können beispielsweise die vorherige Abfrage-Anweisung schreiben, um das Projekt anzuzeigen, in dem die Iteration Teil ist:

/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($expand=Project)

Es gibt die folgende JSON zurück:

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
  "value":[
    {
      "WorkItemId":10000,
      "Revision":3,
      "Watermark":283397,
      "Title":"Production deployment and testing for Entitlement API v2 and Subscriber database",
      "WorkItemType":"Task",
      "ChangedDate":"2014-07-10T19:29:58.41Z",
      "CreatedDate":"2014-04-19T22:44:58.31Z",
      "State":"Completed",
      "Reason":"Completed",
      "Priority":2,
      "CompletedWork":10.0,
      "OriginalEstimate":20.0,
      "Count":1,
      "Iteration":{
        "IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46",
        "Name":"Sprint 55",
        "Number":13021,
        "IterationPath":"Fabrikam\\Sprints\\Sprint 55",
        "StartDate":"2013-09-23T00:00:00Z",
        "EndDate":"2013-10-11T00:00:00Z",
        "IterationLevel1":"Fabrikam",
        "IterationLevel2":" Sprints",
        "IterationLevel3":"Sprint 55",
        "Level":2,
        "IsDeleted":false,
        "Project":{
          "ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
          "ProjectName":"Fabrikam",
          "IsDeleted":false
        }
      }
    }
  ]
}

Sie können auch Anweisungen kombinieren und $select festlegen$expand. Sie können beispielsweise die vorherige Abfrage ändern, um nur den Iterationsnamen und den Iterationspfad zurückzugeben:

/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($select=IterationId,IterationPath;$expand=Project)

Es gibt die folgende JSON zurück:

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(Iteration(IterationId,IterationPath,Project))",
  "value":[
    {
      "WorkItemId":10000,
      "Revision":3,
      "Watermark":283397,
      "Title":"Production deployment and testing for Entitlement API v2 and Subscriber database","WorkItemType":"Task",
      "ChangedDate":"2014-07-10T19:29:58.41Z",
      "CreatedDate":"2014-04-19T22:44:58.31Z",
      "State":"Completed",
      "Reason":"Completed",
      "Priority":2,
      "CompletedWork":10.0,
      "OriginalEstimate":20.0,
      "Count":1,
      "Iteration":{
        "IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46","IterationPath":"Fabrikam\\Sprints\\Sprint 55",
        "Project":{
          "ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
          "ProjectName":"Fabrikam",
          "IsDeleted":false
        }
      }
    }
  ]
}

Beachten Sie, dass das Ergebnis hier nur die IterationId und IterationPath anzeigt und dass das Project ein geschachteltes Objekt im JSON-Ergebnis ist. Ein weiteres zu beachtende Schlüsselelement ist die URL selbst. Wenn Sie eine Anweisung und eine $select$expand Klausel verwenden, müssen Sie einen Semikolon (;) vor dem $expand. Alles andere führt zu einem Fehler.

Ergebnisse sortieren

Sie können OData-Ergebnisse mithilfe der $orderby Klausel sortieren. Sie können diese Klausel auf eine beliebige OData-Abfrage anwenden, wie gezeigt:

/WorkItems?$orderby=WorkItemId

Sie können in aufsteigender oder absteigender Reihenfolge mithilfe von Schlüsselwörtern ascdesc oder entsprechend sortieren:

/WorkItems?&$orderby=WorkItemId desc

Und Sie können nach mehreren Elementen bestellen:

/WorkItems?$orderby=WorkItemType,State

Erzwingen von serverseitigem Paging

Analyse erzwingt das Paging, wenn Abfrageergebnisse 10000 Datensätze überschreiten. In diesem Fall erhalten Sie erste Seite von Daten und Link, um zu folgen, um die nächste Seite zu erhalten. Link (@odata.nextLink) kann am Ende der JSON-Ausgabe gefunden werden. Es sieht wie eine ursprüngliche Abfrage aus, gefolgt von $skip oder $skiptoken. 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

Beim Abrufen von Daten in Clienttools wie Power BI Desktop oder Excel folgen Tools automatisch dem nächsten Link und laden alle erforderlichen Datensätze.

Nächste Schritte