Definieren grundlegender Abfragen mithilfe von OData Analytics

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

Verwenden Sie Analytics-OData-Abfragen, um Arbeitsverfolgungsdaten aus Azure DevOps in Ihrem Browser oder in Clienttools wie Excel und Power BI abzurufen. Dieser Artikel behandelt das Zählen von Elementen, Auswählen bestimmter Felder mit $select, Filtern mit $filter, Erweitern von Navigationseigenschaften mit $expand, Abfragen von Datumsbereichen und Sortieren mit $orderby.

Die Beispiele konzentrieren sich auf Azure Boards Work Tracking Entity Sets, aber die gleichen Prinzipien gelten für andere Entitätssätze. Weitere Informationen finden Sie unter Erstellen von OData-Abfragen für Die Analyse - und Metadatenreferenz für Azure Boards Analytics.

Voraussetzungen

Anzahl der Elemente ermitteln

Um nur eine Anzahl ohne andere Daten zurückzugeben, fügen Sie $apply=aggregate($count as Count) an eine beliebige Entitätssatz-URL an. Die folgenden Abfragen zählen beispielsweise Projekte, Arbeitselemente, Bereichspfade und Benutzer in einer Organisation:

https://analytics.dev.azure.com/<OrganizationName>/_odata/v4.0-preview/Projects?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/<OrganizationName>/_odata/v4.0-preview/WorkItems?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/<OrganizationName>/_odata/v4.0-preview/Areas?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/<OrganizationName>/_odata/v4.0-preview/Users?$apply=aggregate($count as Count)

Die Projects Abfrage für die fabrikam Organisation gibt Folgendes zurück:

{
  "value": [
    {
      "Count": 16
    }
  ]
}

Anzahl der Elemente und deren Daten erfassen

Um eine Anzahl zusammen mit den Daten zurückzugeben, fügen Sie $count=true zu einer Abfrage hinzu, die eine $select-Klausel enthält. Die folgenden Abfragen geben eine Anzahl plus ausgewählte Eigenschaften für Arbeitsaufgaben, Bereichspfade und Benutzer in einem Projekt zurück:

https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/v4.0-preview/WorkItems?$count=true&$select=WorkItemId,Title,WorkItemType 
https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/v4.0-preview/Areas?$count=true&$select=AreaName,AreaPath 
https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/v4.0-preview/Users?$count=true&$select=UserName,UserEmail

Gültige Eigenschaftennamen finden Sie unter Metadatenreferenz für Azure Boards Analytics und Kalenderdatum, Project und Benutzermetadatenreferenz.

Die folgende Abfrage gibt beispielsweise die Anzahl und benutzernamen im Fabrikam Fiber-Projekt zurück:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Users?$count=true&$select=UserName

Die Antwort umfasst die Gesamtanzahl in @odata.count und die übereinstimmenden Datensätze in value.

{
  "@odata.count": 5,
  "value": [
    { "UserName": "Microsoft.VisualStudio.Services.TFS" },
    { "UserName": "fabrikamfiber1@hotmail.com" },
    { "UserName": "Jamal Hartnett" },
    { "UserName": "fabrikamfiber5@hotmail.com" },
    { "UserName": "fabrikamfiber2@hotmail.com" }
  ]
}

Auswählen bestimmter Eigenschaften oder Felder

Fügen Sie eine $select Klausel hinzu, um nur die benötigten Eigenschaften zurückzugeben. Bei Eigenschaftsnamen wird die Groß-/Kleinschreibung beachtet, darf keine Leerzeichen enthalten und den Namen von Arbeitsaufgabenfeldern entsprechen. Gibt beispielsweise $select=WorkItemId,WorkItemType,Title,State diese vier Felder zurück.

Informationen zu Eigenschaftennamensuchvorgängen, einschließlich benutzerdefinierter Felder, finden Sie in der Metadatenreferenz für Azure Boards.

