Tutorial: Consulta de elementos de trabajo vinculados

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

Al ejecutar consultas de Open Data Protocol (OData) en Analytics para Azure DevOps, puede recuperar información sobre los elementos de trabajo. También puede consultar elementos de trabajo vinculados. Los elementos de trabajo se pueden vincular jerárquicamente, como en relaciones de padres o hijos. Los elementos de trabajo también se pueden vincular de forma no jerárquica, como cuando los elementos de trabajo están relacionados o se duplican.

La forma en que se consultan los elementos de trabajo vinculados es similar a la forma en que se usan las propiedades de navegación para filtrar las consultas de conjuntos de entidades. Pero los vínculos son entidades, por lo que hay cierta complejidad adicional. Hay dos maneras de consultar elementos de trabajo vinculados:

Mediante las propiedades de navegación Parent o Children
Utilizando la propiedad de navegación Links

En este tutorial:

Construya consultas para devolver elementos de trabajo vinculados jerárquicamente.
Crea consultas para devolver elementos de trabajo vinculados de forma no jerárquica.

Nota:

El servicio de análisis se habilita y es compatible automáticamente en producción para todos los servicios de Azure DevOps Services. La integración de Power BI y el acceso a la fuente OData del servicio Analytics están disponibles con carácter general. Se recomienda que use la fuente OData de Analytics y proporcione comentarios.

Los datos disponibles dependen de la versión. La versión más reciente admitida de la API de OData es v2.0y la versión preliminar más reciente es v4.0-preview. Para obtener más información, consulte Control de versiones de la API de OData.

Nota:

El servicio Analytics se instala y se admite automáticamente en producción para todas las nuevas colecciones de proyectos para Azure DevOps Server 2020 y versiones posteriores. La integración de Power BI y el acceso a la fuente OData del servicio Analytics están disponibles con carácter general. Se recomienda que use la fuente OData de Analytics y proporcione comentarios. Si actualiza desde Azure DevOps Server 2019, puede instalar el servicio Analytics durante la actualización.

Prerrequisitos

Categoría	Requisitos
Niveles de acceso	- Miembro del proyecto. - Al menos acceso básico .
Permisos	De forma predeterminada, los miembros del proyecto tienen permiso para consultar Analytics y crear vistas. Para obtener más información sobre otros requisitos previos relacionados con las actividades de habilitación de servicios y características y seguimiento de datos generales, consulte Permisos y requisitos previos para acceder a Analytics.

Nota:

En los ejemplos de este artículo se usa una dirección URL de Azure DevOps Services con el formato siguiente:

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

Para Azure DevOps Server, use en su lugar el siguiente formato, que incluye el servidor local:

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

Consulta de elementos de trabajo primarios o secundarios

Puede consultar elementos relacionados a través de vínculos de padre-hijo utilizando la opción $expand en las propiedades de navegación Parent y Children.

Ejemplo: Solicitar los elementos secundarios de un ítem

Para devolver información sobre los elementos secundarios de un elemento, use $expand en la propiedad de navegación Children. El código de OData siguiente consulta el proyecto Fabrikam Fiber en la organización fabrikam. Devuelve los subelementos del elemento de trabajo con el ID 359.

Solicitud

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 respuesta lista la información de los elementos de características de trabajo con los ID 479 y 480. Estas características son elementos secundarios del elemento de trabajo épico con el identificador 359.

Nota:

La mayoría de las consultas de OData que solicitan información de vínculo del elemento de trabajo devuelven resultados, pero también una advertencia. La advertencia es un recordatorio para seguir las directrices de consulta recomendadas que se describen en las directrices de consulta de OData Analytics. Sin embargo, los ejemplos de consulta de este artículo son válidos.

Respuesta

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

Ejemplo: Solicitar el elemento padre de un elemento

Al reemplazar Children por Parent en la opción $expand, puede recuperar la ascendencia de un elemento.

El siguiente código consulta el elemento padre del elemento de trabajo con el identificador 1048 en el proyecto Fabrikam Fiber y la organización Fabrikam.

Solicitud

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 respuesta muestra información sobre la característica con el identificador 480, que es el elemento primario del artículo de trabajo pendiente del producto con el identificador 1048.

Respuesta

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

Consulta de vínculos no jerárquicos

Además de los vínculos padre-hijo, otros tipos como Related o Duplicate también pueden vincular elementos de trabajo. Puede usar la Links propiedad de navegación para solicitar información sobre los elementos de trabajo vinculados a través de relaciones no jerárquicas.

Ejemplo: Solicitud de vínculos de un elemento

Para recuperar los vínculos asociados a un elemento, utilice la opción $expand en la propiedad de navegación Links. La consulta siguiente recupera los valores SourceWorkItemId, TargetWorkItemId y LinkTypeName de todos los vínculos asociados al elemento de trabajo 363.

Solicitud

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)

Respuesta

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

Ejemplo: Solicitud de información detallada sobre los elementos vinculados

Puede consultar información detallada sobre los elementos de trabajo vinculados mediante la opción $expand en las propiedades de navegación TargetWorkItem o SourceWorkItem.

Al igual que la consulta anterior, la consulta siguiente recupera los SourceWorkItemIdvalores , TargetWorkItemIdy LinkTypeName de todos los vínculos asociados a un elemento de trabajo. Pero esta consulta también recupera los valores de WorkItemId, Title y State del elemento de trabajo objetivo de cada enlace.

Solicitud

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

Respuesta

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

Ejemplo: Solicitud de vínculos de un tipo específico

Si estás interesado en un tipo determinado de vínculo entre elementos, puedes usar una LinkTypeName propiedad en una $filter cláusula. La consulta siguiente expande todos los Related vínculos y filtra todos los demás tipos de vínculo para el elemento de trabajo 103.

Solicitud

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

Respuesta

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

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-12-17

Compartir a través de

Tutorial: Consulta de elementos de trabajo vinculados

Prerrequisitos

Consulta de elementos de trabajo primarios o secundarios

Ejemplo: Solicitar los elementos secundarios de un ítem

Ejemplo: Solicitar el elemento padre de un elemento

Consulta de vínculos no jerárquicos

Ejemplo: Solicitud de vínculos de un elemento

Ejemplo: Solicitud de información detallada sobre los elementos vinculados

Ejemplo: Solicitud de vínculos de un tipo específico

Contenido relacionado

Comentarios

Recursos adicionales