Vytváření dotazů OData pro Analytics v Azure DevOps

  • Článek

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

Analýza, platforma pro vytváření sestav pro Azure DevOps, může odpovídat na kvantitativní otázky týkající se předchozího nebo současného stavu vašich projektů. Analýza podporuje dotazy OData na metadata a data sady entit. Cvičením jednoduchých dotazů z webového prohlížeče se můžete seznámit s datovým modelem a procesem dotazů.

V tomto článku se dozvíte následující:

  • Vytvoření dotazu Analytics OData pro cloud nebo místní prostředí
  • Jak dotazovat metadata Analýzy
  • Jak dotazovat Analytics OData pro sadu entit
  • Které možnosti dotazu jsou podporované a doporučená posloupnost
  • Při vynucení stránkování na straně serveru

Analýzu můžete dotazovat z libovolného podporovaného webového prohlížeče. Další nástroje, které můžete použít k dotazování analytics, najdete v tématu Analytické nástroje pro dotazy.

Poznámka:

OData, protokol na úrovni aplikace pro interakci s daty prostřednictvím rozhraní RESTful (kde REST=Representational State Transfer) podporuje popis datových modelů a úpravy a dotazování dat podle těchto modelů. Entity Data Model (EDM) nebo metadata popisují informace dostupné z Analýzy, včetně entit, typů entit, vlastností, relací a výčtů, které používáte k dotazování dat na vytváření sestav. Přehled OData najdete v tématu Vítá vás 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.

Komponenty adresy URL pro dotazování na metadata

Analýza zveřejňuje model entit na adrese URL metadat, která je vytvořená připojením $metadata k kořenové adrese URL služby. Analýza poskytuje kořeny služeb pro projekt nebo celou organizaci v Azure DevOps.

Dotazem na metadata můžete vyhledat libovolný z následujících datových prvků.

  • Typy entit a sady entit
  • Vlastnosti a navigační vlastnosti
  • Náhradní klíče
  • Výčtové seznamy
  • Entityset
  • Kontejnery
  • Funkce filtru (Org.OData.Capabilities.V1.FilterFunctions)
  • Podporované agregace (Org.OData.Aggregation.V1.ApplySupported)
  • Podpora služby Batch (Org.OData.Capabilities.V1.BatchSupportType)

Adresa URL, kterou používáte, závisí na tom, jestli dotazujete data pro Azure DevOps Services (cloud) nebo místní Azure DevOps Server.

Pokud chcete dotazovat metadata pro organizaci nebo projekt hostovaný v cloudu, zadejte syntaxi adresy URL, jak je znázorněno níže ve webovém prohlížeči. Nahraďte {OrganizationName} název organizace a {ProjectName} název projektu, který chcete dotazovat. Pokud chcete vrátit všechna metadata pro organizaci, nezadávejte název projektu.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/version/$metadata 
\______________________________/\______________________________/\______________/\_________/
               |                                 |                       |           |
    Analytics service root URL         Organization/Project        OData version  return metadata

Poznámka:

Nejnovější verze Analytics OData je v4.0-preview. Tuto verzi můžete použít pro všechny dotazy na hostované služby. Další informace o verzích Analytics a dostupných datech najdete v tématu Datový model pro Analýzu.

Tady je příklad pro organizaci fabrikam hostované ve službě Azure DevOps Services.

https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata

Interpretace odpovědi na metadata

Analýza vrátí soubor XML datového modelu. Pomocí funkce vyhledávání v prohlížeči můžete najít informace specifické pro entitu, která vás zajímá.

Tip

V závislosti na prohlížeči, který používáte, může nebo nemusí být tento soubor naformátovaný čitelným způsobem. Pokud není formátovaný, můžete najít bezplatný online formátovací modul XML prostřednictvím vyhledávání ve webovém prohlížeči.

Dvě hlavní schémata definovaná v metadatech Analýzy jsou Microsoft.VisualStudio.Services.Analytics.Model, která definují typy entit a výčtové typy a jejich členy a Default schéma, které definuje kontejnery entit a sady entit a podporované filtry OData, transformace a vlastní agregační funkce. Další informace najdete v tématu Analýza metadat OData.

<?xml version="1.0" encoding="UTF-8"?>
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
    <edmx:DataServices>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Microsoft.VisualStudio.Services.Analytics.Model">
           <EntityType Name="Entity Name"/>
        </Schema>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Default">
           <EntityContainer Name="Container"/>
        </Schema>
    </edmx:DataServices>
</edmx:Edmx>