Die folgende Abfrage gibt die ID, den Typ, den Titel und den Zustand für die drei wichtigsten Arbeitsaufgaben im Fabrikam Fiber-Projekt zurück:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$top=3

{
  "value": [
    { "WorkItemId": 31, "Title": "About screen", "WorkItemType": "Task", "State": "New" },
    { "WorkItemId": 30, "Title": "Change background color", "WorkItemType": "Task", "State": "Active" },
    { "WorkItemId": 32, "Title": "Standardize on form factors", "WorkItemType": "Task", "State": "Active" }
  ]
}

Filtern von Daten

Fügen Sie eine $filter Klausel hinzu, um nur Elemente zurückzugeben, die bestimmten Kriterien entsprechen. Verwenden Sie Vergleichsoperatoren wie eq, ne, gt, ge, lt und le, und kombinieren Sie Bedingungen mit and und or. Die folgende Abfrage gibt beispielsweise Features zurück, die ausgeführt werden:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,AssignedTo,State&$filter=WorkItemType eq 'Feature' and State eq 'In Progress'

Kombinieren mehrerer Filterbedingungen

Verwenden Sie Klammern, um or Bedingungen innerhalb eines breiteren Filters zu gruppierenand. Die folgende Abfrage gibt Benutzergeschichten, Fehler und einen benutzerdefinierten Typ in bestimmten Zuständen zurück:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,AssignedTo,State&$filter=(WorkItemType eq 'User Story' or WorkItemType eq 'Bug' or WorkItemType eq 'Backlog Work') and (State eq 'New' or State eq 'Committed' or State eq 'Active')

{
  "value": [
    { "WorkItemId": 210, "Title": "Slow response on form", "State": "Active" },
    ...
    { "WorkItemId": 160, "Title": "Game store testing", "State": "New" }
  ]
}

Sie können auch Zeichenfolgenfunktionen wie contains, startswithund endswith in Filterausdrücken verwenden. Weitere Informationen finden Sie unter "Unterstützte Funktionen".

Eigenschaften des Abfragebereichspfads oder Iterationspfads

Für einige Abfragen ist anstelle der Pfadzeichenfolge der Ersatzschlüssel (AreaSK oder IterationSK) erforderlich. Verwenden Sie die Entitätssätze "Bereiche" oder "Iterationen ", um den Schlüssel für einen bestimmten Pfad nachzuschlagen.

Geben Sie das AreaSK für einen bestimmten Bereichspfad zurück

Die folgende Abfrage gibt AreaSK für den Bereichspfad Fabrikam Fiber\Production Planning\Web zurück. Weitere verfügbare Eigenschaften finden Sie unter "Bereiche".

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Areas?$filter=AreaPath eq 'Fabrikam Fiber\Production Planning\Web'&$select=AreaSK

{
  "value": [
    { "AreaSK": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" }
  ]
}

Zurückgeben des IterationSK für einen bestimmten Iterationspfad

Die folgende Abfrage gibt den Wert IterationSK für den Iterationspfad Fabrikam Fiber\Release 1\Sprint 3 zurück. Weitere verfügbare Eigenschaften finden Sie unter Iterationen.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Iterations?$filter=IterationPath eq 'Fabrikam Fiber\Release 1\Sprint 3'&$select=IterationSK

Nach Navigationseigenschaften filtern

Navigationseigenschaften wie Iteration, Areaund AssignedTo stellen Beziehungen zu anderen Entitäten dar. Verwenden Sie den vollständigen Pfad im Format NavigationProperty/Field, um nach einem Feld aus einer verknüpften Entität zu filtern. Verweist beispielsweise Iteration/IterationPath auf das IterationPath Feld über die Iteration Navigationseigenschaft:

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

Die folgende Abfrage gibt die fünf wichtigsten Arbeitsaufgaben in einer bestimmten Iteration mithilfe des vollständigen Navigationspfads zurück:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Iteration/IterationPath eq 'Fabrikam Fiber\3Week Sprints\Sprint 3'&$select=WorkItemId,WorkItemType,Title,State&$orderby=WorkItemId asc

Erweitern von Daten aus verwandten Entitäten

Das Filtern nach einer Navigationseigenschaft führt dazu, dass deren Daten nicht in der Antwort enthalten sind. Um Felder aus einer verknüpften Entität zurückzugeben, verwenden Sie $expand. Ohne $expand können Sie nicht auf Navigationsattribute über $select zugreifen.

Die folgende Abfrage gibt Arbeitsaufgabe 480 mit allen Feldern aus der erweiterten Iteration Entität zurück:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration

Da keine $select auf die Iteration Erweiterung angewendet wird, enthält die Antwort jedes Iteration Feld:

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "IterationSK": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "StartDate": "2025-12-04T00:00:00-12:00",
        "EndDate": "2025-12-25T23:59:59.999-12:00",
        "IterationLevel1": "Fabrikam Fiber",
        "IterationLevel2": "3Week Sprints",
        "IterationLevel3": "Sprint 3",
        ...
        "Depth": 2,
        "IsEnded": false
      }
    }
  ]
}

