Запрос связанных рабочих элементов

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

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

Существует два способа запроса связанных рабочих элементов. Первым является иерархия "Родитель-ребенок", а второй — свойство навигации Links.

В этой статье вы узнаете:

• Создание запроса для возврата иерархических рабочих элементов (родительского-дочернего)
• Создание запроса для возврата не иерархических (связанных, прямых) связанных рабочих элементов

Примечание.

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

Иерархия типа "родители-потомки"

Вы можете включить элементы, связанные с помощью ссылок "Родительский или дочерний", с помощью $expand свойств "Родительский" и "Дочерний".

Пример: родительский к дочернему запросу

Чтобы вернуть сведения о дочерних элементах, используйте $expandсвойство навигации "Дочерние ". Следующий фрагмент кода запрашивает возврат дочерних элементов рабочего элемента 359 из проекта Fabrikam Fibre.

Запросить

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

Ответ возвращает функции 479 и 480, которые являются детьми эпического 359.

Примечание.

Большинство запросов OData, запрашивающих сведения о ссылке на рабочий элемент, возвращают результаты, но и предупреждение. Предупреждение является напоминанием о том, чтобы следовать рекомендациям по запросу, описанным в рекомендациях по запросам OData Analytics. Однако приведенные примеры запросов являются допустимыми.

Response

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,WorkItemType,State,Children(WorkItemId,Title,WorkItemType,State))"
vsts.warnings@odata.type	"#Collection(String)"
@vsts.warnings	
0	"VS403508: Using the Parent, Children, Descendants or Revision properties in a filter or expand is not recommended. Details on recommended query patterns are available here: https://go.microsoft.com/fwlink/?linkid=861060."
value	
 0	
   WorkItemId	359
   Title	"Phase 1 - Customer access and engagement 5"
   WorkItemType	"Epic"
   State	"In Progress"
   Children	
      0	
        WorkItemId	480
        Title	"Customer Phone - Phase 1"
        WorkItemType	"Feature"
        State	"In Progress"
      1	
        WorkItemId	479
        Title	"Customer Web - Phase 1"
        WorkItemType	"Feature"
        State	"In Progress"

Пример: дочерний родительский запрос

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

Следующие запросы запрашивают возврат родительского элемента рабочего элемента 1048 из проекта Fabrikam Fibre.

Запросить

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

Ответ возвращает функцию 480, которая является родительским элементом невыполненной работы продукта 1048.

Response

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,WorkItemType,State,Parent(WorkItemId,Title,WorkItemType,State))"
vsts.warnings@odata.type	"#Collection(String)"
@vsts.warnings	
0	"VS403508: Using the Parent, Children, Descendants or Revision properties in a filter or expand is not recommended. Details on recommended query patterns are available here: https://go.microsoft.com/fwlink/?linkid=861060."
value	
  0	
     WorkItemId	1048
     Title	"Support reset"
     WorkItemType	"Product Backlog Item"
     State	"New"
     Parent	
        WorkItemId	480
        Title	"Customer Phone - Phase 1"
        WorkItemType	"Feature"
        State	"In Progress"

Запрос не иерархических ссылок

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

Пример. Запрос ссылок элемента

Чтобы получить ссылки, связанные с элементом, можно $expandиспользовать свойство навигации Links . В этом примере sourceWorkItemId, TargetWorkItemId и LinkTypeName извлекаются для всех ссылок, связанных с рабочим элементом 363.

Запросить

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

Response

{
    "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,WorkItemType,State,Links(SourceWorkItemId,TargetWorkItemId,LinkTypeName))",
    "value": [{
        "WorkItemId": 363,
        "Title": "Welcome back page",
        "WorkItemType": "Product Backlog Item",
        "State": "Done",
        "Links": [{
            "SourceWorkItemId": 363,
            "TargetWorkItemId": 400,
            "LinkTypeName": "Related"
        }, {
            "SourceWorkItemId": 363,
            "TargetWorkItemId": 470,
            "LinkTypeName": "Tested By"
        }, {
            "SourceWorkItemId": 363,
            "TargetWorkItemId": 501,
            "LinkTypeName": "Related"
        }, {
            "SourceWorkItemId": 363,
            "TargetWorkItemId": 1079,
            "LinkTypeName": "Tested By"
        }
    }]
}

Пример. Запрос сведений о связанных элементах

Вы можете включить сведения о связанных рабочих элементах с помощью $expandсвойств навигации TargetWorkItem или SourceWorkItem . В этом примере мы извлекаем WorkItemId, Title и State целевого рабочего элемента для каждой ссылки.

Запросить

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,WorkItemType,State&$filter=WorkItemId%20eq%20103&$expand=Links($select=SourceWorkItemId,TargetWorkItemId,LinkTypeName;$expand=TargetWorkItem($select=WorkItemId,Title,State))

Response

{
    "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,WorkItemType,State,Links(SourceWorkItemId,TargetWorkItemId,LinkTypeName,TargetWorkItem(WorkItemId,Title,State)))",
    "value": [{
        "WorkItemId": 103,
        "Title": "Feature Y",
        "WorkItemType": "Feature",
        "State": "New",
        "Links": [{
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 48,
            "LinkTypeName": "Child",
            "TargetWorkItem": {
                "WorkItemId": 48,
                "Title": "Story 15",
                "State": "Resolved"
            }
        }, {
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 50,
            "LinkTypeName": "Child",
            "TargetWorkItem": {
                "WorkItemId": 50,
                "Title": "Story 17",
                "State": "Active"
            }
        }, {
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 55,
            "LinkTypeName": "Child",
            "TargetWorkItem": {
                "WorkItemId": 55,
                "Title": "Story 22",
                "State": "New"
            }
        }, {
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 112,
            "LinkTypeName": "Related",
            "TargetWorkItem": {
                "WorkItemId": 112,
                "Title": "Some issue",
                "State": "Active"
            }
        }]
    }]
}

Пример: ссылки определенного типа

Вы также можете быть заинтересованы в определенном типе связи между элементами. Укажите свойство LinkTypeName в предложении$filter. Следующий пример запроса расширяет все связанные ссылки и фильтрует все другие типы ссылок для рабочего элемента 103.

Запросить

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,WorkItemType,State&$filter=WorkItemId eq 103&$expand=Links($select=SourceWorkItemId,TargetWorkItemId,LinkTypeName;$filter=LinkTypeName eq 'Related';$expand=TargetWorkItem($select=WorkItemId,Title,State))

Response

{
    "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,WorkItemType,State,Links(SourceWorkItemId,TargetWorkItemId,LinkTypeName,TargetWorkItem(WorkItemId,Title,State)))",
    "value": [{
        "WorkItemId": 103,
        "Title": "Feature Y",
        "WorkItemType": "Feature",
        "State": "New",
        "Links": [{
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 112,
            "LinkTypeName": "Related",
            "TargetWorkItem": {
                "WorkItemId": 112,
                "Title": "Some issue",
                "State": "Active"
            }
        }]
    }]
}

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

Изучение метаданных Аналитики

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

• Создание запросов OData для аналитики
• Создание базовых запросов с помощью OData Analytics
• Рабочие элементы с примерами отчетов с прямыми ссылками
• Пример отчета отслеживания требований