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

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

Pomocí Analytics pro Azure DevOps můžete vytvořit základní a filtrované dotazy, které vrátí data, která vás zajímají. Tyto dotazy můžete spouštět přímo v prohlížeči nebo v Power BI.

Tento článek sestaví informace poskytnuté v dotazech OData pro analýzu a metadata pro Azure Boards Analytics. Dotazy v tomto článku se také zaměřují na načítání sad entit sledování práce, ale zásady platí pro dotazování jiných sad entit.

V tomto článku se dozvíte, jak definovat dotazy, které vracejí následující data:

  • Počet položek (žádná jiná data)
  • Počet položek a dat
  • Vlastnosti definované pro oblasti nebo cesty iterace
  • Vybrané sloupce nebo pole
  • Filtrovaná data
  • Vrácení dat pro pole Cesta k identitě, cestě oblasti a cestě iterace
  • Filtrování podle navigační vlastnosti
  • Dotazování rozsahu dat
  • Vnoření příkazů rozbalení
  • Řazení výsledků, možnost orderby

Poznámka:

Služba Analytics je automaticky povolená a podporovaná v produkčním prostředí pro všechny služby Azure DevOps Services. Integrace Power BI a přístup k datovému kanálu OData služby Analytics jsou obecně dostupné. Doporučujeme, abyste ho používali a poskytli nám zpětnou vazbu. Dostupná data jsou závislá na verzi. Nejnovější podporovaná verze 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, abyste ho používali a poskytli nám zpětnou vazbu. Pokud jste upgradovali 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 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 je ve verzi Preview pro Azure DevOps Server 2019. Můžete ji povolit nebo nainstalovat pro kolekci projektů. Integrace Power BI a přístup k datovému kanálu OData služby Analytics jsou ve verzi Preview. Doporučujeme, abyste ho používali a poskytli nám zpětnou vazbu.

Dostupná data jsou závislá na verzi. Nejnovější podporovaná verze 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

  • Pokud chcete zobrazit data Analýzy a dotazovat se na službu, musíte být členem projektu se základním přístupem nebo novějším. Ve výchozím nastavení mají všichni členové projektu udělená oprávnění k dotazování analýzy a definování zobrazení Analýzy.
  • 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:

V tomto článku je definována adresa URL dotazu OData pro Azure DevOps Services. Pokud chcete vytvořit podobný dotaz pro místní server, přečtěte si pokyny uvedené v dotazech OData konstruktoru pro analýzu. Doporučujeme vám upravit dotazy poskytované pro vaši organizaci a projekt, abyste se seznámili s dotazováním OData pomocí prohlížeče.

Vrácení počtu položek (žádná jiná data)

Pokud se chcete dozvědět o počtu položek nebo entit definovaných v organizaci nebo projektu, zadejte $apply=aggregate($count as Count) možnost dotazu. Například následující dotazy vrátí počet projektů, pracovních položek, cest oblastí a uživatelů definovaných pro 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)

Tip

Dotazy napříč projekty selžou, když uživatel, který dotaz spouští, nemá přístup ke všem projektům. Přečtěte si další informace o požadavcích v dotazech v Projectu a dotazech v oboru organizace.

Počet projektů

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

Počet pracovních položek

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)"
value	
  0	
     @odata.id	null
     Count	    1166

Počet oblastí

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value	
  0	
     @odata.id	null
     Count	    70

Počet uživatelů

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

Vrácení počtu položek a dat

Pokud chcete vrátit počet položek spolu s vybranými daty pro položky, zadejte $count=true možnost dotazu. Například následující dotazy vrátí počet pracovních položek, cest oblastí a uživatelů definovaných pro projekt spolu se zadanými vlastnostmi. Platné vlastnosti najdete v referenčních informacích k metadatám pro azure Boards Analytics a kalendářní datum, projekt a uživatelská metadata pro Azure DevOps Analytics.

Tip

Pokud nezadáte vlastnosti, které se mají vrátit, vrátí Analýza všechny vlastnosti definované pro zadaný typ entity.

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

Vlastnosti oblastí nebo iterací

Pokud chcete vyhledat AreaSK nebo IterationSKnebo jinou vlastnost cesty oblasti nebo cesty iterace, použijte následující dotazy.

Vrácení areaSK pro konkrétní cestu k oblasti

Následující dotaz určuje vrácení AreaSK vlastnosti definované pro Fabrikam Fiber\Service Delivery\InternetArea Path. Pokud chcete zadat další vlastnosti definované pro Areas sadu entit, přečtěte si referenční informace k metadatům pro analýzy Azure Boards, oblasti.

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

