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

Сервисы Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022

Используйте аналитические OData-запросы для получения данных отслеживания работы из Azure DevOps в браузере или таких клиентских приложениях, как Excel и Power BI. В этой статье рассматриваются подсчет элементов, выбор определенных полей с $select, фильтрация с $filter, расширение свойств навигации с $expand, запрос диапазонов дат и сортировка с $orderby.

В примерах рассматриваются наборы сущностей отслеживания работы в Azure Boards, но те же принципы применяются к другим наборам сущностей. Дополнительные сведения см. в статьях Конструирование запросов OData для аналитики и Справочник по метаданным для аналитики Azure Boards.

Предварительные условия

Узнать количество элементов

Чтобы вернуть только количество без других данных, добавьте $apply=aggregate($count as Count) к URL-адресу набора сущностей. Например, следующие запросы подсчитывают проекты, рабочие элементы, пути к областям и пользователей в организации.

https://analytics.dev.azure.com/<OrganizationName>/_odata/v4.0-preview/Projects?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/<OrganizationName>/_odata/v4.0-preview/WorkItems?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/<OrganizationName>/_odata/v4.0-preview/Areas?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/<OrganizationName>/_odata/v4.0-preview/Users?$apply=aggregate($count as Count)

Запрос Projects для fabrikam организации возвращает:

{
  "value": [
    {
      "Count": 16
    }
  ]
}

Получение количества элементов и их данных

Чтобы вернуть количество вместе с данными, добавьте $count=true в запрос с ключевым словом $select. Следующие запросы возвращают количество и выбранные свойства для рабочих элементов, путей к областям и пользователей в проекте:

https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/v4.0-preview/WorkItems?$count=true&$select=WorkItemId,Title,WorkItemType 
https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/v4.0-preview/Areas?$count=true&$select=AreaName,AreaPath 
https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/v4.0-preview/Users?$count=true&$select=UserName,UserEmail

Допустимые имена свойств см. в справочнике по метаданным Azure Boards Analytics и справочнике по метаданным даты календаря, проекта и пользователя.

Например, следующий запрос возвращает количество и имена пользователей в проекте Fabrikam Fiber:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Users?$count=true&$select=UserName

Ответ включает общее количество записей @odata.count и соответствующие записи в value:

{
  "@odata.count": 5,
  "value": [
    { "UserName": "Microsoft.VisualStudio.Services.TFS" },
    { "UserName": "fabrikamfiber1@hotmail.com" },
    { "UserName": "Jamal Hartnett" },
    { "UserName": "fabrikamfiber5@hotmail.com" },
    { "UserName": "fabrikamfiber2@hotmail.com" }
  ]
}

Выбор определенных свойств или полей

Добавьте оператор $select, чтобы вернуть только необходимые свойства. Имена свойств чувствительны к регистру, не могут содержать пробелы и должны соответствовать именам полей рабочих элементов. Например, $select=WorkItemId,WorkItemType,Title,State возвращает эти четыре поля.

Дополнительные сведения о поиске имен свойств, включая настраиваемые поля, см. в справочнике по метаданным для Azure Boards.

Следующий запрос возвращает идентификатор, тип, название и состояние для трех основных рабочих элементов в проекте Fabrikam Fibre:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$top=3

{
  "value": [
    { "WorkItemId": 31, "Title": "About screen", "WorkItemType": "Task", "State": "New" },
    { "WorkItemId": 30, "Title": "Change background color", "WorkItemType": "Task", "State": "Active" },
    { "WorkItemId": 32, "Title": "Standardize on form factors", "WorkItemType": "Task", "State": "Active" }
  ]
}

Фильтрация данных

$filter Добавьте предложение, чтобы возвращать только элементы, соответствующие определенным критериям. Используйте операторы сравнения, такие как eq, ne, gt, ge, lt, и le, и сочетайте условия с and и or. Например, следующий запрос возвращает функции, которые выполняются:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,AssignedTo,State&$filter=WorkItemType eq 'Feature' and State eq 'In Progress'

Объединение нескольких условий фильтра

Используйте круглые скобки для группирования or условий в более широком and фильтре. Следующий запрос возвращает пользовательские истории, ошибки и пользовательский тип в определенных состояниях:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,AssignedTo,State&$filter=(WorkItemType eq 'User Story' or WorkItemType eq 'Bug' or WorkItemType eq 'Backlog Work') and (State eq 'New' or State eq 'Committed' or State eq 'Active')

