Konstruowanie zapytań OData na potrzeby analizy w usłudze Azure DevOps

  • Artykuł

Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019

Analiza, platforma raportowania dla usługi Azure DevOps, może odpowiedzieć na pytania ilościowe dotyczące przeszłości lub bieżącego stanu projektów. Analiza obsługuje zapytania OData dotyczące metadanych i danych zestawu jednostek. Korzystając z prostych zapytań z przeglądarki internetowej, możesz zapoznać się z modelem danych i procesem zapytań.

W tym artykule poznasz następujące informacje:

  • Jak utworzyć zapytanie OData analizy dla chmury lub środowiska lokalnego
  • Jak wykonywać zapytania dotyczące metadanych analizy
  • Jak wykonywać zapytania dotyczące analizy OData dla zestawu jednostek
  • Które opcje zapytania są obsługiwane i zalecana sekwencja
  • Gdy stronicowanie po stronie serwera jest wymuszane

Możesz wykonywać zapytania względem usługi Analytics z dowolnej obsługiwanej przeglądarki internetowej. Aby uzyskać informacje o innych narzędziach, których można użyć do wykonywania zapytań w usłudze Analytics, zobacz Narzędzia zapytań analizy.

Uwaga

OData, protokół na poziomie aplikacji do interakcji z danymi za pośrednictwem interfejsów RESTful (gdzie REST=Representational State Transfer) obsługuje opis modeli danych, a także edytowanie i wykonywanie zapytań dotyczących danych zgodnie z tymi modelami. Model danych jednostki (EDM) lub metadane opisują informacje dostępne z analizy, w tym jednostki, typy jednostek, właściwości, relacje i wyliczenia używane do wykonywania zapytań dotyczących danych w celu tworzenia raportów. Aby zapoznać się z omówieniem usługi OData, zobacz Welcome to OData (Witamy w usłudze OData).

Wymagania wstępne

  • Aby wyświetlić dane analizy i wykonać zapytanie dotyczące usługi, musisz być członkiem projektu z dostępem podstawowym lub większym. Domyślnie wszyscy członkowie projektu otrzymują uprawnienia do wykonywania zapytań w usłudze Analytics i definiowania widoków analizy.
  • Aby dowiedzieć się więcej o innych wymaganiach wstępnych dotyczących włączania usługi i funkcji oraz ogólnych działań śledzenia danych, zobacz Uprawnienia i wymagania wstępne dotyczące dostępu do analizy.

Składniki adresu URL do wykonywania zapytań dotyczących metadanych

Analiza uwidacznia model jednostki pod adresem URL metadanych utworzony przez dołączenie $metadata go do głównego adresu URL usługi. Analiza udostępnia katalogi głównych usług dla projektu lub całej organizacji w usłudze Azure DevOps.

Możesz wyszukać dowolny z następujących elementów danych, wykonując zapytanie dotyczące metadanych.

  • Typy jednostek i zestawy jednostek
  • Właściwości i właściwości nawigacji
  • Klucze zastępcze
  • Wyliczone listy
  • Entityset
  • Kontenery
  • Funkcje filtru (Org.OData.Capabilities.V1.FilterFunctions)
  • Obsługiwane agregacje (Org.OData.Aggregation.V1.ApplySupported)
  • Obsługa usługi Batch (Org.OData.Capabilities.V1.BatchSupportType)

Używany adres URL zależy od tego, czy wykonujesz zapytania dotyczące danych dla usług Azure DevOps Services (w chmurze) czy lokalnego serwera Azure DevOps Server.

Aby wysłać zapytanie o metadane dla organizacji lub projektu hostowanego w chmurze, wprowadź składnię adresu URL, jak pokazano poniżej w przeglądarce internetowej. Zastąp {OrganizationName} wartości i {ProjectName} nazwą organizacji oraz nazwą projektu, który chcesz wykonać zapytanie. Aby zwrócić wszystkie metadane organizacji, nie należy określać nazwy projektu.

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

Uwaga

Najnowsza wersja analizy OData to wersja 4.0-preview. Tej wersji można używać dla wszystkich zapytań względem hostowanej usługi. Aby uzyskać więcej informacji na temat wersji analizy i dostępnych danych, zobacz Model danych dla analizy.