Dotaz vrátí následující data.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Areas(AreaSK)",
  "value": [
    {
      "AreaSK": "637dc203-0549-4415-9663-b6358ac27d21"
    }
  ]
}

Vrácení iteračního znaku (ITerationSK) pro konkrétní cestu iterace

Následující dotaz určuje vrácení IterationSK vlastnosti definované pro cestu iterace Fabrikam Fiber\Release 1\Sprint 3. Pokud chcete zadat další vlastnosti definované pro Iterations sadu entit, přečtěte si referenční informace k metadatům pro Azure Boards Analytics a 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

Dotaz vrátí následující data.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Iterations(IterationSK)",
  "value": [
    {
      "IterationSK": "862e961a-ac7a-4fcc-9ebc-8afd0c12fed5"
    }
  ]
}

Vrácení konkrétních vlastností nebo polí

Pokud chcete vrátit konkrétní vlastnosti nebo pole pracovních položek, přidejte $select klauzuli, která určuje názvy vlastností.

Pokud chcete například vrátit ID pracovní položky, typ pracovní položky, název a stav pracovních položek, přidejte do dotazu následující klauzuli. Tato klauzule určuje vlastnosti, které odpovídají pojmenovaným polím.

Poznámka:

Názvy vlastností neobsahují žádné mezery. Pokud přidáte mezery, dotaz se nezdaří. Dotazy OData vyžadují pozornost jak pro mezery, tak velikost písmen. Informace o tom, jak jsou vlastnosti vlastního pole označené, najdete v referenčních informacích k metadatům pro Azure Boards, vlastní vlastnosti.

Tady určíme, že se mají vrátit první tři pracovní položky.

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

Analýza vrátí následující data.

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value	
   0	
      WorkItemId    462
      Title         "Test case"
      WorkItemType  "Test Case"
      State         "Design"
   1	
      WorkItemId	   491
      Title          "Change color settings"
      WorkItemType   "Shared Steps"
      State          "Active"
   2	
      WorkItemId	   461
      Title          "Test impediment"
      WorkItemType   "Impediment"
      State          "Open"

.

Filtrování dat

Pokud chcete filtrovat entitu nastavenou tak, aby vracela vybrané položky, zadejte $filter klauzuli, která určuje kritéria, která musí položky splňovat. Na základě posledního dotazu zde přidáme klauzuli filtru, která vrátí pouze typy pracovních položek funkce , které jsou ve stavu Probíhá .

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

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

Analýza vrátí následující data.

  
@odata.context	"https://analytics.dev.azure.com/kelliott/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,State)"
value	
  0	
      WorkItemId	380
      Title	"Refresh web look, feel, performance factors"
      State	"In Progress"
  1	
      WorkItemId	480
      Title	"Customer Phone - Phase 1"
      State	"In Progress"
  2	
      WorkItemId	493
      Title	"Change initial view"
      State	"In Progress"
  3	
      WorkItemId	479
      Title	"Customer Web - Phase 1"
      State	"In Progress"
  4	
      WorkItemId	551
      Title	"Mobile feedback"
      State	"In Progress"

Zadání několika klauzulí filtru

Můžete použít AND a OR zadat několik klauzulí filtru.

Například následující dotaz určuje, že se mají vracet pracovní položky typu Uživatelský scénář, Chyba a Práce backlogu (vlastní typ pracovní položky), které jsou ve stavu Nové, Potvrzeno nebo Aktivní . Pomocí závorek můžete podle potřeby seskupit klauzule filtru.

Kromě toho můžete použít různé funkce, jako containsje , startswithendswith a další. Viz podporované funkce a klauzule OData, Podporované funkce.

Vrácení dat pro pole Cesta k identitě, cestě oblasti a cestě iterace

Výběrové vlastnosti jsou přidružené k navigačním vlastnostem a nejsou přímo přístupné pomocí příkazu $select . K vrácení dat, která vás zajímají, musíte použít $expand příkaz. Tyto vlastnosti jsou často spojeny s několika vlastními vlastnostmi. Pomocí polí Identita můžete například zadat, aby se vrátilo uživatelské jméno nebo e-mail uživatele.

Následující tabulka obsahuje příklady, jak rozbalit několik těchto vlastností.

Pole typu Odkazovaná vlastnost Příklady klauzulí, které se mají zahrnout
DateTime 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)

Chcete-li zadat několik vlastností, které je třeba rozbalit, zadáte je v jediné rozbalovací klauzuli v seznamu oddělených čárkami.

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

Filtrování podle navigační vlastnosti

Když jako součást kritérií filtru zadáte navigační vlastnost, musíte ji zadat v požadovaném formátu.

Například následující klauzule určuje filtrování pracovních položek na základě iterace 1 definované pro projekt.

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

