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

  • Статья

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.

Чтобы запросить метаданные для организации или проекта, размещенного в облаке, введите синтаксис 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

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

Аналитика возвращает 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>

Все типы сущностей связаны со свойствами и свойствами навигации. Запросы наборов сущностей можно фильтровать с помощью обоих этих типов свойств. Они перечислены в метаданных в виде EntityTypeProperty или 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.

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
   }
 ]
}

Примечание.

Если вы не включаете предложение или $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. Полный список наборов сущностей см. в разделе "Модель данных для аналитики".

Например, вы можете получить список проектов, определенных для организации, запросив /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"
   }
 ]
}

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

Параметр запроса — это набор параметров строки запроса, применяемых к ресурсу, который может помочь контролировать объем возвращаемых данных для ресурса в 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