Udostępnij za pośrednictwem

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 analityczne OData dla chmury lub lokalnego środowiska
  • 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

Kategoria Wymagania
poziomy dostępu - Członek projektu.
— Co najmniej dostęp w warstwie podstawowej.
Uprawnienia użytkownika Domyślnie członkowie projektu mają uprawnienia do wykonywania zapytań w usłudze Analytics i tworzenia widoków. Aby uzyskać więcej informacji na temat innych wymagań 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 ujawnia model jednostki pod adresem URL metadanych, utworzony przez dołączenie $metadata do głównego adresu URL usługi. Analizy udostępniają podstawy 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 nawigacyjne
  • Klucze zastępcze
  • Wyliczone listy
  • EntitySet
  • Kontenery
  • Funkcje filtru (Org.OData.Capabilities.V1.FilterFunctions)
  • Obsługiwane agregacje (Org.OData.Aggregation.V1.ApplySupported)
  • Obsługa 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} nazwą swojej organizacji oraz {ProjectName} nazwą projektu, który chcesz zapytać. 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 Analytics OData to v4.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.

Wskazówka

W zależności od przeglądarki, której używasz, ten plik może być sformatowany w czytelny sposób lub nie. 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 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 pod EntityType jako Property lub NavigationalProperty. Jednostki pokrewne służą do określania dodatkowych filtrów, takich jak ścieżki iteracji, ścieżki obszaru lub zespoły.

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"/>
...

Komponenty adresu URL do 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 zwróci 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.", co jest równoważne wykonaniu instrukcji SELECT na zestawie encji, zwracając wszystkie kolumny i wszystkie wiersze. Jeśli masz dużą liczbę rekordów, może to potrwać kilka sekund. Jeśli masz więcej niż 10 000 elementów roboczych, stronicowanie oparte na serwerze jest wymuszane.

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 Twojej organizacji, wykonując zapytanie /Projects i wybierając zwrócenie właściwości ProjectName. W przypadku organizacji Fabrikam adres URL jest podany poniżej.

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

Analytics zwraca nazwy 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 za pomocą $filter jest obliczane dla każdego zasobu w kolekcji, a w odpowiedzi uwzględniane są tylko te elementy, dla których wyrażenie przyjmuje wartość true. 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, aby określić kolejność, w jakiej rekordy powinny być zwracane.
Aby zapoznać się z przykładami, zobacz Zapytania dotyczące danych śledzenia pracy z wykorzystaniem narzędzi analitycznych.
$top/$skip Użyj, aby ograniczyć liczbę zwracanych rekordów.
Przykłady można znaleźć w Zapytania w zakresie projektu i organizacji.
$select/$expand Użyj $select aby określić kolumny potrzebne do tworzenia raportu. Użyj $expand, aby zagnieżdżać inne opcje zapytania. Każda expandItem jest oceniana względem encji zawierającej właściwość nawigacji lub strumienia, która jest rozszerzana.

Lista opcji zapytania, rozdzielana średnikami i ujęta w nawiasach, odnosząca się do nazwy właściwości nawigacji. Dozwolone opcje zapytań systemowych to $filter, , $select$orderby$skip$top$count, , $searchi .$expand
Aby zapoznać się z przykładami, zobacz zapytania dotyczące danych śledzenia pracy przy użyciu narzędzi analitycznych.
$skiptoken Użyj, aby pominąć określoną liczbę rekordów.
$count lub $count=true Wprowadź $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.

Wskazówka

Unikaj mieszania $apply i $filter klauzul w jednym zapytaniu. Aby filtrować zapytanie, masz dwie możliwości: (1) zastosuj klauzulę $filter lub (2) zastosuj klauzulę kombinowaną $apply=filter(). 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 oraz link do następnej strony. Link (@odata.nextLink) można znaleźć na końcu danych wyjściowych JSON. Będzie wyglądać jak oryginalne zapytanie, po którym następuje $skip 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