Freigeben über

Anleitung: Abfragen von verknüpften Arbeitselementen

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020

Wenn Sie Open Data Protocol (OData)-Abfragen für Analytics für Azure DevOps ausführen, können Sie Informationen zu Arbeitsaufgaben abrufen. Sie können auch verknüpfte Arbeitsaufgaben abfragen. Arbeitsaufgaben können hierarchisch verknüpft werden, z. B. in übergeordneten oder untergeordneten Beziehungen. Arbeitsaufgaben können auch nichthierarchisch verknüpft werden, z. B. wenn Arbeitsaufgaben verknüpft sind oder Duplikate sind.

Die Art und Weise, wie Sie verknüpfte Arbeitsaufgaben abfragen, ähnelt der Art und Weise, wie Sie Navigationseigenschaften zum Filtern von Abfragen von Entitätssätzen verwenden. Verknüpfungen sind jedoch Entitäten, daher gibt es eine zusätzliche Komplexität. Es gibt zwei Möglichkeiten, verknüpfte Arbeitsaufgaben abzufragen:

  • Mithilfe der Navigationseigenschaften Parent oder Children
  • Mithilfe der Links Navigationseigenschaft

In diesem Tutorial führen Sie Folgendes durch:

  • Erstellen Sie Abfragen, um hierarchisch verknüpfte Arbeitsaufgaben zurückzugeben.
  • Erstellen Sie Abfragen, um nichthierarchisch verknüpfte Arbeitsaufgaben zurückzugeben.

Anmerkung

Der Analysedienst wird automatisch aktiviert und in der Produktion für alle Dienste in Azure DevOps Services unterstützt. Power BI-Integration und Zugriff auf den OData-Feed des Analytics-Diensts sind allgemein verfügbar. Sie werden dazu ermutigt, den OData-Datenfeed für Analytics zu verwenden und Feedback zu geben.

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

Anmerkung

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. Sie werden dazu ermutigt, den OData-Datenfeed für Analytics zu verwenden und Feedback zu geben. Wenn Sie ein Upgrade von Azure DevOps Server 2019 durchführen, können Sie den Analysedienst während des Upgrades installieren.

Verfügbare Daten sind versionsabhängig. Die neueste unterstützte Version der OData-API ist v2.0, und die neueste Vorschauversion ist 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.

Anmerkung

Die Beispiele in diesem Artikel verwenden eine Azure DevOps Services-URL im folgenden Format:

https://analytics.dev.azure.com/{organization-name}/{project-name}/_odata/{version}

Verwenden Sie für Azure DevOps Server stattdessen das folgende Format, das den lokalen Server enthält:

https://{server-name}:{port}/tfs/{organization-name}/{project-name}/_odata/{version}

Abfragen von übergeordneten oder untergeordneten Arbeitsaufgaben

Sie können Elemente abfragen, die durch Eltern-Kind-Verknüpfungen verbunden sind, indem Sie die Option $expand für die Parent-Eigenschaften und Children Navigationseigenschaften verwenden.

Beispiel: Anfordern der untergeordneten Elemente eines Elements

Verwenden Sie $expand für die Children Navigationseigenschaft, um Informationen über die untergeordneten Elemente eines Elements zurückzugeben. Der folgende OData-Code fragt das Fabrikam Fiber-Projekt in der Fabrikam-Organisation ab. Es gibt die Unterelemente der Aufgabe mit der ID 359 zurück.

Anfrage anfordern

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

Die Antwort listet Informationen zu den Funktionsaufgaben mit IDs 479 und 480 auf. Diese Funktionen sind untergeordnete Elemente des umfangreichen Arbeitselements mit ID 359.

Anmerkung

Die meisten OData-Abfragen, die Arbeitsaufgabenlinkinformationen anfordern, geben Ergebnisse zurück, aber auch eine Warnung. Die Warnung ist eine Erinnerung, die in den OData Analytics-Abfragerichtlinien beschriebenen empfohlenen Abfragerichtlinien zu befolgen. Die Abfragebeispiele in diesem Artikel 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": [
        "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": [{
        "WorkItemId": 359,
        "Title": "Phase 1 - Customer access and engagement 5",
        "WorkItemType": "Epic",
        "State": "In Progress",
        "Children": [{
            "WorkItemId": 480,
            "Title": "Customer Phone - Phase 1",
            "WorkItemType": "Feature",
            "State": "In Progress"
        },
        {
            "WorkItemId": 479,
            "Title": "Customer Web - Phase 1",
            "WorkItemType": "Feature",
            "State": "In Progress"
        }]
    }]
}

Beispiel: Abrufen des übergeordneten Elements eines Artikels

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

Der folgende Code fragt das übergeordnete Element der Arbeitsaufgabe mit der ID 1048 im Fabrikam Fiber-Projekt und der Fabrikam-Organisation ab.

Anfrage anfordern

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

Die Antwort listet Informationen zu dem Feature mit der ID 480 auf, bei dem es sich um das übergeordnete Element des Produktrücklogelements mit der ID 1048 handelt.

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": [
        "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": [{
        "WorkItemId": 1048,
        "Title": "Support reset",
        "WorkItemType": "Product Backlog Item",
        "State": "New",
        "Parent": {
                "WorkItemId": 480,
                "Title": "Customer Phone - Phase 1",
                "WorkItemType": "Feature",
                "State": "In Progress"
        }
    }]
}

Neben Links zu übergeordneten und untergeordneten Elementen können andere Typen wie Related oder Duplicate ebenfalls Arbeitsaufgaben verknüpfen. Sie können die Links Navigationseigenschaft verwenden, um Informationen zu Arbeitsaufgaben anzufordern, die über nichthierarchische Beziehungen verknüpft sind.

Zum Abrufen der Verknüpfungen, die einem Element zugeordnet sind, verwenden Sie die $expand Option für die Links Navigationseigenschaft. Die folgende Abfrage ruft die SourceWorkItemId, TargetWorkItemIdund LinkTypeName Werte für alle Verknüpfungen ab, die Arbeitsaufgabe 363 zugeordnet sind.

Anfrage anfordern

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_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 detaillierter Informationen zu verknüpften Elementen

Sie können detaillierte Informationen zu verknüpften Arbeitsaufgaben abfragen, indem Sie die $expand Option für die TargetWorkItem Eigenschaften oder SourceWorkItem Navigationseigenschaften verwenden.

Wie bei der vorherigen Abfrage ruft die folgende Abfrage die SourceWorkItemId, TargetWorkItemIdund LinkTypeName Werte für alle Verknüpfungen ab, die einer Arbeitsaufgabe zugeordnet sind. Diese Abfrage ruft auch die Werte des Zielarbeitsobjekts jedes Links ab, einschließlich der WorkItemId, Title und State Werte.

Anfrage anfordern

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_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": "Issue 10",
                "State": "Active"
            }
        }]
    }]
}

Wenn Sie an einem bestimmten Typ von Verknüpfung zwischen Elementen interessiert sind, können Sie die LinkTypeName Eigenschaft in einer $filter Klausel verwenden. Die folgende Abfrage erweitert alle Related Verknüpfungen und filtert alle anderen Verknüpfungstypen für Arbeitsaufgabe 103 aus.

Anfrage anfordern

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_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": "Issue 10",
                "State": "Active"
            }
        }]
    }]
}

Verwandte Inhalte