Všechny typy entit jsou přidruženy k vlastnostem a navigačním vlastnostem. Dotazy sad entit můžete filtrovat pomocí obou těchto typů vlastností. Jsou uvedeny v metadatech pod položkou EntityTypePropertyNavigationalPropertynebo . Související entity slouží k určení dalších filtrů, jako jsou cesty iterace, cesty oblastí nebo týmy.

Následující fragment kódu poskytuje částečné zobrazení metadat entity WorkItem . Vlastnosti odpovídají poli pracovní položky a také konkrétním datům zachyceným analýzou, například LeadTimeDays a CycleTimeDays. Vlastnosti navigace odpovídají jiným sadám entit nebo konkrétním analytickým datům zachyceným pro typ entity, například Revisions, Links, Childrena Parent.

<Key>
   <PropertyRef Name="WorkItemId"/>
</Key>
<Property Name="WorkItemId" Type="Edm.Int32" Nullable="false">
   <Annotation Term="Ref.ReferenceName" String="System.Id"/>
   <Annotation Term="Display.DisplayName" String="Work Item Id"/>
</Property>
<Property Name="InProgressDate" Type="Edm.DateTimeOffset">
   <Annotation Term="Display.DisplayName" String="InProgress Date"/>
   </Property>
<Property Name="CompletedDate" Type="Edm.DateTimeOffset">
   <Annotation Term="Display.DisplayName" String="Completed Date"/>
   </Property>
<Property Name="LeadTimeDays" Type="Edm.Double">
   <Annotation Term="Display.DisplayName" String="Lead Time Days"/>
</Property>
<Property Name="CycleTimeDays" Type="Edm.Double">
   <Annotation Term="Display.DisplayName" String="Cycle Time Days"/>
</Property>
<Property Name="InProgressDateSK" Type="Edm.Int32"/>
<Property Name="CompletedDateSK" Type="Edm.Int32"/>
<Property Name="AnalyticsUpdatedDate" Type="Edm.DateTimeOffset"/>
<Property Name="ProjectSK" Type="Edm.Guid" Nullable="false"/>
<Property Name="WorkItemRevisionSK" Type="Edm.Int32" Nullable="false"/>
...
<NavigationProperty Name="BoardLocations" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.BoardLocation)"/>
<NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>
<NavigationProperty Name="InProgressOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="InProgressDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="CompletedOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="CompletedDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="Revisions" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemRevision)"/>
<NavigationProperty Name="Links" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemLink)"/>
<NavigationProperty Name="Children" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Parent" Type="Microsoft.VisualStudio.Services.Analytics.Model.WorkItem">
<ReferentialConstraint Property="ParentWorkItemId" ReferencedProperty="WorkItemId"/>
</NavigationProperty>
<NavigationProperty Name="Processes" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Process)"/>
<NavigationProperty Name="Descendants" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project" Nullable="false">
<ReferentialConstraint Property="ProjectSK" ReferencedProperty="ProjectSK"/>
<Annotation Term="Display.DisplayName" String="Project"/>
...

Komponenty adresy URL pro dotazování entit

Pokud chcete dotazovat data Analytics a vytvářet sestavy, obvykle dotazujete sadu entit. Přehled podporovaných entit najdete v tématu Analýza metadat OData.

Následující adresa URL se používá k dotazování konkrétního EntitySettypu , například WorkItems, WorkItemSnapshota PipelineRuns.

https://analytics.dev.azure.com/OrganizationName/ProjectName/_odata/version/EntityType?{Query-options}
\______________________________/\__________________________/ \____________/\_________/\_____________/
               |                             |                    |               |          |
    Analytics service root URL     Organization/Project      OData version    Entity   Query parts

Tady je příklad pro organizaci fabrikam , která vrací počet pracovních položek definovaných pro projekt Fabrikam Fiber.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?%20$apply=aggregate($count%20as%20Count)

Příklad vrátí 1399 pracovních položek.

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

Poznámka:

Pokud nezadáte $select klauzuli nebo $apply klauzuli, zobrazí se upozornění, například "VS403507: The specified query does not include a $select or $apply clause which is recommended for all queries. Details on recommended query patterns are available here: https://go.microsoft.com/fwlink/?linkid=861060." je ekvivalentní k provedení příkazu select pro sadu entit a vrácení všeho, všech sloupců a všech řádků. Pokud máte velký počet záznamů, může to trvat několik sekund. Pokud máte více než 10 000 pracovních položek, vynutí se stránkování řízené serverem.

Abyste se vyhnuli limitům využití, vždy uveďte klauzuli $select nebo $apply klauzuli.

