Definiowanie podstawowych zapytań przy użyciu usługi OData Analytics

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

Możesz użyć analizy dla usługi Azure DevOps, aby skonstruować zapytania OData w celu zwrócenia interesujących Cię danych. Te zapytania można uruchamiać w przeglądarce lub w oprogramowaniu klienckim, na przykład Excel lub Power BI.

Ten artykuł koncentruje się na zapytaniach dotyczących pobierania zestawów jednostek śledzenia pracy usługi Azure Boards, ale zasady dotyczą wykonywania zapytań dotyczących innych zestawów jednostek. Aby uzyskać więcej informacji, zobacz Tworzenie zapytań OData na potrzeby analizy i dokumentacji metadanych dla usługi Azure Boards Analytics.

W tym samouczku pokazano, jak:

Wymagania wstępne

Uzyskaj liczbę elementów

Aby zwrócić tylko liczbę elementów lub jednostek zdefiniowanych w organizacji lub projekcie bez uwzględniania $apply=aggregate($count as Count) innych informacji, zastosuj opcję zapytania. Następujące zapytania zwracają liczbę projektów, elementów roboczych, ścieżek obszaru i użytkowników w organizacji.

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)

Powyższe zapytania zwracają wyniki, jak w poniższym przykładzie dla projektów w organizacji fabrikam.

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

Uzyskaj liczbę elementów i ich dane

Aby zwrócić liczbę elementów wraz z wybranymi danymi dla elementów, określ $count=true opcję zapytania w instrukcji select . Następujące zapytania zwracają liczbę elementów roboczych, ścieżek obszaru i użytkowników zdefiniowanych dla projektu wraz z określonymi właściwościami. Aby uzyskać prawidłowe właściwości, zobacz referencje metadanych dla Azure Boards Analytics oraz referencje metadanych daty kalendarza, projektu i użytkownika dla Azure DevOps Analytics.

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

Na przykład następujące zapytanie żąda liczby użytkowników i nazw użytkowników w projekcie Fabrikam Fiber :

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

Zapytanie zwraca liczbę 5 użytkowników z ich nazwami użytkowników.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Users(UserName)",
  "@odata.count": 5,
  "value": [
    {
      "UserName": "Microsoft.VisualStudio.Services.TFS"
    },
    {
      "UserName": "fabrikamfiber1@hotmail.com"
    },
    {
      "UserName": "Jamal Hartnett"
    },
    {
      "UserName": "fabrikamfiber5@hotmail.com"
    },
    {
      "UserName": "fabrikamfiber2@hotmail.com"
    }
  ]
}

Wybieranie określonych właściwości lub pól

Aby zwrócić określone właściwości lub pola elementu roboczego, dodaj klauzulę, która określa nazwy właściwości $select. Aby na przykład zwrócić identyfikator elementu roboczego, typ elementu roboczego, tytuł i stan elementów roboczych, dodaj klauzulę $select=WorkItemId,WorkItemType,Title,State do zapytania.

Klauzula $select określa nazwy właściwości, które odpowiadają nazwanym polam. Nazwy właściwości w zapytaniach OData wymagają uwagi zarówno odstępów, jak i wielkości liter. Mimo że nazwy wyświetlane właściwości, takie jak identyfikator elementu roboczego , mogą zawierać spacje, formalne nazwy właściwości nie mogą zawierać spacji.

Aby uzyskać więcej informacji na temat nazw i etykiet właściwości, zobacz Dokumentacja metadanych dla usługi Azure Boards. Aby dowiedzieć się, w jaki sposób właściwości pól niestandardowych są oznaczone etykietami, zobacz Właściwości niestandardowe.

Poniższe przykładowe zapytanie żąda identyfikatorów elementów roboczych, tytułów i stanów dla trzech najważniejszych elementów roboczych w projekcie Fabrikam Fiber.

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

Analiza zwraca następujące dane.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikamprime/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)",
  "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"
    }
  ]
}

Filtrowanie danych

