Definování základních dotazů pomocí OData Analytics

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

Pomocí dotazů Analytics OData můžete načítat data sledování práce z Azure DevOps v prohlížeči nebo v klientských nástrojích, jako je Excel a Power BI. Tento článek popisuje počítání položek, výběr konkrétních polí s $select, filtrování s $filter, rozbalení navigačních vlastností s $expand, dotazování rozsahů kalendářních dat a řazení pomocí $orderby.

Návod

Můžete použít AI k pomoci s tímto úkolem dále v tomto článku, nebo si můžete prostudovat Povolit asistenci AI s Azure DevOps MCP Serverem pro začátek.

Příklady se zaměřují na sady entit pro sledování úkolů v Azure Boards, avšak tytéž principy platí i pro jiné sady entit. Další informace najdete v tématu Vytváření dotazů OData pro analýzy a metadata pro Azure Boards Analytics.

Poznámka:

Služba Analytics je automaticky povolená a podporovaná v produkčním prostředí pro všechny služby v rámci Azure DevOps Services. Integrace Power BI a přístup k datovému kanálu OData služby Analytics jsou obecně dostupné. Doporučujeme používat datový kanál OData Analytics a poskytovat zpětnou vazbu.

Dostupná data jsou závislá na verzi. Nejnovější podporovaná verze rozhraní OData API je v2.0a nejnovější verze Preview je v4.0-preview. Další informace najdete v tématu Správa verzí rozhraní API OData.

Poznámka:

Služba Analytics se automaticky nainstaluje a podporuje v produkčním prostředí pro všechny nové kolekce projektů pro Azure DevOps Server 2020 a novější verze. Integrace Power BI a přístup k datovému kanálu OData služby Analytics jsou obecně dostupné. Doporučujeme používat datový kanál OData Analytics a poskytovat zpětnou vazbu. Pokud upgradujete z Azure DevOps Serveru 2019, můžete během upgradu nainstalovat službu Analytics.

Dostupná data jsou závislá na verzi. Nejnovější podporovaná verze rozhraní OData API je v2.0a nejnovější verze Preview je v4.0-preview. Další informace najdete v tématu Správa verzí rozhraní API OData.

Požadavky

Kategorie Požadavky
úrovně přístupu - Člen projektu.
Alespoň základní přístup.
Oprávnění Ve výchozím nastavení mají členové projektu oprávnění provádět dotazy v Analytice a vytvářet zobrazení. Další informace o dalších požadavcích týkajících se povolení služeb a funkcí a obecných aktivit sledování dat najdete v tématu Oprávnění a požadavky pro přístup k Analýzám.

Poznámka:

  • Dotazy mezi projekty selžou, když uživatel, který dotaz spouští, nemá přístup ke všem projektům. Další informace najdete v tématu Projektové a organizační dotazy.
  • Příklady v tomto článku používají formát adresy URL služby Azure DevOps Services: https://analytics.dev.azure.com/{OrganizationName}/. Pro Azure DevOps Server použijte místo toho https://{servername}/{CollectionName}/. Další informace najdete v tématu Vytváření dotazů OData pro analýzu.

Získání počtu položek

Pokud chcete vrátit pouze počet bez jiných dat, připojte $apply=aggregate($count as Count) k libovolné adrese URL sady entit. Například následující dotazy sčítají projekty, pracovní položky, cesty oblastí a uživatele v organizaci:

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)

Dotaz Projects pro fabrikam organizaci vrátí:

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

Získání počtu položek a jejich dat

Pokud chcete vrátit počet společně s daty, přidejte $count=true ho do dotazu, který obsahuje klauzuli $select . Následující dotazy vrátí počet a vybrané vlastnosti pro pracovní položky, oblastní cesty a uživatele v rámci projektu:

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

Poznámka:

Vždy zahrňte $select nebo $apply do dotazu. Vynechání obou triggerů aktivuje upozornění a může zasáhnout limity využití.

Platné názvy vlastností najdete v referenčních informacích k metadatám pro azure Boards Analytics a kalendářní datum, projekt a referenční informace o metadatech uživatelů.

Například následující dotaz vrátí počet a uživatelská jména v projektu Fabrikam Fiber :

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

Odpověď zahrnuje celkový počet v @odata.count a odpovídající záznamy v 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" }
  ]
}

Výběr konkrétních vlastností nebo polí

Přidejte klauzuli $select , která vrátí jenom vlastnosti, které potřebujete. V názvech vlastností se rozlišují malá a velká písmena, nemůžou obsahovat mezery a odpovídají názvům polí pracovních položek. Například $select=WorkItemId,WorkItemType,Title,State vrátí tato čtyři pole.

Pro vyhledávání názvů vlastností, včetně vlastních polí, viz referenční informace k metadatům pro Azure Boards.

Následující dotaz vrátí ID, typ, název a stav prvních tří pracovních položek v projektu Fabrikam Fiber:

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

Filtrování dat

Přidejte klauzuli $filter , která vrátí pouze položky, které odpovídají konkrétním kritériím. Použijte relační operátory jako eq, ne, gt, ge, lt a le a kombinujte podmínky s and a or. Například následující dotaz vrátí probíhající funkce:

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'

Kombinování více podmínek filtru

Pomocí závorek můžete seskupit or podmínky v rámci širšího and filtru. Následující dotaz vrátí uživatelské scénáře, chyby a vlastní typ v konkrétních stavech:

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

Můžete také použít řetězcové funkce, jako contains, startswith a endswith ve výrazech filtru. Další informace naleznete v tématu Podporované funkce.

Vlastnosti cesty oblasti dotazu nebo cesty iterace

