Запросы на уровне проекта и организации

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

С помощью Аналитики для Azure DevOps можно создавать запросы, которые относятся к проекту или организации или коллекции. Эти запросы можно выполнять непосредственно в браузере или в Power BI.

Запросы области проекта помогают отвечать на вопросы о одном проекте, а организации и запросы с областью сбора позволяют отвечать на вопросы, пересекающие границы проекта. Для запросов в области организации и сбора требуются более широкие разрешения пользователей или осторожные ограничения области, чтобы убедиться, что запрос не заблокирован из-за отсутствия разрешений.

Примечание.

Служба Аналитики автоматически включается и поддерживается в рабочей среде для всех Служб Azure DevOps Services. Интеграция Power BI и доступ к веб-каналу OData службы Аналитики общедоступны. Мы рекомендуем вам использовать его и дать нам отзыв. Доступные данные зависят от версий. Последняя поддерживаемая версия: v2.0последняя предварительная версия v4.0-preview. Дополнительные сведения см. в разделе "Управление версиями API OData".

Необходимые компоненты

• Доступ. Быть членом проекта с по крайней мере базовым доступом.
• Разрешения. По умолчанию члены проекта имеют разрешение на запросы аналитики и создания представлений.
• Дополнительные сведения о других предварительных требованиях для включения служб и функций и общих действий отслеживания данных см. в разделе "Разрешения и предварительные требования для доступа к аналитике".

Внимание

Если у вас нет доступа ко всем проектам в организации, рекомендуется применить фильтр проекта ко всем запросам. При извлечении данных в клиентские средства, такие как Power BI или Excel, использование синтаксиса пути проекта является лучшим способом, чтобы убедиться, что все данные ограничены заданным проектом. Рекомендуется использовать запросы в области организации или области сбора только в том случае, если необходимо сообщить о двух или более проектах.

Запросы с областью проекта

Создайте запрос, введя URL-адрес OData в поддерживаемый веб-браузер.

Базовый URL-адрес для запроса OData уровня проекта, как показано в следующем синтаксисе.

Cloud (Azure DevOps Services)

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

В приведенных примерах замените {OrganizationName} имена {ProjectName} вашей организации и проекта, которые вы хотите запросить.

Локальная среда (Azure DevOps Server)

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

В приведенных примерах сделайте следующее:

• analytics.dev.azure.com с {ServerName}:{Port}/tfs/
• {CollectionName} с именем коллекции проектов (по умолчанию — DefaultCollection)
• {ProjectName} с именем проекта, который требуется запросить.

Примечание.

Остальные примеры, приведенные в этой статье, основаны на URL-адресе Azure DevOps Services. Для выполнения примеров необходимо заменить URL-адрес сервера Azure DevOps Server.

Возвращает количество рабочих элементов

Например, следующий запрос с областью проекта возвращает количество рабочих элементов для определенного проекта.

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

Например, запрос проекта Fabrikam Fibre возвращает количество рабочих элементов 7126. Удаленные рабочие элементы не включены в число.

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

7126

Возврат путей к области проекта

Аналогичным образом следующая строка запроса вернет области для определенного проекта:

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

Это эквивалентно следующему фильтру в запросе в области организации:

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

Например, запрос проекта Fabrikam Fibre возвращает все свойства, определенные для пути области, так как оператор не $select применяется в запросе.

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

В следующем примере показаны данные, возвращаемые для одного пути области.

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

Использование параметра $expand

При использовании запроса в области проекта с параметром $expand не требуется предоставлять другие фильтры.

Например, следующий фильтр области проекта:

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

фильтруется автоматически, чтобы обеспечить безопасность:

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

Запросы в области организации

Базовый URL-адрес для запросов уровня организации, как показано ниже.

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

При использовании запроса в области организации с параметром $expand необходимо предоставить другой фильтр.

Например, следующий запрос в области организации, который использует $expand для извлечения дочерних элементов всех рабочих элементов.

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

Для этого требуется другой фильтр, чтобы проверить, что дочерние элементы ограничены указанным проектом:

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

Возврат родительского элемента всех рабочих элементов

Следующий запрос, который использует $expand параметр для получения родительского элемента всех рабочих элементов.

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

Для этого требуется другой фильтр, чтобы проверить, что родительский объект ограничен указанным проектом:

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

Без другого фильтра запрос завершится ошибкой, если родительский элемент любого рабочего элемента ссылается на рабочие элементы в проекте, к которому у вас нет доступа на чтение.

Ограничения безопасности на уровне проекта

Аналитика имеет несколько дополнительных ограничений на синтаксис запросов, связанных с безопасностью на уровне проекта.

all Фильтры any применяются к базовой сущности в объекте$expand. Для фильтров на основе проекта мы явно игнорируем фильтр при использовании $expand:

Например, следующий запрос:

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

Интерпретируется следующим образом:

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

и завершится ошибкой, если у вас нет доступа ко всем проектам.

Чтобы обойти ограничение, необходимо добавить дополнительное выражение в $filter:

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

Использование $level поддерживается только в том случае, если у вас есть доступ ко всем проектам в коллекции или при использовании запроса с областью проекта:

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

Аналитика не поддерживает межуровневую ссылку для проектов с помощью $it предложения. Например, следующий запрос ссылается на корневой рабочий элемент ProjectName с помощью $it псевдонима, который не поддерживается:

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

Следующий шаг

Агрегированные данные запроса

Связанные статьи

• Рекомендации по запросу