Partager via

Tutoriel : Rechercher des éléments de travail liés

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

Lorsque vous exécutez des requêtes OData (Open Data Protocol) sur Analytics pour Azure DevOps, vous pouvez récupérer des informations sur les éléments de travail. Vous pouvez également interroger des éléments de travail liés. Les éléments de travail peuvent être liés hiérarchiquement, comme dans les relations parent ou enfant. Les éléments de travail peuvent également être liés non hiérarchiquement, par exemple lorsque les éléments de travail sont liés ou sont des doublons.

La façon dont vous interrogez les éléments de travail liés est similaire à la façon dont vous utilisez les propriétés de navigation pour filtrer les requêtes des jeux d’entités. Mais les liens sont des entités, il y a donc une certaine complexité supplémentaire. Il existe deux façons d’interroger les éléments de travail liés :

  • À l’aide des propriétés de Parent ou Children navigation
  • En utilisant la propriété de navigation Links

Dans ce tutoriel, vous allez :

  • Créez des requêtes pour retourner des éléments de travail liés hiérarchiquement.
  • Créez des requêtes pour retourner des éléments de travail non liés de façon non hiérarchique.

Remarque

Le service Analytics est automatiquement activé et pris en charge en production pour tous les services dans Azure DevOps Services. L’intégration de Power BI et l’accès au flux OData du service Analytics sont généralement disponibles. Vous êtes encouragé à utiliser le flux OData Analytics et à fournir des commentaires.

Les données disponibles dépendent de la version. La dernière version prise en charge de l’API OData est v2.0, et la dernière version préliminaire est v4.0-preview. Pour plus d’informations, consultez gestion des versions de l’API OData .

Remarque

Le service Analytics est automatiquement installé et pris en charge en production pour toutes les nouvelles collections de projets pour Azure DevOps Server 2020 et versions ultérieures. L’intégration de Power BI et l’accès au flux OData du service Analytics sont généralement disponibles. Vous êtes encouragé à utiliser le flux OData Analytics et à fournir des commentaires. Si vous effectuez une mise à niveau à partir d’Azure DevOps Server 2019, vous pouvez installer le service Analytics pendant la mise à niveau.

Les données disponibles dépendent de la version. La dernière version prise en charge de l’API OData est v2.0, et la dernière version préliminaire est v4.0-preview. Pour plus d’informations, consultez gestion des versions de l’API OData .

Conditions préalables

Catégorie Exigences
niveaux d’accès - membre du projet.
- Au moins un accès de base.
autorisations Par défaut, les membres du projet ont l’autorisation d’interroger Analytics et de créer des vues. Pour plus d’informations sur les autres conditions préalables concernant l’activation du service et des fonctionnalités et les activités de suivi des données générales, consultez Autorisations et conditions préalables pour accéder à Analytics.

Remarque

Les exemples de cet article utilisent une URL Azure DevOps Services au format suivant :

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

Pour Azure DevOps Server, utilisez plutôt le format suivant, qui inclut le serveur local :

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

Rechercher des éléments de travail parents ou enfants

Vous pouvez interroger des éléments liés via des liens parent-enfant en utilisant l’option $expand sur les propriétés de navigation Parent et Children.

Exemple : Requérir les enfants d’un élément

Pour retourner des informations sur les enfants d’un élément, utilisez $expand sur la propriété de navigation Children. Le code OData suivant interroge le projet Fabrikam Fiber dans l’organisation fabrikam. Il retourne les enfants de l'élément de travail avec l'identifiant 359.

demande n°

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)

La réponse répertorie les informations sur les éléments associés aux fonctionnalités avec les ID 479 et 480. Ces fonctionnalités sont des sous-éléments de l’élément de travail d'envergure avec l’ID 359.

Remarque

La plupart des requêtes OData qui demandent des informations de lien d’élément de travail retournent des résultats, mais également un avertissement. L’avertissement est un rappel pour suivre les instructions de requête recommandées décrites dans les instructions de requête OData Analytics. Toutefois, les exemples de requête de cet article sont valides.

Réponse

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

Exemple : Demander le parent d’un élément

En remplaçant ChildrenParent par l’option $expand , vous pouvez récupérer l’ancêtre d’un élément.

Le code suivant interroge le parent de l’élément de travail avec l’ID 1048 dans le projet Fabrikam Fiber et l’organisation Fabrikam.

demande n°

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

La réponse fournit des informations sur la fonctionnalité avec l’ID 480, qui est le parent de l’élément du backlog de produit avec l’ID 1048.

Réponse

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

Outre les liens parent-enfant, d’autres types comme Related ou Duplicate peuvent également lier des éléments de travail. Vous pouvez utiliser la Links propriété de navigation pour demander des informations sur les éléments de travail liés via des relations non hiérarchiques.

Pour récupérer les liens associés à un élément, vous utilisez l’option $expand sur la propriété de Links navigation. La requête suivante récupère les valeurs SourceWorkItemId, TargetWorkItemId et LinkTypeName de tous les liens associés à l’élément de travail 363.

demande n°

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)

Réponse

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

Exemple : Demander des informations détaillées sur les éléments liés

Vous pouvez interroger des informations détaillées sur les éléments de travail liés en utilisant l'option $expand avec les propriétés de navigation TargetWorkItem ou SourceWorkItem.

Comme dans la requête précédente, la requête suivante récupère les valeurs SourceWorkItemId, TargetWorkItemId et LinkTypeName de tous les liens associés à un élément de travail. Mais cette requête récupère également les valeurs WorkItemId, Title, et State de l'élément de travail cible de chaque lien.

demande n°

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

Réponse

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

Si vous êtes intéressé par un type particulier de lien entre les éléments, vous pouvez utiliser la LinkTypeName propriété dans une $filter clause. La requête suivante développe tous les Related liens et filtre tous les autres types de liens pour l’élément de travail 103.

demande n°

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

Réponse

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

Contenu connexe