Některé dotazy vyžadují náhradní klíč (AreaSK nebo IterationSK) místo řetězce cesty. Pomocí sad entit Oblasti nebo Iterace vyhledejte klíč pro konkrétní cestu.

Vrátit AreaSK pro konkrétní cestu k oblasti

Následující dotaz vrátí AreaSK pro cestu oblasti Fabrikam Fiber\Production Planning\Web. Další dostupné vlastnosti naleznete v části Oblasti.

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

Vrátit IterationSK pro konkrétní cestu iterace

Následující dotaz vrátí IterationSK pro Fabrikam Fiber\Release 1\Sprint 3 cestu iterace. Další dostupné vlastnosti najdete v tématu Iterace.

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

Filtrovat podle navigačních vlastností

Navigační vlastnosti, jako je Iteration, Areaa AssignedTo představují vztahy s jinými entitami. Pokud chcete filtrovat pole ze související entity, použijte úplnou cestu ve formátu NavigationProperty/Field. Například Iteration/IterationPath odkazuje na IterationPath pole prostřednictvím Iteration navigační vlastnosti:

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

Následující dotaz vrátí prvních pět pracovních položek v konkrétní iteraci pomocí úplné navigační cesty:

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

Filtrování podle navigační vlastnosti neobsahuje data v odpovědi. Chcete-li vrátit pole ze související entity, použijte $expand. Bez $expand, nemůžete získat přístup k polím navigační vlastnosti prostřednictvím $select.

Následující dotaz vrátí pracovní položku 480 se všemi poli z rozbalené Iteration entity:

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

Jelikož se na $select rozšíření nepoužije Iteration, odpověď obsahuje každé Iteration pole:

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

Použijte příkaz select v příkazech expand

Pokud chcete omezit pole vrácená z rozbalené entity, přidejte klauzuli $select do $expand s použitím syntaxe $expand=Entity($select=Field1,Field2). Následující dotaz se rozšíří Iteration, ale vrátí pouze IterationName a IterationPath:

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

Následující tabulka ukazuje $expand s příklady $select běžných typů navigačních vlastností.

Typ navigace Klíčová vlastnost Ukázkové klauzule
Datum a čas DateSK $expand=CreatedDate($select=Date) nebo
$expand=CreatedDate($select=WeekStartingDate)
Identita UserSK $expand=AssignedTo($select=UserName) nebo
$expand=AssignedTo($select=UserEmail)
Plocha AreaSK $expand=Area($select=AreaName) nebo
$expand=Area($select=AreaPath)
Iterace IterationSK $expand=Iteration($select=IterationName) nebo
$expand=Iteration($select=IterationPath) nebo
$expand=Iteration($select=StartDate)
Projekt ProjectSK $expand=Project($select=ProjectName)
Tým TeamSK $expand=Teams($select=TeamName)

Pokud chcete v jednom dotazu rozbalit více navigačních vlastností, použijte seznam oddělený čárkami:

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

Použijte vnořené příkazy expand

Pokud chcete rozbalit navigační vlastnost v rámci již rozbalené entity, vnořte jeden $expand do druhého. Následující dotaz rozbalí Iteration a pak rozbalí Project v rámci Iteration pro zobrazení, ke kterému projektu iterace patří.

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)

Chcete-li zkombinovat vnořené rozšíření s $select, použijte středník (;) k oddělení $select od $expand uvnitř závorek. Bez středníku vrátí dotaz chybu. Následující dotaz vrátí pouze IterationName a IterationPath z Iteration, plus vnořený 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"
        }
      }
    }
  ]
}

Dotaz na časové období.

Následující příklad dotazu vrátí pracovní položky, jejichž datum poslední změny je větší nebo rovno 1. lednu 2025.

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

Následující příklad dotazu vrátí pracovní položky, jejichž poslední změněné datum nastalo v týdnu od 31. října do 7. listopadu 2025.

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

Řazení výsledků

Přidejte $orderby k seřazení výsledků podle jedné nebo více vlastností. Výsledky jsou ve výchozím nastavení seřazeny vzestupně; pro sestupné řazení přidejte desc. Oddělte více polí řazení čárkami.

Seřadit podle Klauzule
ID pracovní položky /WorkItems?$orderby=WorkItemId
ID pracovní položky (od nejnovějšího) /WorkItems?$orderby=WorkItemId desc
Typ pracovní položky a stav /WorkItems?$orderby=WorkItemType,State

Použití AI k sestavení dotazů OData

Pokud nakonfigurujete Azure DevOps MCP Server, můžete pomocí asistentů AI vytvářet a řešit potíže s dotazy OData.

Příklady výzev

Úkol Příklad výzvy
Vytvoření dotazu Write an OData query that returns all active bugs with their area path and assigned-to fields in <Contoso> project
Filtrovat podle data Create an OData query that returns work items created in the last 30 days in <Contoso> project
Rozbalit navigační vlastnosti Write an OData query that expands the iteration path and area path for user stories in <Contoso> project
Ladění dotazu My OData query returns no results — help me troubleshoot the filter clause and URL format for <Contoso> project
Vnořené rozbalení Write an OData query with nested expand to return work items with their parent details in <Contoso> project
Řazení a omezení výsledků Create an OData query that returns the 20 most recently changed bugs ordered by changed date in <Contoso> project
Počet podle typu pracovní položky Write an OData query that counts work items grouped by work item type for <Contoso> project
Filtrování s řetězcovými funkcemi Create an OData query that returns work items whose title contains "login" in <Contoso> project
Kombinace výběru, filtrování a rozšíření Write an OData query that returns the title, state, assigned-to name, and iteration path for all user stories in the current sprint in <Contoso> project

Další krok

Dotazy v oboru projektu a organizace

Související obsah

  • Last updated on