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

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

Аналитика, платформа отчетов для Azure DevOps, может ответить на количественные вопросы о прошлом или настоящем состоянии ваших проектов. Аналитика поддерживает запросы 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.

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

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

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

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

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

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

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

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

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

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

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

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

• Справочник по метаданным календаря, Project и User
• Справочник по метаданным для Azure Boards
• Справочник по метаданным для Azure Pipelines
• Справочник по метаданным для планов тестирования

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

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

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

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

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-адресе.

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

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

Аналитика заставляет разбиение по страницам, когда результаты запроса превышают 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"
}

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

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

• Что такое служба Аналитики?
• Рекомендации по запросам OData Analytics
• Разрешения и предварительные требования для доступа к Аналитике в Azure DevOps