Zapytania w zakresie projektu i organizacji

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

Korzystając z analizy dla usługi Azure DevOps, można tworzyć zapytania, które są ograniczone do projektu lub organizacji lub kolekcji. Te zapytania można uruchamiać bezpośrednio w przeglądarce lub w usłudze Power BI.

Zapytania dotyczące zakresu projektu pomagają odpowiedzieć na pytania dotyczące pojedynczego projektu, natomiast zapytania w zakresie organizacji i kolekcji umożliwiają odpowiadanie na pytania, które przekraczają granice projektu. Zapytania w zakresie organizacji i kolekcji wymagają szerszych uprawnień użytkownika lub starannych ograniczeń określania zakresu, aby upewnić się, że zapytanie nie jest blokowane z powodu braku uprawnień.

Uwaga

Usługa Analytics jest automatycznie włączona i obsługiwana w środowisku produkcyjnym dla wszystkich usług Azure DevOps Services. Integracja usługi Power BI i dostęp do źródła danych OData usługi Analytics są ogólnie dostępne. Zachęcamy do korzystania z niego i przekazywania opinii. Dostępne dane są zależne od wersji. Najnowsza obsługiwana wersja to v2.0, a najnowsza wersja zapoznawcza to v4.0-preview. Aby uzyskać więcej informacji, zobacz Wersjonowanie interfejsu API 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.

Ważne

Jeśli nie masz dostępu do wszystkich projektów w organizacji, zastosuj filtr projektu do wszystkich zapytań. Podczas ściągania danych do narzędzi klienckich, takich jak Power BI lub Excel, użyj składni ścieżki projektu, aby upewnić się, że wszystkie dane są ograniczone przez dany projekt. Używaj zapytań o zakresie organizacji lub zapytań o zakresie kolekcji tylko wtedy, gdy trzeba raportować co najmniej dwa projekty.

Zapytania w zakresie projektu

Zapytanie tworzy się, wprowadzając adres URL OData do obsługiwanej przeglądarki internetowej.

Podstawowy adres URL zapytania OData na poziomie projektu jest pokazany w poniższej składni.

Chmura (Azure DevOps Services)

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/

W podanych przykładach zamień {OrganizationName} i {ProjectName} na nazwy swojej organizacji i projektu, który chcesz zapytać.

Na miejscu (Azure DevOps Server)

https://{servername}:{port}/tfs/{CollectionName}/{ProjectName}/_odata/{version}/

W podanych przykładach wykonaj następujące zamiany:

• analytics.dev.azure.com z {ServerName}:{Port}/tfs/
• {CollectionName} z nazwą kolekcji projektu (wartość domyślna to DefaultCollection)
• {ProjectName} z nazwą projektu, który chcesz wyszukać.

Uwaga

Pozostałe przykłady w tym artykule są oparte na adresie URL usług Azure DevOps Services. Zastąp adres URL serwera Usługi Azure DevOps, aby użyć przykładów.

Zwracanie liczby elementów roboczych

Na przykład następujące zapytanie w zakresie projektu zwraca liczbę elementów roboczych dla określonego projektu.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/WorkItems/$count

Na przykład zapytanie projektu Fabrikam Fiber zwraca liczbę 7126 elementów roboczych. Usunięte elementy robocze nie są uwzględniane w liczbie.

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v1.0/WorkItems/$count

7126

Przywracanie ścieżek obszaru w projekcie

Podobnie następujący ciąg zapytania zwraca obszary dla określonego projektu:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/Areas

Jest to odpowiednikiem następującego filtru w zapytaniu z zakresem organizacji.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/Areas?
  $filter=Project/ProjectName eq '{ProjectName}'

Na przykład zapytanie dotyczące projektu Fabrikam Fiber zwraca wszystkie właściwości zdefiniowane dla ścieżki obszaru, ponieważ w zapytaniu nie zastosowano żadnego operatora $select.

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v1.0/Areas

W poniższym przykładzie przedstawiono dane zwrócone dla pojedynczej ścieżki obszaru.

