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

Статья
01/10/2024

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

С помощью Аналитики для Azure DevOps можно создавать базовые и отфильтрованные запросы для возврата интересующих данных. Эти запросы можно выполнять непосредственно в браузере или в Power BI.

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

В этой статье вы узнаете, как определить запросы, возвращающие следующие данные:

Количество элементов (без других данных)
Количество элементов и данных
Свойства, определенные для областей или путей итерации
Выбранные столбцы или поля
Отфильтрованные данные
Возврат данных для полей путь к удостоверению, области и пути итерации
Фильтрация по свойству навигации
Запрос диапазона дат
Операторы развертывания вложенного расширения
Сортировка результатов, параметр orderby

Примечание.

Служба Аналитики автоматически включается и поддерживается в рабочей среде для всех Служб Azure DevOps Services. Интеграция Power BI и доступ к веб-каналу OData службы Аналитики общедоступны. Мы рекомендуем вам использовать его и дать нам отзыв. Доступные данные зависят от версий. Последняя поддерживаемая версия: v2.0последняя предварительная версия v4.0-preview. Дополнительные сведения см. в разделе "Управление версиями API OData".

Примечание.

Служба Аналитики автоматически устанавливается и поддерживается в рабочей среде для всех новых коллекций проектов для Azure DevOps Server 2020 и более поздних версий. Интеграция Power BI и доступ к веб-каналу OData службы Аналитики общедоступны. Мы рекомендуем вам использовать его и дать нам отзыв. При обновлении с Azure DevOps Server 2019 можно установить службу Аналитики во время обновления.

Доступные данные зависят от версий. Последняя поддерживаемая версия: v2.0последняя предварительная версия v4.0-preview. Дополнительные сведения см. в разделе "Управление версиями API OData".

Примечание.

Служба Аналитики доступна в предварительной версии для Azure DevOps Server 2019. Его можно включить или установить для коллекции проектов. Интеграция Power BI и доступ к веб-каналу OData службы аналитики находятся в предварительной версии. Мы рекомендуем вам использовать его и дать нам отзыв.

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

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

Примечание.

В этой статье URL-адрес запроса OData определен для Azure DevOps Services. Чтобы создать аналогичный запрос для локального сервера, см. руководство, предоставленное в запросах OData конструктора для аналитики. Мы рекомендуем настроить запросы, предоставленные для вашей организации и проекта, чтобы ознакомиться с запросами OData с помощью браузера.

Возвращает количество элементов (без других данных)

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

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)

Совет

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

Число проектов

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(Count)"
value	
   0	
     @odata.id	null
     Count	    28

Количество рабочих элементов

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)"
value	
  0	
     @odata.id	null
     Count	    1166

Количество областей

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value	
  0	
     @odata.id	null
     Count	    70

Число пользователей

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value	
  0	
     @odata.id	null
     Count	    16

Возвращает количество элементов и данных

Чтобы вернуть количество элементов вместе с данными для элементов, укажите $count=true параметр запроса. Например, следующие запросы возвращают количество рабочих элементов, путей области и пользователей, определенных для проекта, а также указанных свойств. Допустимые свойства см. в справочнике по метаданным для аналитики и календаря Azure Boards Analytics , project и user метаданных для Azure DevOps Analytics.

Совет

Если вы не указываете возвращаемые свойства, аналитика вернет все свойства, определенные для указанного типа сущности.

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

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

Чтобы найти AreaSK или IterationSKдругое свойство пути области или пути итерации, используйте следующие запросы.

Возврат области для определенного пути области

Следующий запрос указывает, чтобы вернуть свойство, определенное для пути fabrikam Fibre\Service Delivery\Internet Area Path.AreaSK Сведения о других свойствах, определенных для Areas набора сущностей, см . в справочнике по метаданным для Аналитики, областей Azure Boards.

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

Запрос возвращает следующие данные.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Areas(AreaSK)",
  "value": [
    {
      "AreaSK": "637dc203-0549-4415-9663-b6358ac27d21"
    }
  ]
}

Возврат итерацииSK для определенного пути итерации

