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 Przechowywanie wersji interfejsu API OData.

Wymagania wstępne

• Dostęp: być członkiem projektu z co najmniej dostępem podstawowym.
• Uprawnienia: 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, zaleca się zastosowanie filtru projektu do wszystkich zapytań. Podczas ściągania danych do narzędzi klienckich, takich jak power BI lub Excel, użycie składni ścieżki projektu jest najlepszym sposobem zapewnienia, że wszystkie dane są ograniczone przez dany projekt. Zalecamy używanie zapytań o zakresie organizacji lub 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 zastąp {OrganizationName} wartości i {ProjectName} swoimi nazwami organizacji i projektu, którego chcesz wykonać zapytanie.

Lokalnie (serwer 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 wykonać zapytanie.

Uwaga

Pozostałe przykłady przedstawione w tym artykule są oparte na adresie URL usług Azure DevOps Services. W celu wykonania przykładów należy zastąpić adres URL serwera Azure DevOps Server.

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ę elementów roboczych 7126. Usunięte elementy robocze nie są uwzględniane w liczbie.

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

7126

Zwracanie ścieżek obszaru projektu

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

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

Jest on odpowiednikiem następującego filtru w zapytaniu o zakresie organizacji:

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

Na przykład zapytanie projektu Fabrikam Fiber zwraca wszystkie właściwości zdefiniowane dla ścieżki obszaru, ponieważ żaden operator nie $select jest stosowany w zapytaniu.

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 następujący filtr o zakresie projektu:

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

jest filtrowany automatycznie w celu wymuszenia zabezpieczeń:

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 o zakresie organizacji, 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 innego filtru, aby sprawdzić, czy elementy podrzędne 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 $expand opcji do pobrania elementu nadrzędnego 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 innego filtru żądanie zakończy się niepowodzeniem, jeśli element nadrzędny żadnego 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

i zakończy się niepowodzeniem, 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 żadnego odwołania między poziomami dla projektów przy użyciu klauzuli $it . Na przykład następujące zapytanie odwołuje się do głównego elementu ProjectName roboczego przy użyciu $it aliasu, 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ń