Delen via


Query uitvoeren op gekoppelde werkitems

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Het uitvoeren van query's op werkitems in koppelingen is vergelijkbaar met het gebruik van typische navigatie-eigenschappen. Koppelingen zelf zijn echter entiteiten, dus er is wat extra complexiteit.

Er zijn twee manieren om een query uit te voeren op gekoppelde werkitems. De eerste is de bovenliggende/onderliggende hiërarchie en de tweede is de eigenschap Koppelingennavigatie.

In dit artikel leert u het volgende:

  • Een query maken om hiërarchische gekoppelde werkitems (bovenliggend/onderliggend) te retourneren
  • Een query samenstellen om niet-hiërarchische (gerelateerde, directe) gekoppelde werkitems te retourneren

Notitie

De Analytics-service wordt automatisch ingeschakeld en ondersteund in productie voor alle Azure DevOps-services. Power BI-integratie en -toegang tot de OData-feed van de Analytics-service zijn algemeen beschikbaar. We raden u aan deze te gebruiken en ons feedback te geven. Beschikbare gegevens zijn afhankelijk van versie. De meest recente ondersteunde versie is v2.0en de nieuwste preview-versie is v4.0-preview. Zie OData API-versiebeheer voor meer informatie.

Notitie

De Analytics-service wordt automatisch geïnstalleerd en ondersteund in productie voor alle nieuwe projectverzamelingen voor Azure DevOps Server 2020 en nieuwere versies. Power BI-integratie en -toegang tot de OData-feed van de Analytics-service zijn algemeen beschikbaar. We raden u aan deze te gebruiken en ons feedback te geven. Als u een upgrade hebt uitgevoerd van Azure DevOps Server 2019, kunt u de Analytics-service installeren tijdens de upgrade.

Beschikbare gegevens zijn afhankelijk van versie. De meest recente ondersteunde versie is v2.0en de nieuwste preview-versie is v4.0-preview. Zie OData API-versiebeheer voor meer informatie.

Notitie

De Analytics-service is in preview voor Azure DevOps Server 2019. U kunt deze in- of installeren voor een projectverzameling. Power BI-integratie en toegang tot de OData-feed van de Analytics-service zijn in preview. We raden u aan deze te gebruiken en ons feedback te geven.

Beschikbare gegevens zijn afhankelijk van versie. De meest recente ondersteunde versie is v2.0en de nieuwste preview-versie is v4.0-preview. Zie OData API-versiebeheer voor meer informatie.

Notitie

De voorbeelden in dit artikel zijn gebaseerd op een Azure DevOps Services-URL. Voor Azure DevOps Server moet u de URL vervangen door de on-premises server.

https://{servername}:{port}/tfs/{OrganizationName}/{ProjectName}/_odata/{version}/

Bovenliggende/onderliggende hiërarchie

U kunt items met betrekking tot bovenliggende/onderliggende koppelingen opnemen met behulp van $expand de eigenschappen Bovenliggend en Onderliggende items.

Voorbeeld: Bovenliggende naar onderliggende query

Als u informatie wilt retourneren over de onderliggende items van een item, gebruikt $expand u de eigenschap Onderliggende navigatie. Het volgende codefragment vraagt om de onderliggende items van werkitem-id 359 van het Fabrikam Fiber-project te retourneren.

Aanvragen

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)

Het antwoord retourneert functies 479 en 480, die kinderen zijn van het epische 359.

Notitie

De meeste OData-query's die koppelingsgegevens voor werkitems aanvragen, retourneren resultaten, maar ook een waarschuwing. De waarschuwing is een herinnering om de aanbevolen queryrichtlijnen te volgen die worden beschreven in OData Analytics-queryrichtlijnen. De opgegeven queryvoorbeelden zijn echter geldig.

Respons

@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"

Voorbeeld: Onderliggend naar bovenliggende query

Door Onderliggende items te vervangen door Bovenliggend item in de $expand optie, kunt u de vooroudering van een item ophalen.

De volgende query vraagt om het bovenliggende item-id 1048 van het Fabrikam Fiber-project te retourneren.

Aanvragen

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

Het antwoord retourneert functie 480, het bovenliggende item van productachterstand 1048.

Respons

@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"

Naast de bovenliggende/onderliggende hiërarchie kunnen items rechtstreeks worden gerelateerd aan andere items met koppelingstypen zoals Gerelateerd of Dupliceren. Met de navigatie-eigenschap Koppelingen kunt u deze relaties aanvragen.

Als u de koppelingen wilt ophalen die aan een item zijn gekoppeld, kunt $expand u de navigatie-eigenschap Koppelingen gebruiken. In dit voorbeeld worden de SourceWorkItemId, TargetWorkItemId en LinkTypeName opgehaald voor alle koppelingen die zijn gekoppeld aan het werkitem 363.

Aanvragen

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

Voorbeeld: Details van gekoppelde items aanvragen

U kunt de details van uw gekoppelde werkitems opnemen met behulp van $expand de navigatie-eigenschappen TargetWorkItem of SourceWorkItem . In dit voorbeeld halen we de WorkItemId, Titel en Status van het doelwerkitem voor elke koppeling op.

Aanvragen

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

Mogelijk bent u ook geïnteresseerd in een bepaald type koppeling tussen items. Geef de eigenschap LinkTypeName op in een $filter component. In het volgende queryvoorbeeld worden alle gerelateerde koppelingen uitgevouwen en worden alle andere koppelingstypen voor werkitem 103 uitgefilterd.

Aanvragen

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

Volgende stappen