Создание запросов OData для аналитики в Azure DevOps

Статья
07/17/2024

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

Аналитика, платформа отчетов для Azure DevOps, может ответить на количественные вопросы о прошлом или настоящем состоянии ваших проектов. Аналитика поддерживает запросы OData своих метаданных и данных набора сущностей. Выполняя простые запросы из веб-браузера, вы можете ознакомиться с моделью данных и процессом запроса.

В этой статье вы узнаете следующее:

Создание запроса OData аналитики для облака или локальной среды
Как запрашивать метаданные Аналитики
Запрос OData аналитики для набора сущностей
Поддерживаемые параметры запроса и рекомендуемая последовательность
При принудительном выполнении разбиения на стороне сервера

Вы можете запросить аналитику из любого поддерживаемого веб-браузера. Другие средства, которые можно использовать для запроса аналитики, см. в статье "Аналитика запросов".

Примечание.

OData, протокол уровня приложения для взаимодействия с данными с помощью интерфейсов RESTful (где интерфейсы REST=Representational State Transfer) поддерживает описание моделей данных, а также редактирование и запрос данных в соответствии с этими моделями. Модель данных сущности (EDM) или метаданные описывают сведения, доступные в аналитике, включая сущности, типы сущностей, свойства, связи и перечисления, используемые для запроса данных для создания отчетов. Общие сведения об OData см. в разделе "Добро пожаловать в OData".

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

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

Компоненты URL-адресов для запроса метаданных

Аналитика предоставляет модель сущности по URL-адресу метаданных, сформированной путем добавления $metadata к корневому URL-адресу службы. Аналитика предоставляет корни служб для проекта или всей организации в Azure DevOps.

Вы можете искать любой из следующих элементов данных, запрашивая метаданные.

Типы сущностей и наборы сущностей
Свойства и свойства навигации
Суррогатные ключи
Перечисленные списки
EntitySet
Контейнеры
Фильтрация функций (Org.OData.Capabilities.V1.FilterFunctions)
Поддерживаемые агрегаты (Org.OData.Aggregation.V1.ApplySupported)
Поддержка пакетной службы (Org.OData.Capabilities.V1.BatchSupportType)

Используемый URL-адрес зависит от того, запрашиваете данные для Azure DevOps Services (облако) или локальный сервер Azure DevOps Server.

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

Чтобы запросить метаданные для организации или проекта, размещенного в облаке, введите синтаксис URL-адреса, как показано ниже в веб-браузере. {ProjectName} Замените {OrganizationName} имя организации и имя проекта, который требуется запросить. Чтобы вернуть все метаданные для организации, не указывайте имя проекта.

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

Примечание.

Последняя версия OData аналитики — версия 4.0-preview. Эту версию можно использовать для всех запросов к размещенной службе. Дополнительные сведения о версиях аналитики и доступных данных см. в разделе "Модель данных для аналитики".

Ниже приведен пример для организации fabrikam , размещенной в Azure DevOps Services.

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

Чтобы запросить метаданные для локального сервера, введите синтаксис URL-адреса, как показано ниже в веб-браузере. {CollectionName} Замените локальные имена и {ProjectName} замените {ServerName}их. Чтобы вернуть все метаданные для коллекции, не указывайте имя проекта.

https://{ServerName}/{CollectionName}/{ProjectName}/_odata/version/$metadata 
\_________________________________________________/\______________/\________/
                            |                              |            | 
     On-premises server, collection, project         OData version  return metadata

Примечание.

Ниже приведен пример для сервера с именем fabrikam-devops и DefaultCollection размещенного в Azure DevOps Server 2022:

https://fabrikam-devops/DefaultCollection/_odata/v4.0-preview/$metadata

Интерпретация ответа метаданных

Аналитика возвращает XML-файл модели данных. Используйте функцию поиска в браузере, чтобы найти сведения, относящиеся к интересующей сущности.

Совет

В зависимости от используемого браузера этот файл может быть отформатирован в режиме чтения. Если он не отформатирован, вы можете найти бесплатный веб-форматировщик XML с помощью поиска в веб-браузере.