Aby przefiltrować zbiór encji w celu zwrócenia określonych elementów, dodaj klauzulę $filter, która określa kryteria, jakie muszą spełniać elementy. Poniższa klauzula filtru zwraca tylko typy elementów roboczych Feature, które znajdują się w stanie W toku.

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

Poniższe przykładowe zapytanie określa, aby zwrócić tylko identyfikator elementu roboczego, typ elementu roboczego, tytuł i stan elementów roboczych typu Funkcja, które znajdują się w stanie W toku.

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'

Określ kilka klauzul filtru

Można użyć funkcji and i or , aby określić kilka filtrów w jednej $select klauzuli. Na przykład następujące zapytanie określa kilka pól z elementów roboczych typów Historia użytkownika, Usterka lub niestandardowego typu Backlog Praca, które znajdują się w stanach Nowy, Zobowiązane lub Aktywne. Użyj nawiasu, aby grupować klauzule filtru zgodnie z potrzebami.

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')

Zapytanie zwraca dane podobne do następujących wyników:

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,AssignedTo,State)",
  "value": [
    {
      "WorkItemId": 210,
      "Title": "Slow response on form",
      "State": "Active"
    },
    ...
    {
      "WorkItemId": 160,
      "Title": "Game store testing",
      "State": "New"
    }
  ]
}

Można również zastosować różne funkcje, takie jak contains, startswithi endswith w $select klauzulach. Zobacz Obsługiwane funkcje.

Właściwości ścieżki obszaru zapytania lub ścieżki iteracji

Aby wyszukać właściwości takie jak AreaSK, IterationSK lub inne, dotyczące określonej ścieżki obszaru lub ścieżki iteracji, użyj następujących zapytań.

Zwróć AreaSK dla określonej ścieżki obszaru

Poniższe zapytanie prosi o właściwość AreaSK zdefiniowaną dla obszaru Fabrikam Fiber\Production Planning\Web ścieżki. Aby wyświetlić inne zdefiniowane właściwości dla zestawu jednostek Obszary , zobacz Obszary.

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

Zapytanie zwraca następujące dane.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikamprime/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Areas(AreaSK)",
  "value": [
    {
      "AreaSK": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
    }
  ]
}

Zwróć IterationSK dla określonej ścieżki iteracji.

Poniższe zapytanie zwraca właściwość IterationSK zdefiniowaną dla ścieżki iteracji Fabrikam Fiber\3Week Sprints\Sprint 3. Aby wyświetlić inne zdefiniowane właściwości zestawu jednostek Iteracji , zobacz Iteracje.

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

Filtruj według właściwości nawigacji

Właściwości nawigacji reprezentują relacje między typami jednostek. Po określeniu właściwości nawigacji w ramach kryteriów filtrowania należy określić pełną ścieżkę dla właściwości nawigacji. Na przykład poniższa klauzula filtruje elementy robocze na podstawie określonej ścieżki iteracji dla Iteration właściwości nawigacji.

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

Iteration jest właściwością nawigacji i IterationPath jest polem zainteresowania. Iteration/IterationPath jest pełną ścieżką właściwości IterationPath.

Przykładowe zapytanie poniżej pobiera dane z pięciu najwyżej ocenianych elementów roboczych w ścieżce iteracji Fabrikam Fiber\3Week Sprints\Sprint 3, określając pełną ścieżkę dla Iteration/IterationPath.

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

Rozwijanie danych z powiązanych jednostek

Poprzednie przykładowe zapytanie nie zwraca Iteration danych, ponieważ Iteration jest powiązaną jednostką. Właściwości nawigacji, takie jak Identity, Areai Iteration nie są bezpośrednio dostępne za pomocą $select instrukcji . Aby zwracać dane z powiązanych jednostek, należy użyć $expand instrukcji .

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

Poniższe przykładowe zapytanie żąda informacji skojarzonych z identyfikatorem 480elementu roboczego, w tym rozszerzonymi Iteration danymi.

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