Следующий запрос указывает, чтобы вернуть IterationSK свойство, определенное для пути итерации Fabrikam Fibre\Release 1\Sprint 3. Сведения о других свойствах, определенных для Iterations набора сущностей, см . в справочнике по метаданным для Аналитики Boards, итерации.

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

Запрос возвращает следующие данные.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Iterations(IterationSK)",
  "value": [
    {
      "IterationSK": "862e961a-ac7a-4fcc-9ebc-8afd0c12fed5"
    }
  ]
}

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

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

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

Примечание.

Имена свойств не содержат пробелов. Запрос завершится ошибкой, если вы добавите пробелы. Запросы OData требуют внимания как между интервалами, так и регистрами. Сведения о том, как помечены свойства настраиваемого поля, см . в справочнике по метаданным для Azure Boards, настраиваемых свойств.

Здесь мы указываем, чтобы вернуть первые три рабочих элемента.

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

Аналитика возвращает следующие данные.

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value	
   0	
      WorkItemId    462
      Title         "Test case"
      WorkItemType  "Test Case"
      State         "Design"
   1	
      WorkItemId	   491
      Title          "Change color settings"
      WorkItemType   "Shared Steps"
      State          "Active"
   2	
      WorkItemId	   461
      Title          "Test impediment"
      WorkItemType   "Impediment"
      State          "Open"

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

Чтобы отфильтровать набор сущностей для возврата элементов выбора, укажите $filter предложение, указывающее критерии, которые должны соответствовать элементам. На основе последнего запроса мы добавим предложение фильтра, чтобы возвращать только типы рабочих элементов компонента , которые находятся в состоянии "Ход выполнения ".

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=State eq 'In Progress'

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

Аналитика возвращает следующие данные.

  
@odata.context	"https://analytics.dev.azure.com/kelliott/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,State)"
value	
  0	
      WorkItemId	380
      Title	"Refresh web look, feel, performance factors"
      State	"In Progress"
  1	
      WorkItemId	480
      Title	"Customer Phone - Phase 1"
      State	"In Progress"
  2	
      WorkItemId	493
      Title	"Change initial view"
      State	"In Progress"
  3	
      WorkItemId	479
      Title	"Customer Web - Phase 1"
      State	"In Progress"
  4	
      WorkItemId	551
      Title	"Mobile feedback"
      State	"In Progress"

Указание нескольких предложений фильтра

Можно использовать AND и OR указать несколько предложений фильтра.

Например, следующий запрос указывает, чтобы возвращать рабочие элементы типа User Story, Bug и Backlog Work (настраиваемый тип рабочего элемента), которые находятся в новых, зафиксированных или активных состояниях. При необходимости используйте скобки для группирования предложений фильтров.

Кроме того, можно применять различные функции, такие как contains, startswithendswith и многое другое. См. поддерживаемые функции и предложения OData, поддерживаемые функции.

Возврат данных для полей путь к удостоверению, области и пути итерации

Выбор свойств связан с свойствами навигации и недоступен напрямую с помощью инструкции $select . Для возврата интересующих данных необходимо использовать инструкцию $expand . Эти свойства часто связаны с несколькими свойствами своих собственных. Например, в полях identity можно указать имя пользователя или сообщение электронной почты пользователя.

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

Поля типа	Свойство, на которое ссылается ссылка	Примеры предложений для включения
Дата/время	`DateSK`	`$expand=CreatedDate($select=Date)` или `$expand=CreatedDate($select=WeekStartingDate)`
Идентификация	`UserSK`	`$expand=AssignedTo($select=UserName)` или `$expand=AssignedTo($select=UserEmail)`
Площадь	`AreaSK`	`$expand=Area($select=AreaName)` или `$expand=Area($select=AreaPath)`
Итерация	`IterationSK`	`$expand=Iteration($select=IterationName)` или `$expand=Iteration($select=IterationPath)` или `$expand=Iteration($select=StartDate)`
Project	`ProjectSK`	`$expand=Project($select=ProjectName)`
Группа	`TeamSK`	`$expand=Teams($select=TeamName)`

