Consulta de elementos de trabajo vinculados

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

La consulta de elementos de trabajo entre vínculos es muy similar al uso de propiedades de navegación típicas. Sin embargo, los vínculos son entidades, por lo que hay cierta complejidad adicional.

Hay dos maneras de consultar elementos de trabajo vinculados. La primera es la jerarquía Parent/Child y la segunda es la propiedad de navegación Links.

En este artículo, aprenderá lo siguiente:

• Cómo construir una consulta para devolver elementos de trabajo vinculados jerárquicamente (elemento primario-secundario)
• Cómo construir una consulta para devolver elementos de trabajo vinculados no jerárquicos (relacionados, directos)

Nota:

El servicio Analytics se habilita automáticamente y se admite en producción para todos los servicios de Azure DevOps. La integración de Power BI y el acceso a la fuente OData del servicio Analytics están disponibles con carácter general. Le recomendamos que lo use y nos envíe sus comentarios. Los datos disponibles dependen de la versión. La versión más reciente admitida 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.

Jerarquía de elementos primarios y secundarios

Puede incluir elementos relacionados a través de vínculos primarios o secundarios mediante $expand en las propiedades Parent y Children.

Ejemplo: Consulta primaria a secundaria

Para devolver información sobre los elementos secundarios de un elemento, use $expand en la propiedad de navegación Children . El siguiente fragmento de código solicita devolver los elementos secundarios del identificador de elemento de trabajo 359 del proyecto Fabrikam Fiber.

Solicitar

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)

La respuesta devuelve características 479 y 480, que son elementos secundarios de la epopeya 359.

Nota:

La mayoría de las consultas de OData que solicitan información de vínculo del elemento de trabajo devolverán 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 proporcionados 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	
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"

Ejemplo: Consulta secundaria a primaria

Al reemplazar Niños por Padre en la $expand opción, puede recuperar la herencia de un elemento.

La consulta siguiente solicita devolver el identificador 1048 primario del elemento de trabajo del proyecto Fabrikam Fiber.

Solicitar

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

La respuesta devuelve la característica 480, que es el elemento primario del trabajo pendiente del producto 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	
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"

Consulta de vínculos no jerárquicos

Además de la jerarquía Parent/Child, los elementos pueden estar directamente relacionados con otros elementos con tipos de vínculo como Related o Duplicate. La propiedad de navegación Links permite solicitar estas relaciones.

Ejemplo: Solicitud de vínculos de un elemento

Para recuperar los vínculos asociados a un elemento, puede $expand la propiedad de navegación Vínculos . En este ejemplo se recuperan sourceWorkItemId, TargetWorkItemId y LinkTypeName para todos los vínculos asociados al elemento de trabajo 363.

Solicitar

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)

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 detalles de elementos vinculados

Puede incluir los detalles de los elementos de trabajo vinculados mediante $expand en las propiedades de navegación TargetWorkItem o SourceWorkItem . En este ejemplo, recuperamos workItemId, Title y State del elemento de trabajo de destino para cada vínculo.

Solicitar

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

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": "Some issue",
                "State": "Active"
            }
        }]
    }]
}

Ejemplo: Vínculos de un tipo específico

También puede estar interesado en un tipo determinado de vínculo entre elementos. Especifique la propiedad LinkTypeName en una $filter cláusula . En el ejemplo de consulta siguiente se expanden todos los vínculos relacionados y se filtran todos los demás tipos de vínculo para el elemento de trabajo 103.

Solicitar

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

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": "Some issue",
                "State": "Active"
            }
        }]
    }]
}

Pasos siguientes

Exploración de metadatos de Analytics

Artículos relacionados

• Construcción de consultas de OData para Analytics
• Construcción de consultas básicas mediante OData Analytics
• Elementos de trabajo con informes de ejemplo de vínculos directos
• Informe de ejemplo de seguimiento de requisitos