Oto przykład organizacji fabrikam hostowanej w usługach Azure DevOps Services.

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

Interpretowanie odpowiedzi metadanych

Analiza zwraca plik XML modelu danych. Użyj funkcji wyszukiwania przeglądarki, aby znaleźć informacje specyficzne dla danej jednostki.

Napiwek

W zależności od używanej przeglądarki ten plik może być sformatowany w czytelny sposób. Jeśli nie jest sformatowany, możesz znaleźć bezpłatny formater XML online za pomocą wyszukiwania w przeglądarce internetowej.

Dwa główne schematy zdefiniowane w metadanych analizy to Microsoft.VisualStudio.Services.Analytics.Model, który definiuje typy jednostek i wyliczane typy oraz ich składowe oraz Default schemat, który definiuje kontenery jednostek i zestawy jednostek oraz obsługiwane funkcje filtrowania, przekształcania i agregacji niestandardowej OData. Aby uzyskać więcej informacji, zobacz Analytics OData metadata (Metadane OData analizy).

<?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>

Wszystkie typy jednostek są skojarzone z właściwościami i właściwościami nawigacji. Zapytania dotyczące zestawów jednostek można filtrować przy użyciu obu tych typów właściwości. Są one wymienione w metadanych w obszarze EntityType jako lub PropertyNavigationalProperty. Jednostki pokrewne służą do określania dodatkowych filtrów, takich jak ścieżki iteracji, ścieżki obszaru lub teams.

Poniższy fragment kodu zawiera częściowy widok metadanych dla WorkItem jednostki. Właściwości odpowiadają polu elementu roboczego, a także określonym danym przechwyconym przez analizę, na przykład LeadTimeDays i CycleTimeDays. Właściwości nawigacji odpowiadają innym zestawom jednostek lub określonym danym analizy przechwyconym dla typu jednostki, na przykład Revisions, Links, Childreni 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"/>
...

Składniki adresu URL do wykonywania zapytań o jednostki

Aby wykonywać zapytania dotyczące danych usługi Analytics i tworzyć raporty, zazwyczaj wykonujesz zapytania dotyczące zestawu jednostek. Aby zapoznać się z omówieniem obsługiwanych jednostek, zobacz Analytics OData metadata (Metadane OData analizy).

Następujący adres URL służy do wykonywania zapytań względem określonego EntitySetelementu , takiego jak WorkItems, WorkItemSnapshoti PipelineRuns.

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

Oto przykład organizacji fabrikam , która zwraca liczbę elementów roboczych zdefiniowanych dla projektu Fabrikam Fiber.

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

Przykład zwraca 1399 elementów roboczych.

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

Uwaga

Jeśli nie dołączysz klauzuli $select lub $apply , zostanie wyświetlone ostrzeżenie, takie jak "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." Wykonanie instrukcji select w zestawie jednostek i zwrócenie wszystkich kolumn i wszystkich wierszy. Jeśli masz dużą liczbę rekordów, może to potrwać kilka sekund. Jeśli masz więcej niż 10 000 elementów roboczych, wymuszane jest stronicowanie oparte na serwerze.

Aby uniknąć przekroczenia limitów użycia, zawsze należy uwzględnić klauzulę $select or $apply .

Aby uzyskać informacje o właściwościach metadanych jednostki i relacji, zobacz następujące artykuły:

Przykład: Wykonywanie zapytań względem określonego zestawu jednostek

Aby wysłać zapytanie do określonego zestawu jednostek, takiego jak WorkItems, Areaslub Projects, dodaj nazwę zestawu jednostek: /WorkItems, /Areaslub /Projects. Aby uzyskać pełną listę zestawów jednostek, zobacz Model danych dla analizy.

Możesz na przykład uzyskać listę projektów zdefiniowanych dla organizacji, wykonując /Projects zapytanie i wybierając opcję zwrócenia ProjectName właściwości. W przypadku organizacji firmy fabrikam adres URL jest jak pokazano poniżej.

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

Analiza zwraca nazwy projektów tych projektów zdefiniowanych dla organizacji 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"
   }
 ]
}

