Модель данных для аналитики

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Модель данных аналитики для Azure DevOps состоит из наборов сущностей, члены которых (сущности) содержат свойства, которые можно фильтровать, агрегировать и суммировать. Кроме того, они содержат свойства навигации, связанные с сущностями друг с другом, предоставляя доступ к другим свойствам для выбора, фильтрации и группировки.

Общие сведения о модели данных Аналитики

Служба Аналитики предоставляет структурированный подход к доступу к данным Azure DevOps через конечные точки OData. Эта модель данных позволяет:

• Запрос данных отслеживания работы: доступ к рабочим элементам, областям, итерациям и связанным метаданным
• Анализ сведений о конвейере: запрос данных о сборке и выпуске конвейера
• Отчет о результатах теста: доступ к данным о выполнении и планированию тестов
• Создание настраиваемых отчетов: создание отчетов Power BI и других решений аналитики

Пространства имен схемы

Модель данных Аналитики работает с двумя пространствами имен схемы:

• Microsoft.VisualStudio.Services.Analytics.Model
• Microsoft.VisualStudio.Services.Analytics

Эти пространства имен упорядочивают сущности и определяют их структуру, обеспечивая согласованность шаблонов доступа к данным в разных функциях Azure DevOps.

Наборы сущностей и типы сущностей

Типы сущностей называются структурированными типами с ключом. Они определяют именованные свойства и связи каждой сущности. Ключ EntityType формируется из подмножества примитивных свойств, например, WorkItemId, PipelineId, ReleasePipelineId, а также из других свойств типа сущности.

Наборы сущностей — это именованные коллекции сущностей. Например, это набор сущностей, WorkItems содержащий WorkItem сущности. Ключ сущности однозначно идентифицирует сущность в наборе сущностей. Если несколько наборов сущностей используют один и тот же тип сущности, то одно и то же сочетание значений ключей может отображаться в нескольких наборах сущностей и определяет разные сущности, по одному для каждого набора сущностей, где отображается это сочетание ключей. У каждой из этих сущностей есть другой идентификатор сущности. Наборы сущностей предоставляют точки входа в модель данных.

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

Составные сущности

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

Например, объединяется и WorkItemSnapshot такоеWorkItemRevisions, Dates что каждая дата имеет одну редакцию для каждого рабочего элемента. Это представление поддерживает запросы OData, ориентированные на данные тренда для отфильтрованного набора рабочих элементов. Однако эту составную сущность не следует использовать для запроса текущего состояния рабочих элементов. Вместо этого следует использовать набор сущностей WorkItems для создания более быстрого выполнения запроса.

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

Связи

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

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

Общие сведения о связях сущностей

Модель данных Аналитики использует несколько типов связей:

• Один ко многим: одна родительская сущность относится к нескольким дочерним сущностям (например, одна область ко многим рабочим элементам)
• Многие к одному: несколько сущностей относятся к одной родительской сущности (например, многие WorkItems к одной области)
• Один к одному: одна сущность относится ровно к одной другой сущности.
• Многие ко многим: несколько сущностей связаны с несколькими другими сущностями (например, WorkItems и теги)

Ключи связи

Связи сущностей также представлены как внешние ключи, чтобы внешние инструменты могли присоединять сущности. Эти свойства имеют суффикс "SK" и являются целыми или целыми типами данных GUID. Свойства даты имеют соответствующие свойства ключа даты целочисленного числа со следующим форматом: ГГГГММДД.

Типы сущностей отслеживания работы и наборы сущностей

Следующие типы сущностей и наборы сущностей поддерживаются с указанными версиями API. Полный справочник см . в справочнике по метаданным отслеживания работы для Аналитики Boards Azure.

Ключевые сущности учета работы для формирования отчетов

При создании отчетов рассмотрите эти основные наборы сущностей:

• Текущие отчеты о состоянии: использование WorkItems для текущего состояния рабочего элемента
• Исторические отчеты о трендах: использование WorkItemSnapshot для анализа тенденций с течением времени
• Подробное отслеживание изменений: использование WorkItemRevisions для комплексной истории
• Отчеты, относящиеся к доске: использование WorkItemBoardSnapshot для анализа доски Kanban

Рекомендации по использованию модели данных Аналитики

Оптимизация производительности

1. Выберите нужную сущность: используйте текущие сущности состояния (WorkItems) для отчетов о состоянии и сущностей моментальных снимков для тенденций
2. Ранняя фильтрация: применение фильтров на уровне сущности, а не после извлечения данных
3. Ограничение диапазонов данных. Использование фильтров дат для ограничения запросов к данным журнала
4. Используйте соответствующие агрегации: при возможности используйте встроенные функции агрегирования.

Шаблоны проектирования запросов

Текущие запросы состояния

/WorkItems?$filter=State ne 'Closed'&$select=WorkItemId,Title,State

Запросы исторических трендов

/WorkItemSnapshot?$filter=DateSK ge 20241001&$select=WorkItemId,State,DateSK

Навигация по связям

/WorkItems?$expand=Area($select=AreaPath),AssignedTo($select=UserName)

Распространенные ловушки, которых следует избегать

• Использование сущностей ревизии для текущего состояния: не используйте WorkItemRevisions, если WorkItems достаточно
• Чрезмерное расширение связей: развернуты только необходимые навигационные свойства
• Отсутствующие фильтры: всегда фильтруйте большие наборы сущностей для повышения производительности
• Игнорировать составные сущности: используйте составные сущности, такие как WorkItemSnapshot для анализа трендов

Соображения по версиям

Различные версии API предоставляют различные возможности:

• v1.0: Основные элементы для отслеживания работы
• версия 2.0. Добавлен процесс и расширенные возможности фильтрации
• версия 3.0-preview: добавлены конвейеры и тестовые сущности
• версия 4.0-preview: расширенные составные сущности и дополнительные метрики конвейера

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

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

• Рекомендации по запросам OData Analytics
• Аналитика WIT
• Статистические данные
• Изучение метаданных OData аналитики
• Ограничения для отслеживания хода выполнения работы, процесса и проекта
• Конструктор набора данных для аналитических представлений
• Создание запросов OData для аналитики
• Безопасность и разрешения аналитики