ProjectSK	"56af920d-393b-4236-9a07-24439ccaa85c"
AreaSK	"26be05fd-e68a-4fcb-833f-497f6bee45f2"
AreaId	"26be05fd-e68a-4fcb-833f-497f6bee45f2"
AreaName	"Service Delivery"
Number	55373
AreaPath	"Fabrikam Fiber\\Service Delivery"
AreaLevel1	"Fabrikam Fiber"
AreaLevel2	"Service Delivery"
AreaLevel3	null
AreaLevel4	null
AreaLevel5	null
AreaLevel6	null
AreaLevel7	null
AreaLevel8	null
AreaLevel9	null
AreaLevel10	null
AreaLevel11	null
AreaLevel12	null
AreaLevel13	null
AreaLevel14	null
Depth	1

Użycie opcji $expand

W przypadku korzystania z zapytania w zakresie projektu z opcją $expand nie jest wymagane podanie innych filtrów.

Na przykład taki filtr projektowy:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/WorkItems?
  $expand=Parent

Jest filtrowany automatycznie, aby zapewnić bezpieczeństwo.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Parent($filter=ProjectName eq '{ProjectName}')

Zapytania w zakresie organizacji

Podstawowy adres URL zapytań na poziomie organizacji wygląda następująco:

https://analytics.dev.azure.com/{OrganizationName}/_odata/v1.0

W przypadku korzystania z zapytania w zakresie organizacji z opcją $expand należy podać inny filtr.

Na przykład następujące zapytanie obejmujące organizację, które używa elementu $expand, aby pobrać elementy podrzędne wszystkich elementów roboczych.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Children

Wymaga to dodatkowego filtru, aby zweryfikować, czy dzieci są ograniczone do określonego projektu.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Children($filter=Project/ProjectName eq '{ProjectName}')

Zwróć element nadrzędny wszystkich elementów roboczych

Poniższe zapytanie, które używa opcji $expand do pobrania elementów nadrzędnych dla wszystkich elementów roboczych.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Parent

Wymaga innego filtru, aby sprawdzić, czy element nadrzędny jest ograniczony do określonego projektu:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Parent($filter=Project/ProjectName eq '{ProjectName}')

Bez dodatkowego filtru żądanie kończy się niepowodzeniem, jeśli element nadrzędny dowolnego elementu roboczego odwołuje się do elementów roboczych w projekcie, do którego nie masz dostępu do odczytu.

Ograniczenia zabezpieczeń na poziomie projektu

Analiza ma jeszcze kilka ograniczeń dotyczących składni zapytań związanych z zabezpieczeniami na poziomie projektu.

Filtry any lub all dotyczą jednostki podstawowej w obiekcie $expand. W przypadku filtrów opartych na projekcie jawnie ignorujemy filtr podczas korzystania z elementu $expand:

Na przykład następujące zapytanie:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Children($filter=Project/ProjectName eq '{ProjectName}')

Jest interpretowany jako:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Children

Niepowodzenie występuje, jeśli nie masz dostępu do wszystkich projektów.

Aby obejść to ograniczenie, należy dodać dodatkowe wyrażenie w pliku $filter:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}' and Children/any(r: r/ProjectName eq '{ProjectName}')
  &$expand=Children

Użycie $level jest obsługiwane tylko wtedy, gdy masz dostęp do wszystkich projektów w kolekcji lub w przypadku korzystania z zapytania o zakresie projektu:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $expand=Children($levels=2;$filter=ProjectName eq '{ProjectName}')

Analiza nie obsługuje odwołań między poziomami w projektach korzystających z klauzuli $it. Jako przykład, poniższe zapytanie odwołuje się do głównego elementu roboczego ProjectName przy pomocy aliasu $it, który nie jest obsługiwany.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $expand=Links(
    $expand=TargetWorkItem;
    $filter=TargetWorkItem/Project/ProjectName eq $it/Project/ProjectName)

Następny krok

Wykonywanie zapytań dotyczących zagregowanych danych

Powiązane artykuły

• Wskazówki dotyczące zapytań