Partilhar via

Tutorial: Consulta de itens de trabalho vinculados

Serviços de DevOps do Azure | Azure DevOps Server | Azure DevOps Server 2022

Ao executar consultas OData (Open Data Protocol) no Analytics for 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 links são entidades, então há alguma complexidade extra. Há duas maneiras de consultar itens de trabalho vinculados:

  • Usando 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.
  • Construa consultas para retornar itens de trabalho vinculados não hierarquicamente.

Observação

O serviço Analytics é automaticamente habilitado e suportado na produção para todos os serviços nos Serviços de DevOps do Azure. A integração do Power BI e o acesso ao feed OData do serviço Analytics estão geralmente disponíveis. Você é incentivado a usar o feed OData do Google Analytics e fornecer feedback.

Os dados disponíveis dependem da versão. A última versão suportada da API OData é v2.0, e a versão de visualização mais recente é v4.0-preview. Para mais informações, consulte versionamento da API OData.

Observação

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

Os dados disponíveis dependem da versão. A última versão suportada da API OData é v2.0, e a versão de visualização mais recente é v4.0-preview. Para mais informações, consulte versionamento da API OData.

Pré-requisitos

Categoria Requerimentos
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 Google Analytics e criar modos de exibição. Para obter mais informações sobre outros pré-requisitos relacionados à ativação de serviços e recursos e atividades gerais de controle de dados, consulte Permissões e pré-requisitos para acessar o Google Analytics.

Observação

Os exemplos neste artigo usam uma URL dos Serviços de DevOps do Azure 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 de pais ou filhos

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 propriedade de navegação Children. 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.

Pedido

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 associados às funcionalidades com IDs 479 e 480. Esses recursos são filhos do item de trabalho épico com ID 359.

Observação

A maioria das consultas OData que solicitam informações de ligações de itens 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 Children por Parent na opção $expand, é possível recuperar a ancestralidade de um item.

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

Pedido

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 o recurso 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 dos 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 propriedade de navegação Links. A consulta a seguir recupera os SourceWorkItemIdvalores , TargetWorkItemIde LinkTypeName para todos os links associados ao item de trabalho 363.

Pedido

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 associados usando a opção $expand nas propriedades de navegação TargetWorkItem ou SourceWorkItem.

Como a consulta anterior, a consulta a seguir recupera os SourceWorkItemIdvalores , TargetWorkItemIde LinkTypeName para 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.

Pedido

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.

Pedido

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