Чтобы указать несколько свойств, которые необходимо развернуть, необходимо указать их в одном предложении развертывания в списке с разделителями-точками.

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

При указании свойства навигации в рамках условий фильтра необходимо указать его в требуемом формате.

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

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

В этом примере Iteration имя свойства навигации соответствует IterationPath полному пути итерации. Чтобы использовать другую сущность в качестве фильтра, поместите свойство навигации, за которым следует косая черта, за которой следует отфильтровать поле.

И вот полный запрос OData:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

Ниже приведен еще один пример, в который возвращаются пять лучших рабочих элементов в разделе Fabrikam Fibre\Service Delivery\Voice Area Path.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Area/AreaPath eq 'Fabrikam Fiber\Service Delivery\Voice'&$select=WorkItemId, WorkItemType, Title, State&$orderby=WorkItemId asc

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value	
  0	
     WorkItemId	361
     Title        "Hello World Web Site"
     WorkItemType	"Product Backlog Item"
     State        "Removed"
  1	
     WorkItemId	362
     Title        "Resume"
     WorkItemType	"Product Backlog Item"
     State        "New"
  2	
     WorkItemId	363
     Title        "Welcome back page"
     WorkItemType	"Product Backlog Item"
     State        "Done"
  3	
     WorkItemId	365
     Title        "Pause"
     WorkItemType	"Feature"
     State        "New"
  4	
     WorkItemId	374
     Title        "Fix performance issues"
     WorkItemType	"Task"
     State        "To Do"

Совет

Свойство навигации нельзя использовать непосредственно в инструкции $select . Вместо этого необходимо использовать $expand.

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

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration

Ниже приведен пример, который возвращает сведения, назначенные рабочему элементу с идентификатором 480.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&&$expand=Iteration
   
@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)"
value	
  0	
      WorkItemId           480
      Title                "Customer Phone - Phase 1"
      WorkItemType	       "Feature"
      State	               "In Progress"
      Iteration	
          ProjectSK	       "56af920d-393b-4236-9a07-24439ccaa85c"
          IterationSK	       "c7063041-ff3a-4d7f-bb46-c433c7030d59"
          IterationId	       "c7063041-ff3a-4d7f-bb46-c433c7030d59"
          IterationName	   "Sprint 1"
          Number	            55297
          IterationPath	    "Fabrikam Fiber\\Release 1\\Sprint 1"
          StartDate	        "2022-01-17T00:00:00-08:00"
          EndDate	            "2022-02-04T23:59:59.999-08:00"
          IterationLevel1	    "Fabrikam Fiber"
          IterationLevel2	    "Release 1"
          IterationLevel3	    "Sprint 1"
          IterationLevel4	    null
          IterationLevel5	    null
          IterationLevel6	    null
          IterationLevel7	    null
          IterationLevel8	    null
          IterationLevel9	    null
          IterationLevel10	null
          IterationLevel11	null
          IterationLevel12	null
          IterationLevel13	null
          IterationLevel14	null
          Depth	            2
          IsEnded	        	true
      AnalyticsUpdatedDate	"2022-01-18T22:18:58.17Z"

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

Чтобы вернуть меньше данных, добавьте $select инструкцию против итерации, а также:

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration($select=Name,IterationPath)

Затем он возвращает следующие данные.

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration,Iteration(Name,IterationPath))",
  "value":[
    {
      "WorkItemId":10000,
      "WorkItemType":"Task",
      "Title":"Some title",
      "State":"Completed",
      "Iteration":{
        "Name":"Sprint 55",
        "IterationPath":"Fabrikam\\Sprints\\Sprint 55"
      }
    }
  ]
}

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

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

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-01-01Z

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

https://analytics.dev.azure.com{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-04-26Z&ChangedDate le 2021-04-30Z

Операторы развертывания вложенного расширения

В OData можно вложить $expand инструкции. Например, можно написать предыдущую инструкцию запроса, чтобы отобразить проект, в котором выполняется итерация:

/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($expand=Project)