Auswahl in expand-Anweisungen verwenden

Um die von einer erweiterten Entität zurückgegebenen Felder einzuschränken, fügen Sie eine $select Klausel in der Verwendung der $expand Syntax $expand=Entity($select=Field1,Field2)hinzu. Die folgende Abfrage erweitert Iteration, gibt jedoch nur IterationName und IterationPath zurück.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath)

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3"
      }
    }
  ]
}

Die folgende Tabelle enthält $expand und $select Beispiele für Typen von allgemeinen Navigationseigenschaften:

Um mehrere Navigationseigenschaften in einer einzelnen Abfrage zu erweitern, verwenden Sie eine durch Trennzeichen getrennte Liste:

$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath)

Verwenden von geschachtelten Expand-Anweisungen

Wenn Sie eine Navigationseigenschaft innerhalb einer bereits erweiterten Entität erweitern möchten, verschachteln Sie eine $expand innerhalb einer anderen. Die folgende Abfrage erweitert Iteration und anschließend Project innerhalb von Iteration, um anzuzeigen, zu welchem Projekt die Iteration gehört.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($expand=Project)

Um geschachtelte Erweiterung mit $select zu kombinieren, verwenden Sie ein Semikolon (;), um innerhalb der Klammern $select von $expand zu trennen. Ohne semikolon gibt die Abfrage einen Fehler zurück. Die folgende Abfrage gibt nur IterationName und IterationPath aus Iteration zurück, und die geschachtelte Project.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath;$expand=Project)

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "Project": {
          "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber"
        }
      }
    }
  ]
}

Datumsspanne abfragen

Die folgende Beispielabfrage gibt Arbeitsaufgaben zurück, deren letztes Änderungsdatum größer oder gleich dem 1. Januar 2025 ist.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-01-01Z

Die folgende Beispielabfrage gibt Arbeitsaufgaben zurück, deren letztes Änderungsdatum in der Woche vom 31. Oktober bis zum 7. November 2025 aufgetreten ist.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-10-31Z and ChangedDate le 2025-11-07Z

Ergebnisse sortieren

Fügen Sie $orderby hinzu, um Ergebnisse nach einer oder mehreren Eigenschaften zu sortieren. Ergebnissortierung in aufsteigender Reihenfolge standardmäßig; anfügen desc für absteigend. Trennen Sie mehrere Sortierfelder durch Kommas.

Nächster Schritt

Verwandte Inhalte

• Erstellen von OData-Abfragen für Analytics
• Aggregieren von Daten mithilfe von Analytics
• Metadatenreferenz für Azure Boards Analytics
• Bewährte Methoden für die Abfrage von Analytics
• Unterstützte OData-Features
• OData v4.0 Teil 2: URL Conventions Plus Errata 02