V tomto příkladu Iteration je název navigační vlastnosti a IterationPath odpovídá úplné cestě pro iteraci. Chcete-li použít jinou entitu jako filtr, umístěte navigační vlastnost následovanou lomítkem následovaným názvem pole, podle které chcete filtrovat.

A tady je úplný dotaz OData:

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

Tady je další příklad, který požaduje prvních pět pracovních položek v cestě Fabrikam Fiber\Service Delivery\Voice Area Path.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Area/AreaPath eq 'Fabrikam Fiber\Service Delivery\Voice'&$select=WorkItemId, WorkItemType, Title, State&$orderby=WorkItemId asc

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value	
  0	
     WorkItemId	361
     Title        "Hello World Web Site"
     WorkItemType	"Product Backlog Item"
     State        "Removed"
  1	
     WorkItemId	362
     Title        "Resume"
     WorkItemType	"Product Backlog Item"
     State        "New"
  2	
     WorkItemId	363
     Title        "Welcome back page"
     WorkItemType	"Product Backlog Item"
     State        "Done"
  3	
     WorkItemId	365
     Title        "Pause"
     WorkItemType	"Feature"
     State        "New"
  4	
     WorkItemId	374
     Title        "Fix performance issues"
     WorkItemType	"Task"
     State        "To Do"

Tip

Navigační vlastnost nelze použít přímo v $select příkazu. Místo toho musíte použít $expand.

Předchozí příklad filtrování pro cestu iterace nevrací cestu iterace, protože je obsažen v související entitě. Pokud chcete vrátit data v související entitě, přidejte příkaz $expand :

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

Tady je příklad, který vrací informace přiřazené k pracovní položce s ID 480.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&&$expand=Iteration
   
@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)"
value	
  0	
      WorkItemId           480
      Title                "Customer Phone - Phase 1"
      WorkItemType	       "Feature"
      State	               "In Progress"
      Iteration	
          ProjectSK	       "56af920d-393b-4236-9a07-24439ccaa85c"
          IterationSK	       "c7063041-ff3a-4d7f-bb46-c433c7030d59"
          IterationId	       "c7063041-ff3a-4d7f-bb46-c433c7030d59"
          IterationName	   "Sprint 1"
          Number	            55297
          IterationPath	    "Fabrikam Fiber\\Release 1\\Sprint 1"
          StartDate	        "2022-01-17T00:00:00-08:00"
          EndDate	            "2022-02-04T23:59:59.999-08:00"
          IterationLevel1	    "Fabrikam Fiber"
          IterationLevel2	    "Release 1"
          IterationLevel3	    "Sprint 1"
          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	        	true
      AnalyticsUpdatedDate	"2022-01-18T22:18:58.17Z"

Jak vidíte, cesta iterace se ve výsledku rozbalí a vrátí se všechna data iterace. Pravděpodobně je to více dat, než chcete.

Pokud chcete vrátit méně dat, přidejte $select také příkaz proti iteraci:

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

Pak vrátí následující data.

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

Dotazování rozsahu dat

Následující příklad vrátí pracovní položky, jejichž změněné datum je větší než 1. ledna 2021.

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

Následující příklad vrátí pracovní položky, jejichž změněné datum nastane v týdnu od 26. do 30. dubna 2021.

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

Vnoření příkazů rozbalení

V OData můžete vnořit $expand příkazy. Můžete například napsat předchozí příkaz dotazu, který zobrazí projekt, na kterém je iterace součástí:

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

Vrátí následující JSON:

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

Můžete také kombinovat $expand a $select příkazy. Předchozí dotaz můžete například změnit tak, aby vracel pouze název iterace a cestu iterace:

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

Vrátí následující JSON:

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

Všimněte si, že výsledek zde zobrazuje pouze IterationId a IterationPath a že Project je vnořený objekt ve výsledku JSON. Další klíčovou položkou k poznámce je samotná adresa URL. Při použití $select příkazu a $expand klauzule je nutné použít středník (;) před $expand. Cokoli jiného způsobí chybu.

Seřadit výsledky, orderby možnost

$orderby Zadejte možnost řazení výsledků nebo určete posloupnost, ve které se vrátí výsledky. Můžete řadit vzestupně nebo sestupně pomocí klíčových slov asc nebo descv uvedeném pořadí. Tady je několik příkladů.

Seřadit podle Klauzule, která se má zahrnout
ID pracovní položky /WorkItems?$orderby=WorkItemId
ID pracovní položky sestupně /WorkItems?$orderby=WorkItemId desc
Typ a stav pracovní položky /WorkItems?$orderby=WorkItemType,State

Další kroky