Двумя основными схемами, определенными в метаданных Аналитики, являются Microsoft.VisualStudio.Services.Analytics.Modelтипы сущностей и перечисленные типы и их члены, а Default также схема, которая определяет контейнеры сущностей и наборы сущностей и поддерживаемые функции фильтрации, преобразования OData и пользовательских агрегатов. Дополнительные сведения см. в разделе метаданных OData Аналитики.

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

Все типы сущностей связаны со свойствами и свойствами навигации. Запросы наборов сущностей можно фильтровать с помощью обоих этих типов свойств. Они перечислены в метаданных в виде EntityType Property или NavigationalProperty. Связанные сущности используются для указания дополнительных фильтров, таких как пути итерации, пути к областям или Teams.

Следующий фрагмент кода предоставляет частичное представление метаданных для сущности WorkItem . Свойства соответствуют полю рабочего элемента, а также определенным данным, захваченным аналитикой, например LeadTimeDays и CycleTimeDays. Свойства навигации соответствуют другим наборам сущностей или определенным данным аналитики, захваченным для типа сущности, например Revisions, , LinksChildrenи 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"/>
...

Компоненты URL-адресов для запроса сущностей

Для запроса данных аналитики и создания отчетов обычно запрашивается набор сущностей. Общие сведения о поддерживаемых сущностях см. в разделе метаданных OData Analytics.

Следующий URL-адрес используется для запроса определенного EntitySetтипа, например WorkItems, WorkItemSnapshotи PipelineRuns.

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

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

Ниже приведен пример для организации fabrikam , которая возвращает количество рабочих элементов, определенных для проекта Fabrikam Fibre.

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

В примере возвращаются рабочие элементы 1399.

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

Ниже приведен пример для сервера fabrikam DefaultCollection, который возвращает количество рабочих элементов, определенных для проекта Fabrikam.

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

В примере возвращаются рабочие элементы 1399.

{
"@odata.context": "http://fabrikam/DefaultCollection/Fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)",
"value": [
   {
      "@odata.id": null,
      "Count": 44
   }
 ]
}

Примечание.

Если вы не включаете предложение или $apply не включаете $select предложение, вы получите предупреждение, например "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." это эквивалентно выполнению инструкции select для набора сущностей и возврату всего, всех столбцов и всех строк. Если у вас большое количество записей, может потребоваться несколько секунд. Если у вас более 10 000 рабочих элементов, на основе сервера применяется разбиение по страницам на основе сервера.

Чтобы избежать ограничения использования, всегда следует включать $select или $apply предложение.

Сведения о свойстве метаданных сущности и связях см. в следующих статьях:

Пример. Запрос определенного набора сущностей

Чтобы запросить определенный набор сущностей, например WorkItems, Areasили Projectsдобавьте имя набора сущностей: /WorkItems, /Areasили /Projects. Полный список наборов сущностей см. в разделе "Модель данных для аналитики".

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

Например, вы можете получить список проектов, определенных для организации, запросив /Projects и выбрав для возврата ProjectName свойства. Для организации fabrikam URL-адрес показан ниже.

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

Аналитика возвращает имена проектов этих проектов, определенных для организации 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"
   }
 ]
}

Ниже приведен пример, который запрашивает Projects набор сущностей, чтобы вернуть имена всех проектов, определенных на сервере Fabrikam,

https://fabrikam/DefaultCollection/_odata/v4.0-preview/Projects?$select=ProjectName

В примере возвращаются три имена проектов.

{
"@odata.context": "http://fabrikam/DefaultCollection/_odata/v4.0-preview/$metadata#Projects(ProjectName)",
"value": [
   {
      "ProjectName": "Fabrikam Fiber"
   },
   {
      "ProjectName": "Fabrikam"
   },
   {
      "ProjectName": "Fabrikam Florida"
   }
 ]
}

Параметры запроса

Параметр запроса — это набор параметров строки запроса, применяемых к ресурсу, который может помочь контролировать объем возвращаемых данных для ресурса в URL-адресе.

