Compartilhar via

Tutorial: Consultar itens de trabalho vinculados

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

Ao executar consultas OData (Open Data Protocol) no Analytics para Azure DevOps, você pode recuperar informações sobre itens de trabalho. Você também pode consultar itens de trabalho vinculados. Os itens de trabalho podem ser vinculados hierarquicamente, como em relações pai ou filho. Os itens de trabalho também podem ser vinculados de forma não hierárquica, como quando os itens de trabalho estão relacionados ou são duplicados.

A maneira como você consulta itens de trabalho vinculados é semelhante à maneira como você usa propriedades de navegação para filtrar consultas de conjuntos de entidades. Mas os links são entidades, portanto, há alguma complexidade extra. Há duas maneiras de consultar itens de trabalho vinculados:

  • Ao usar as propriedades de navegação Parent ou Children
  • Usando a Links propriedade de navegação

Neste tutorial, você:

  • Construa consultas para retornar itens de trabalho hierarquicamente vinculados.
  • Crie consultas para retornar itens de trabalho vinculados de forma não hierárquica.

Observação

O serviço de Análise é habilitado automaticamente e tem suporte na produção de todos os serviços no Azure DevOps Services. A integração do Power BI e o acesso ao feed OData do serviço de Análise estão disponíveis em geral. Você é incentivado a usar o feed OData do Analytics e fornecer comentários.

Os dados disponíveis dependem da versão. A versão mais recente com suporte da API OData é v2.0e a versão de versão prévia mais recente é v4.0-preview. Para mais informações, consulte versão da API OData.

Observação

O serviço Analytics é automaticamente instalado e tem suporte em produção para todas as novas coleções de projetos no Azure DevOps Server 2020 e em versões posteriores. A integração do Power BI e o acesso ao feed OData do serviço de Análise estão disponíveis em geral. Você é incentivado a usar o feed OData do Analytics e fornecer comentários. Se você atualizar do Azure DevOps Server 2019, poderá instalar o serviço de Análise durante a atualização.

Os dados disponíveis dependem da versão. A versão mais recente com suporte da API OData é v2.0e a versão de versão prévia mais recente é v4.0-preview. Para mais informações, consulte versão da API OData.

Pré-requisitos

Categoria Requisitos
Níveis de Acesso - Membro do projeto.
– Pelo menos acesso básico .
Permissões Por padrão, os membros do projeto têm permissão para consultar o Analytics e criar visualizações. Para obter mais informações sobre outros pré-requisitos sobre a habilitação de serviços e recursos e atividades gerais de acompanhamento de dados, consulte Permissões e pré-requisitos para acessar o Analytics.

Observação

Os exemplos neste artigo usam uma URL do Azure DevOps Services no seguinte formato:

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

Para o Azure DevOps Server, use o seguinte formato, que inclui o servidor local:

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

Consulta de itens de trabalho pai ou filho

Você pode consultar itens relacionados por meio de links pai-filho usando a opção $expand nas propriedades de navegação Parent e Children.

Exemplo: solicitar filhos de um item

Para retornar informações sobre os filhos de um item, use $expand na Children propriedade de navegação. O código OData a seguir consulta o projeto Fabrikam Fiber na organização fabrikam. Retorna os filhos do item de trabalho com ID 359.

Solicitação

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)

A resposta lista informações sobre os itens de trabalho de funcionalidades com as IDs 479 e 480. Esses recursos são filhos do item de trabalho épico com a ID 359.

Observação

A maioria das consultas OData que solicitam informações de vínculo de item de trabalho retornam resultados, mas também um aviso. O aviso é um lembrete para seguir as diretrizes de consulta recomendadas descritas nas diretrizes de consulta do OData Analytics. No entanto, os exemplos de consulta neste artigo são válidos.

Resposta

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

Exemplo: solicitar o elemento pai de um item

Ao substituir ChildrenParent na opção $expand , você pode recuperar a ancestralidade de um item.

O código a seguir consulta o pai do item de trabalho com o ID 1048 no projeto Fabrikam Fiber e na organização Fabrikam.

Solicitação

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

A resposta lista informações sobre a funcionalidade com ID 480, que é o pai do item de backlog do produto com ID 1048.

Resposta

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

Além de links pai-filho, outros tipos, como Related ou Duplicate, também podem vincular itens de trabalho. Você pode usar a Links propriedade de navegação para solicitar informações sobre itens de trabalho vinculados por meio de relações não hierárquicas.

Para recuperar os links associados a um item, use a opção $expand na Links propriedade de navegação. A consulta a seguir recupera os valores SourceWorkItemId, TargetWorkItemId e LinkTypeName de todos os links associados ao item de trabalho 363.

Solicitação

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)

Resposta

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

Exemplo: solicitar informações detalhadas sobre itens vinculados

Você pode consultar informações detalhadas sobre itens de trabalho vinculados usando a opção $expand nas propriedades de navegação TargetWorkItem ou SourceWorkItem.

Assim como a consulta anterior, a consulta a seguir recupera os valores SourceWorkItemId, TargetWorkItemId e LinkTypeName de todos os links associados a um item de trabalho. Mas essa consulta também recupera os valores WorkItemId, Title e State do item de trabalho de destino de cada link.

Solicitação

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

Resposta

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

Se você estiver interessado em um tipo específico de vínculo entre itens, poderá usar a LinkTypeName propriedade em uma $filter cláusula. A consulta a seguir expande todos os Related links e filtra todos os outros tipos de link para o item de trabalho 103.

Solicitação

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

Resposta

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

Conteúdo relacionado

  • Last updated on