Freigeben über


Abfragen von verknüpften Arbeitselementen

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 Hierarchie "Übergeordnetes/Untergeordnetes Element", und die zweite ist die Navigationseigenschaft "Links".

In diesem Artikel finden Sie Informationen zu Folgendem:

  • So erstellen Sie eine Abfrage, um hierarchisch (übergeordnetes untergeordnetes Element) verknüpfte Arbeitsaufgaben zurückzugeben
  • Erstellen einer Abfrage zum Zurückgeben von nicht hierarchischen (verknüpften, direkten) Arbeitsaufgaben

Hinweis

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 ist v4.0-preview. Weitere Informationen finden Sie unter OData-API-Versionsverwaltung.

Hinweis

Der Analysedienst wird automatisch installiert und in der Produktion für alle neuen Projektsammlungen für Azure DevOps Server 2020 und höhere Versionen 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. Wenn Sie ein Upgrade von Azure DevOps Server 2019 durchgeführt haben, können Sie den Analysedienst während des Upgrades installieren.

Verfügbare Daten sind versionsabhängig. Die neueste unterstützte Version ist v2.0, und die neueste Vorschauversion ist v4.0-preview. Weitere Informationen finden Sie unter OData-API-Versionsverwaltung.

Hinweis

Der Analysedienst befindet sich in der Vorschau für Azure DevOps Server 2019. Sie können es für eine Projektsammlung aktivieren oder installieren. Die Power BI-Integration und der Zugriff auf den OData-Feed des Analytics-Diensts befinden sich in der Vorschau. 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 ist v4.0-preview. Weitere Informationen finden Sie unter OData-API-Versionsverwaltung.

Hinweis

Die in diesem Artikel gezeigten Beispiele basieren auf einer Azure DevOps Services-URL. Für Azure DevOps Server müssen Sie die URL für den lokalen Server ersetzen.

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

Über-/Unterordnungshierarchie

Sie können Elemente, die sich über übergeordnete/untergeordnete Links $expand beziehen, mithilfe der Eigenschaften "Parent" und "Children" einschließen.

Beispiel: Übergeordnete zu untergeordnete Abfrage

Verwenden Sie die Untergeordneten Elemente eines Elements, um Informationen zu den untergeordneten Elementen zurückzugeben, die für die Navigationseigenschaft "Untergeordnete Elemente" verwendet $expand werden. Der folgende Codeausschnitt fordert an, die untergeordneten Elemente der Arbeitsaufgaben-ID 359 aus dem Fabrikam Fiber-Projekt zurückzugeben.

Anforderung

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 Features 479 und 480 zurück, die Kinder des epischen 359 sind.

Hinweis

Die meisten OData-Abfragen, die Arbeitsaufgabenlinkinformationen anfordern, geben Ergebnisse, aber auch eine Warnung zurück. Die Warnung ist eine Erinnerung, die empfohlenen Abfragerichtlinien zu befolgen, die in den OData Analytics-Abfragerichtlinien beschrieben sind. 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: Untergeordnetes Element zur übergeordneten Abfrage

Durch Ersetzen von "Children " durch "Parent " in der $expand Option können Sie die Herkunft eines Elements abrufen.

Die folgenden Abfrageanforderungen, um das übergeordnete Element der Arbeitsaufgaben-ID 1048 aus dem Fabrikam Fiber-Projekt zurückzugeben.

Anforderung

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, das übergeordnete Element des Produktrückstandselements 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"

Zusätzlich zur Hierarchie "Übergeordnetes/Untergeordnetes Element" können Elemente direkt mit anderen Elementen verknüpft werden, die Verknüpfungstypen wie "Verwandte " oder "Duplizieren" enthalten. Mit der Links-Navigationseigenschaft können Sie diese Beziehungen anfordern.

Zum Abrufen der Verknüpfungen, die einem Element zugeordnet sind, können $expand Sie die Links-Navigationseigenschaft verwenden. In diesem Beispiel werden " SourceWorkItemId", "TargetWorkItemId" und "LinkTypeName " für alle Verknüpfungen abgerufen, die der Arbeitsaufgabe 363 zugeordnet sind.

Anforderung

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 $expand mithilfe der Navigationseigenschaften TargetWorkItem oder SourceWorkItem einschließen. In diesem Beispiel rufen wir die WorkItemId, den Titel und den Status der Zielarbeitsaufgabe für jeden Link ab.

Anforderung

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

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. Im folgenden Abfragebeispiel werden alle verknüpften Links erweitert und alle anderen Verknüpfungstypen für Arbeitsaufgabe 103 herausfiltert.

Anforderung

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