Параметры запроса должны быть указаны в порядке, указанном в следующей таблице.

Параметр запроса	Примечания.
`$apply`	Набор преобразований, которые можно применить к запросу, например: `filter`, `groupby`, , `aggregatecomputeexpand,` `concat` Примеры см. в разделе "Статистические данные отслеживания работы" с помощью аналитики.
`$compute`	Поддерживаемая функция OData, которую можно указать для определения вычисляемых свойств, которые можно использовать в `$select`выражении или `$orderby` в виде выражения`$filter`.
`$filter`	Используется для фильтрации списка возвращаемых ресурсов. Выражение, указанное с `$filter` параметром, вычисляется для каждого ресурса в коллекции, и только элементы, в которых выражение оценивает значение true, включаются в ответ. Ресурсы, для которых выражение оценивается как false, так и значение NULL, или свойства ссылки, недоступные из-за разрешений, опущены из ответа. Примеры см. в разделе "Запрос данных отслеживания работы с помощью аналитики ".
`$orderby`	Используется для указания последовательности, в которой должны быть возвращены записи. Примеры см. в статье "Запрос данных отслеживания работы с помощью аналитики".
`$top`/`$skip`	Используется для ограничения количества возвращаемых записей. Примеры см. в разделе "Запросы в области проекта и организации".
`$select`/`$expand`	Используется `$select` для указания столбцов, необходимых для создания отчета. Используется `$expand` для вложения других параметров запроса. Каждая из них `expandItem` оценивается относительно сущности, содержащей развернутое свойство навигации или потока. Разделенный точкой с запятой список параметров запроса, заключенный в скобки, в имя свойства навигации. Допустимые параметры системного запроса: `$filter`, `$select`, `$orderby$skip`, , `$top`, `$search$count`и `$expand`. Примеры см. в статье "Запрос данных отслеживания работы с помощью аналитики".
`$skiptoken`	Используется для пропуска указанного количества записей.
`$count` или `$count=true`	Введите `$count` только количество записей. Введите `$count=true`, чтобы вернуть как количество записей, так и запрашиваемых данных. Примеры см. в разделе "Статистические данные отслеживания работы" с помощью аналитики.

Совет

Избегайте смешивания $apply и $filter предложений в одном запросе. Для фильтрации запроса есть два варианта: (1) используйте предложение или (2) используйте $filter предложение сочетания $apply=filter() . Каждый из этих вариантов работает хорошо самостоятельно, но объединение их вместе может привести к некоторым непредвиденным результатам.

Принудительное разбиение на страницах на стороне сервера

Аналитика заставляет разбиение по страницам, когда результаты запроса превышают 10000 записей. В этом случае вы получите первую страницу данных и ссылку, чтобы перейти к следующей странице. Ссылку (@odata.nextLink) можно найти в конце выходных данных JSON. Он будет выглядеть как исходный запрос, за которым следует $skip или $skiptoken. Рассмотрим пример.

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

Примечание.

При извлечении данных в клиентские инструменты, такие как Power BI Desktop или Excel, средства автоматически следуют следующей ссылке и загружают все необходимые записи.

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

Создание базовых запросов с помощью OData Analytics

Поделиться через

Создание запросов OData для аналитики в Azure DevOps

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

Компоненты URL-адресов для запроса метаданных

Интерпретация ответа метаданных

Компоненты URL-адресов для запроса сущностей

Пример. Запрос определенного набора сущностей

Параметры запроса

Принудительное разбиение на страницах на стороне сервера

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

Обратная связь

Дополнительные ресурсы

Поделиться через

Создание запросов OData для аналитики в Azure DevOps

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

Компоненты URL-адресов для запроса метаданных

Интерпретация ответа метаданных

Связанные сущности и свойства навигации

Компоненты URL-адресов для запроса сущностей

Пример. Запрос определенного набора сущностей

Параметры запроса

Принудительное разбиение на страницах на стороне сервера

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

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

Обратная связь

Дополнительные ресурсы