Возвращает следующий код JSON:

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
  "value":[
    {
      "WorkItemId":10000,
      "Revision":3,
      "Watermark":283397,
      "Title":"Production deployment and testing for Entitlement API v2 and Subscriber database",
      "WorkItemType":"Task",
      "ChangedDate":"2014-07-10T19:29:58.41Z",
      "CreatedDate":"2014-04-19T22:44:58.31Z",
      "State":"Completed",
      "Reason":"Completed",
      "Priority":2,
      "CompletedWork":10.0,
      "OriginalEstimate":20.0,
      "Count":1,
      "Iteration":{
        "IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46",
        "Name":"Sprint 55",
        "Number":13021,
        "IterationPath":"Fabrikam\\Sprints\\Sprint 55",
        "StartDate":"2013-09-23T00:00:00Z",
        "EndDate":"2013-10-11T00:00:00Z",
        "IterationLevel1":"Fabrikam",
        "IterationLevel2":" Sprints",
        "IterationLevel3":"Sprint 55",
        "Level":2,
        "IsDeleted":false,
        "Project":{
          "ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
          "ProjectName":"Fabrikam",
          "IsDeleted":false
        }
      }
    }
  ]
}

Можно также объединить и $select операторы$expand. Например, можно изменить предыдущий запрос, чтобы вернуть только имя итерации и путь итерации:

/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($select=IterationId,IterationPath;$expand=Project)

Возвращает следующий код JSON:

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(Iteration(IterationId,IterationPath,Project))",
  "value":[
    {
      "WorkItemId":10000,
      "Revision":3,
      "Watermark":283397,
      "Title":"Production deployment and testing for Entitlement API v2 and Subscriber database","WorkItemType":"Task",
      "ChangedDate":"2014-07-10T19:29:58.41Z",
      "CreatedDate":"2014-04-19T22:44:58.31Z",
      "State":"Completed",
      "Reason":"Completed",
      "Priority":2,
      "CompletedWork":10.0,
      "OriginalEstimate":20.0,
      "Count":1,
      "Iteration":{
        "IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46","IterationPath":"Fabrikam\\Sprints\\Sprint 55",
        "Project":{
          "ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
          "ProjectName":"Fabrikam",
          "IsDeleted":false
        }
      }
    }
  ]
}

Обратите внимание, что в результате здесь отображаются только ИтерацииId и IterationPath, а проект является вложенным объектом в результатах JSON. Другим ключевым элементом, который следует заметить, является САМ URL-адрес. При использовании инструкции $select и $expand предложения необходимо использовать точку с запятой (;) перед предложением $expand. Все остальное приведет к ошибке.

Сортировка результатов, `orderby` параметр

$orderby Укажите параметр сортировки результатов или укажите последовательность, в которой возвращаются результаты. Вы можете отсортировать по возрастанию или убыванию по ключевым словам asc или descсоответственно. Показаны некоторые примеры

Сортировать по	Предложение для включения
Идентификатор рабочего элемента	`/WorkItems?$orderby=WorkItemId`
Убывание идентификатора рабочего элемента	`/WorkItems?$orderby=WorkItemId desc`
Тип рабочего элемента и состояние	`/WorkItems?$orderby=WorkItemType,State`

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

Запросы в области проекта и организации

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

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

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

Возвращает количество элементов (без других данных)

Число проектов

Количество рабочих элементов

Количество областей

Число пользователей

Возвращает количество элементов и данных

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

Возврат области для определенного пути области

Возврат итерацииSK для определенного пути итерации

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

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

Указание нескольких предложений фильтра

Возврат данных для полей путь к удостоверению, области и пути итерации

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

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

Операторы развертывания вложенного расширения

Сортировка результатов, `orderby` параметр

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

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

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

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

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

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

Возвращает количество элементов (без других данных)

Число проектов

Количество рабочих элементов

Количество областей

Число пользователей

Возвращает количество элементов и данных

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

Возврат области для определенного пути области

Возврат итерацииSK для определенного пути итерации

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

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

Указание нескольких предложений фильтра

Возврат данных для полей путь к удостоверению, области и пути итерации

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

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

Операторы развертывания вложенного расширения

Сортировка результатов, orderby параметр

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

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

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

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

Сортировка результатов, `orderby` параметр