Zapytanie zwraca następujące dane, w tym wszystkie pola z rozszerzonej Iteration właściwości.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)",
  "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",
        "IterationId": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationName": "Sprint 3",
        "Number": 276,
        "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",
        "IterationLevel4": null,
        "IterationLevel5": null,
        "IterationLevel6": null,
        "IterationLevel7": null,
        "IterationLevel8": null,
        "IterationLevel9": null,
        "IterationLevel10": null,
        "IterationLevel11": null,
        "IterationLevel12": null,
        "IterationLevel13": null,
        "IterationLevel14": null,
        "Depth": 2,
        "IsEnded": false,
        "AnalyticsUpdatedDate": "2025-10-22T17:28:14.7166667Z"
      }
    }
  ]
}

Używanie opcji select w instrukcjach expand

Jeśli rozszerzona właściwość zwraca więcej danych niż chcesz, dodaj instrukcję $select dla tej właściwości.

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

Na przykład, poniższe przykładowe zapytanie wybiera tylko dane IterationName i IterationPath z rozwiniętej właściwości Iteration.

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)

Zapytanie zwraca następujące dane.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration(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"
      }
    }
  ]
}

W poniższej tabeli pokazano, jak używać klauzul $expand i $select do wybierania kilku pól w ramach właściwości nawigacyjnych. Na przykład służy $expand=AssignedTo($select=UserName) do zwracania właściwości Przypisane do pola Nazwa użytkownika we Identity właściwości nawigacji.

Można określić kilka właściwości do rozwinięcia w jednej $expand klauzuli przy użyciu listy rozdzielanej przecinkami.

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

Użyj zagnieżdżonych instrukcji 'expand'

Można użyć zagnieżdżonych poleceń OData $expand. Na przykład następujące zapytanie używa zagnieżdżonych $expand instrukcji do wyświetlania projektu, w którym znajduje się iteracja.

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)

Zapytanie zwraca następujące dane:

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)",
  "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",
        "IterationId": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationName": "Sprint 3",
        "Number": 276,
        "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",
        "IterationLevel4": null,
        "IterationLevel5": null,
        "IterationLevel6": null,
        "IterationLevel7": null,
        "IterationLevel8": null,
        "IterationLevel9": null,
        "IterationLevel10": null,
        "IterationLevel11": null,
        "IterationLevel12": null,
        "IterationLevel13": null,
        "IterationLevel14": null,
        "Depth": 2,
        "IsEnded": false,
        "AnalyticsUpdatedDate": "2025-10-22T17:28:14.7166667Z",
        "Project": {
          "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber",
          "AnalyticsUpdatedDate": "2025-10-28T20:27:13.5833333Z",
          "ProjectVisibility": "Private"
        }
      }
    }
  ]
}

Możesz dodać $select wyrażenia, na przykład, aby zwrócić tylko IterationName oraz IterationPath z Iteration.

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)

To zapytanie zwraca następujące dane:

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration(IterationName,IterationPath,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": {
          "ProjectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber",
          "AnalyticsUpdatedDate": "2025-10-28T20:27:13.5833333Z",
          "ProjectVisibility": "Private"
        }
      }
    }
  ]
}

Wyniki pokazują tylko IterationName i IterationPath z Iteration, a Project jako zagnieżdżony obiekt w wynikach Iteration.

Wykonywanie zapytań względem zakresu dat

Poniższe przykładowe zapytanie zwraca elementy robocze, których ostatnia data zmiany jest większa lub równa 1 stycznia 2025 r.

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

Poniższe przykładowe zapytanie zwraca elementy robocze, których ostatnia data zmiany miała miejsce w tygodniu od 31 października do 7 listopada 2025 r.

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

Sortowanie wyników

Określ opcję sortowania $orderby wyników lub określ sekwencję zwracania wyników. Można sortować w kolejności rosnącej lub malejącej przy użyciu słów kluczowych asc lub desc. W poniższej tabeli przedstawiono kilka przykładów.

Następny krok

Treści powiązane

• Konstruowanie zapytań OData na potrzeby analizy
• Odniesienie do metadanych dla usługi Azure Boards Analytics
• Najlepsze praktyki przy wykonywaniu zapytań w Analytics
• Obsługiwane funkcje OData
• Specyfikacja OData w wersji 4.0
• OData v4.0 — część 2: Konwencje adresów URL Plus Errata 02