Informace o vlastnosti metadat entity a relaci najdete v následujících článcích:

Příklad: Dotazování konkrétní sady entit

Dotazování konkrétní sady entit, například WorkItems, Areasnebo Projects, přidat název sady entit: /WorkItems, /Areasnebo /Projects. Úplný seznam sad entit najdete v tématu Datový model pro analýzu.

Seznam projektů definovaných pro vaši organizaci můžete získat například dotazováním /Projects a výběrem možnosti vrácení ProjectName vlastnosti. V organizaci fabrikam je adresa URL uvedená níže.

  https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/Projects?$select=ProjectName

Analýza vrátí názvy projektů těchto projektů definovaných pro organizaci fabrikam .

{
@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(ProjectName)",

"value": [
   {
      "ProjectName": "Basic Fabrikam"
   },
   {
      "ProjectName": "Fabrikam Fiber"
   },
   {
      "ProjectName": "MyFirstProject"
   },
   {
      "ProjectName": "Fabrikam Test"
   },
   {
      "ProjectName": "MyPublicProject"
   }
 ]
}

Možnosti proxy

Možnost dotazu je sada parametrů řetězce dotazu použitých u prostředku, který může pomoct řídit množství dat vrácených pro prostředek v adrese URL.

Možnosti dotazu by se měly zadat v pořadí uvedeném v následující tabulce.

Možnost dotazu Notes
$apply Sada transformací, které můžete použít u dotazu, například: filter, groupbyaggregate, , computeexpand,concat
Příklady najdete v tématu Agregace dat sledování práce pomocí Analýzy.
$compute Podporovaná funkce OData, kterou můžete zadat k definování počítaných vlastností, které lze použít v objektu ,$filter, nebo $orderby výrazu$select.
$filter Slouží k filtrování seznamu vrácených prostředků. Výraz zadaný $filter pomocí se vyhodnocuje pro každý prostředek v kolekci a do odpovědi se zahrnou pouze položky, ve kterých se výraz vyhodnotí jako true. Prostředky, pro které se výraz vyhodnotí jako false nebo null nebo které odkazují na vlastnosti, které nejsou k dispozici kvůli oprávněním, se z odpovědi vynechávají.
Příklady najdete v tématu Dotazování dat sledování práce pomocí Analýzy .
$orderby Slouží k určení posloupnosti, ve které se mají vrátit záznamy.
Příklady najdete v tématu Dotazování dat sledování práce pomocí Analýzy.
$top/$skip Slouží k omezení počtu vrácených záznamů.
Příklady najdete v tématu Dotazy v rámci projektu a organizace.
$select/$expand Slouží $select k určení sloupců, které potřebujete k sestavení sestavy. Slouží $expand k vnoření dalších možností dotazu. Každá z nich expandItem se vyhodnotí vzhledem k entitě, která obsahuje rozbalenou vlastnost navigace nebo streamu.

Seznam možností dotazu oddělený středníkem uzavřený v závorkách k názvu navigační vlastnosti Povolené systémové možnosti dotazu jsou $filter, , $orderby$top$skip$count$select, $searcha .$expand
Příklady najdete v tématu Dotazování dat sledování práce pomocí Analýzy.
$skiptoken Slouží k vynechání zadaného počtu záznamů.
$count nebo $count=true Zadáním $count vrátíte pouze počet záznamů. Zadáním $count=truevrátíte počet záznamu i dotazovaných dat.
Příklady najdete v tématu Agregace dat sledování práce pomocí Analýzy.

Tip

Vyhněte se kombinování $apply a $filter klauzulí v jednom dotazu. K filtrování dotazu máte dvě možnosti: (1) použijte $filter klauzuli nebo (2) použijte $apply=filter() kombinaci klauzule. Každá z těchto možností funguje skvěle samostatně, ale jejich kombinování může vést k neočekávaným výsledkům.

Vynucení stránkování na straně serveru

Analýza vynutí stránkování, když výsledky dotazu překročí 1 0000 záznamů. V takovém případě získáte první stránku dat a odkaz na následující stránku. Odkaz (@odata.nextLink) najdete na konci výstupu JSON. Bude vypadat jako původní dotaz následovaný $skip nebo $skiptoken. Příklad:

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

Poznámka:

Při načítání dat do klientských nástrojů, jako je Power BI Desktop nebo Excel, budou nástroje automaticky sledovat další odkaz a načíst všechny požadované záznamy.

Další kroky

Vytváření základních dotazů pomocí OData Analytics