Abfrage für verknüpfte Arbeitselemente

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019

Das Abfragen von Arbeitsaufgaben über Verknüpfungen ähnelt der Verwendung typischer Navigationseigenschaften. Links selbst sind jedoch Entitäten, daher gibt es eine zusätzliche Komplexität.

Es gibt zwei Möglichkeiten, verknüpfte Arbeitsaufgaben abzufragen. Die erste ist die Eltern-Kind-Hierarchie, und die zweite ist die Navigationseigenschaft "Links".

In diesem Artikel erfahren Sie:

• So erstellen Sie eine Abfrage, um hierarchisch (Eltern-Kind) verknüpfte Arbeitsaufgaben zurückzugeben.
• Erstellen einer Abfrage zum Zurückgeben von nicht hierarchischen (verknüpften, direkten) Arbeitsaufgaben

Anmerkung

Der Analysedienst wird automatisch aktiviert und in der Produktion für alle Azure DevOps-Dienste unterstützt. Power BI-Integration und Zugriff auf den OData-Feed des Analytics-Diensts sind allgemein verfügbar. Wir empfehlen Ihnen, sie zu verwenden und uns Feedback zu geben. Verfügbare Daten sind versionsabhängig. Die neueste unterstützte Version ist v2.0, und die neueste Vorschauversion wird v4.0-preview. Weitere Informationen finden Sie unter OData-API-Versionsverwaltung.

Voraussetzungen

Kategorie	Anforderungen
Zugriffsebenen	- Projektmitglied. – Mindestens Basic Zugriff.
Berechtigungen	Standardmäßig verfügen Projektmitglieder über die Berechtigung zum Abfragen von Analysen und Erstellen von Ansichten. Weitere Informationen zu anderen Voraussetzungen für die Dienst- und Featureaktivierung und allgemeine Datenverfolgungsaktivitäten finden Sie unter Berechtigungen und Voraussetzungen für den Zugriff auf Analytics.

Eltern-Kind-Hierarchie

Sie können Elemente, die sich über Parent/Child-Links beziehen, einschließen, indem Sie $expand für die Eigenschaften "übergeordnete Elemente" und "untergeordnete Elemente" verwenden.

Beispiel: Abfrage von einem übergeordneten an ein untergeordnetes Element

Um Informationen zu den untergeordneten Elementen eines Elements zurückzugeben, verwenden Sie $expand für die Navigationseigenschaft Untergeordnete Elemente. Der folgende Codeausschnitt fordert, die untergeordneten Elemente der Arbeitsaufgabe ID 359 aus dem Fabrikam Fiber-Projekt zurückzugeben.

Anfrage anfordern

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)

Die Antwort gibt die Features 479 und 480 zurück, die Unterelemente des Epic 359 sind.

Anmerkung

Die meisten OData-Abfragen, die Informationen zu Verknüpfungen von Arbeitselementen anfordern, geben Ergebnisse, aber auch eine Warnung zurück. Die Warnung ist eine Erinnerung, die empfohlenen Abfragerichtlinien zu befolgen, die in OData Analytics-Abfragerichtlinienbeschrieben werden. Die bereitgestellten Abfragebeispiele sind jedoch gültig.

Antwort

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

Beispiel: Abfrage vom Kind- zum Elternelement

Indem Sie Children durch Parent in der Option $expand ersetzen, können Sie die Herkunft eines Elements abrufen.

Die folgende Abfrageanforderung bittet darum, das übergeordnete Element des Arbeitselements mit der ID 1048 im Fabrikam Fiber-Projekt zurückzugeben.

Anfrage

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

Die Antwort gibt Feature 480 zurück, welches das übergeordnete Element des Backlog-Elements 1048 ist.

Antwort

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

Abfrage für nicht hierarchische Verknüpfungen

Zusätzlich zur Hierarchie "Übergeordnetes/Untergeordnetes Element" können Elemente direkt mit anderen Elementen wie zum Beispiel Verknüpfungstypen Verwandt oder Duplikatverknüpft werden. Mit der Links Navigationseigenschaft können Sie diese Beziehungen anfordern.

Beispiel: Anfordern der Verknüpfungen eines Elements

Um die einem Element zugeordneten Links abzurufen, können Sie die Navigationseigenschaft Links mit $expand verwenden. In diesem Beispiel werden die SourceWorkItemId, TargetWorkItemIdund LinkTypeName- für alle Verknüpfungen abgerufen, die der Arbeitsaufgabe 363 zugeordnet sind.

Anfrage

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)

Antwort

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

Beispiel: Anfordern von Details zu verknüpften Elementen

Sie können die Details Ihrer verknüpften Arbeitsaufgaben einschließen, indem Sie $expand für die TargetWorkItem- oder SourceWorkItem- Navigationseigenschaften verwenden. In diesem Beispiel rufen wir die WorkItemId, Titleund State des Zielarbeitselements für jeden Link ab.

Anfrage anfordern

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))

Antwort

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

Beispiel: Verknüpfungen eines bestimmten Typs

Möglicherweise sind Sie auch an einer bestimmten Art von Verknüpfung zwischen Elementen interessiert. Geben Sie die LinkTypeName- eigenschaft in einer $filter-Klausel an. Das folgende Abfragebeispiel erweitert alle Verwandten Links und filtert alle anderen Verknüpfungstypen für Arbeitsaufgabe 103 heraus.

Anfrage anfordern

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))

Antwort

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

Nächste Schritte

Analytics-Metadaten erkunden

Verwandte Artikel

• Erstellen von OData-Abfragen für Analytics
• Erstellen grundlegender Abfragen mit OData Analytics-
• Arbeitselemente mit direkten Links zu Beispielberichten
• Beispielbericht zur Anforderungsnachverfolgung