Opcje zapytań

Opcja zapytania to zestaw parametrów ciągu zapytania zastosowanych do zasobu, który może pomóc w kontrolowaniu ilości zwracanych danych dla zasobu w adresie URL.

Opcje zapytania należy określić w kolejności wymienionej w poniższej tabeli.

Opcja kwerendy Uwagi
$apply Zestaw przekształceń, które można zastosować do zapytania, na przykład: filter, , groupbyaggregate, , , computeexpand,concat
Aby zapoznać się z przykładami, zobacz Agregowanie danych śledzenia pracy przy użyciu analizy.
$compute Obsługiwana funkcja OData, którą można określić, aby zdefiniować obliczone właściwości, które mogą być używane w wyrażeniu $select$filter, lub $orderby .
$filter Służy do filtrowania listy zwracanych zasobów. Wyrażenie określone przy $filter użyciu jest obliczane dla każdego zasobu w kolekcji i tylko elementy, w których wyrażenie daje wartość true, są uwzględniane w odpowiedzi. Zasoby, dla których wyrażenie daje wartość false lub null lub które właściwości odwołania są niedostępne z powodu uprawnień, zostaną pominięte w odpowiedzi.
Przykłady można znaleźć w temacie Query work tracking data using Analytics (Wykonywanie zapytań dotyczących danych śledzenia pracy przy użyciu usługi Analytics ).
$orderby Użyj polecenia , aby określić sekwencję, w której mają być zwracane rekordy.
Aby zapoznać się z przykładami, zobacz Query work tracking data using Analytics (Wykonywanie zapytań dotyczących danych śledzenia pracy przy użyciu analizy).
$top/$skip Użyj polecenia , aby ograniczyć liczbę zwracanych rekordów.
Przykłady można znaleźć w temacie Project and organization-scoped queries (Zapytania w zakresie projektu i organizacji).
$select/$expand Użyj $select polecenia , aby określić kolumny potrzebne do skompilowania raportu. Służy $expand do zagnieżdżania innych opcji zapytania. Każda z nich expandItem jest oceniana względem jednostki zawierającej rozszerzaną właściwość nawigacji lub strumienia.

Rozdzielana średnikami lista opcji zapytania, ujęta w nawiasy, na nazwę właściwości nawigacji. Dozwolone opcje zapytań systemowych to $filter, , $skip$top$orderby$count$select, , $searchi .$expand
Aby zapoznać się z przykładami, zobacz Query work tracking data using Analytics (Wykonywanie zapytań dotyczących danych śledzenia pracy przy użyciu analizy).
$skiptoken Użyj polecenia , aby pominąć określoną liczbę rekordów.
$count lub $count=true Wprowadź wartość , $count aby zwrócić tylko liczbę rekordów. Wprowadź wartość $count=true, aby zwrócić zarówno liczbę rekordów, jak i zapytanych danych.
Aby zapoznać się z przykładami, zobacz Agregowanie danych śledzenia pracy przy użyciu analizy.

Napiwek

Unikaj mieszania $apply i $filter klauzul w jednym zapytaniu. Aby filtrować zapytanie, masz dwie opcje: (1) użyj klauzuli $filter lub (2) użyj klauzuli $apply=filter() kombinacji. Każda z tych opcji działa świetnie samodzielnie, ale połączenie ich razem może prowadzić do nieoczekiwanych wyników.

Wymuszanie stronicowania po stronie serwera

Analiza wymusza stronicowanie, gdy wyniki zapytania przekraczają 10000 rekordów. W takim przypadku uzyskasz pierwszą stronę danych i link, aby wykonać instrukcje, aby uzyskać następną stronę. Link (@odata.nextLink) można znaleźć na końcu danych wyjściowych JSON. Będzie ona wyglądać podobnie do oryginalnego zapytania, po którym $skip następuje element lub $skiptoken. Na przykład:

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

Uwaga

Podczas ściągania danych do narzędzi klienckich, takich jak Program Power BI Desktop lub Excel, narzędzia będą automatycznie śledzić kolejne linki i ładować wszystkie wymagane rekordy.

Następne kroki

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