{
  "value": [
    { "WorkItemId": 210, "Title": "Slow response on form", "State": "Active" },
    ...
    { "WorkItemId": 160, "Title": "Game store testing", "State": "New" }
  ]
}

Можно также использовать такие строковые функции, как contains, startswithи endswith в выражениях фильтра. Дополнительные сведения см. в разделе "Поддерживаемые функции".

Свойства пути области запроса или пути итерации

Для некоторых запросов требуется суррогатный ключ (AreaSK или IterationSK) вместо строки пути. Используйте наборы сущностей "Области " или " Итерации" , чтобы найти ключ для определенного пути.

Вернуть AreaSK для определенного пути к области

Следующий запрос возвращает AreaSK для пути области Fabrikam Fiber\Production Planning\Web. Сведения о других доступных свойствах см. в разделе "Области".

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Areas?$filter=AreaPath eq 'Fabrikam Fiber\Production Planning\Web'&$select=AreaSK

{
  "value": [
    { "AreaSK": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" }
  ]
}

Получите IterationSK для конкретного пути итерации

Следующий запрос возвращает IterationSK для Fabrikam Fiber\Release 1\Sprint 3 итерационного пути. Сведения о других доступных свойствах см. в разделе "Итерации".

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Iterations?$filter=IterationPath eq 'Fabrikam Fiber\Release 1\Sprint 3'&$select=IterationSK

Фильтрация по свойствам навигации

Свойства навигации, такие как Iteration, Areaи AssignedTo представляют связи с другими сущностями. Чтобы отфильтровать поле из связанной сущности, используйте полный путь в формате NavigationProperty/Field. Например, Iteration/IterationPath ссылается на IterationPath поле с помощью свойства навигации Iteration :

/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

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

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Iteration/IterationPath eq 'Fabrikam Fiber\3Week Sprints\Sprint 3'&$select=WorkItemId,WorkItemType,Title,State&$orderby=WorkItemId asc

Разверните данные из связанных сущностей

Фильтрация по навигационному свойству означает, что его данные не будут включены в ответ. Чтобы вернуть поля из связанной сущности, используйте $expand. Без $expand невозможен доступ к полям свойств навигации через $select.

Следующий запрос возвращает рабочий элемент 480 со всеми полями из развернутой Iteration сущности:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration

Так как $select не применяется к расширению Iteration, ответ включает каждое Iteration поле:

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "IterationSK": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "StartDate": "2025-12-04T00:00:00-12:00",
        "EndDate": "2025-12-25T23:59:59.999-12:00",
        "IterationLevel1": "Fabrikam Fiber",
        "IterationLevel2": "3Week Sprints",
        "IterationLevel3": "Sprint 3",
        ...
        "Depth": 2,
        "IsEnded": false
      }
    }
  ]
}

Используйте select в операторах расширения

Чтобы ограничить поля, возвращаемые из развернутой сущности, добавьте $select условие внутри $expand с использованием синтаксиса $expand=Entity($select=Field1,Field2). Следующий запрос расширяет Iteration, возвращает только IterationName и IterationPath:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath)

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3"
      }
    }
  ]
}

В следующей таблице показаны $expand$select примеры распространенных типов свойств навигации:

Чтобы развернуть несколько свойств навигации в одном запросе, используйте список с разделителями-запятыми:

$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath)

Использование вложенных инструкций развертывания

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

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($expand=Project)

Для комбинирования вложенного расширения с $select, используйте точку с запятой (;) для разделения $select от $expand внутри круглых скобок. Без запятой запрос возвращает ошибку. Следующий запрос возвращает только IterationName и IterationPath из Iteration, а также вложенный Project:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath;$expand=Project)

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "Project": {
          "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber"
        }
      }
    }
  ]
}

Запрос диапазона дат

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

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-01-01Z

В следующем примере запроса возвращаются рабочие элементы, последние дата изменения которых произошла в течение недели с 31 октября по 7 ноября 2025 года.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-10-31Z and ChangedDate le 2025-11-07Z

Сортировка результатов

Добавьте $orderby для сортировки результатов по одному или нескольким свойствам. Результаты сортируются по возрастанию по умолчанию; для убывания добавьте desc. Разделите несколько полей сортировки запятыми.

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

Связанный контент

• Создание запросов OData для аналитики
• Агрегированные данные с помощью аналитики
• Справочник по метаданным для Аналитики Azure Boards
• Лучшие практики использования при запросах аналитических данных
• Поддерживаемые функции OData
• OData версии 4.0, часть 2. Соглашения URL плюс Errata 02