Partilhar via


Consulta de itens de trabalho vinculados

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

Consultar itens de trabalho entre links é muito parecido com usar propriedades de navegação típicas. Os links em si são entidades, portanto, há alguma complexidade extra.

Há duas maneiras de consultar itens de trabalho vinculados. A primeira é a hierarquia Pai/Filho e a segunda é a propriedade de navegação Links.

Neste artigo você vai aprender:

  • Como construir uma consulta para retornar hierarquicamente (pai-filho) itens de trabalho vinculados
  • Como construir uma consulta para retornar itens de trabalho vinculados não hierarquicamente (relacionados, diretos)

Nota

O serviço Analytics é automaticamente habilitado e suportado na produção para todos os Serviços de DevOps do Azure. A integração do Power BI e o acesso ao feed OData do Serviço de Análise estão geralmente disponíveis. Nós encorajamos você a usá-lo e nos dar feedback. Os dados disponíveis dependem da versão. A última versão suportada é , e a versão de pré-visualização mais recente é v2.0v4.0-preview. Para obter mais informações, consulte Controle de versão da API OData.

Nota

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 de Análise estão geralmente disponíveis. Nós encorajamos você a usá-lo e nos dar feedback. Se você atualizou 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 é , e a versão de pré-visualização mais recente é v2.0v4.0-preview. Para obter mais informações, consulte Controle de versão da API OData.

Nota

O serviço Analytics está em pré-visualização para o Azure DevOps Server 2019. Você pode habilitá-lo ou instalá-lo para uma coleção de projetos. A integração do Power BI e o acesso ao feed OData do Serviço de Análise estão em Pré-visualização. Nós encorajamos você a usá-lo e nos dar feedback.

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

Nota

Os exemplos mostrados neste artigo são baseados em uma URL dos Serviços de DevOps do Azure. Para o Servidor de DevOps do Azure, você precisa substituir a URL do servidor local.

https://{servername}:{port}/tfs/{OrganizationName}/{ProjectName}/_odata/{version}/

Hierarquia principal-subordinado

Você pode incluir itens relacionados por meio de links Pai/Filho usando $expand as propriedades Pai e Filhos.

Exemplo: consulta de pai para filho

Para retornar informações sobre os filhos de um item, use $expand a propriedade de navegação Filhos . O trecho de código a seguir solicita o retorno dos filhos do item de trabalho ID 359 do projeto Fabrikam Fibra.

Pedir

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)

A resposta retorna os recursos 479 e 480, que são filhos do épico 359.

Nota

A maioria das consultas OData que solicitam informações de link de item de trabalho retornará 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 fornecidos são válidos.

Response

@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"

Exemplo: consulta filho a pai

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

A consulta a seguir solicita o retorno do pai do item de trabalho ID 1048 do projeto Fabrikam Fibra.

Pedir

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

A resposta retorna o recurso 480, que é o pai para o item 1048 da lista de pendências do produto.

Response

@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"

Além da hierarquia Pai/Filho, os itens podem ser diretamente relacionados a outros itens com tipos de link como Relacionado ou Duplicado. A propriedade de navegação Links permite que você solicite essas relações.

Para recuperar os links associados a um item, você pode $expand usar a propriedade de navegação Links . Neste exemplo, SourceWorkItemId, TargetWorkItemId e LinkTypeName são recuperados para todos os links associados ao item de trabalho 363.

Pedir

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)

Response

{
    "@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 detalhes de itens vinculados

Você pode incluir os detalhes de seus itens de trabalho vinculados usando $expand as propriedades de navegação TargetWorkItem ou SourceWorkItem. Neste exemplo, recuperamos o WorkItemId, Title e State do item de trabalho de destino para cada link.

Pedir

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

Response

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

Você também pode estar interessado em um tipo específico de link entre itens. Especifique a propriedade LinkTypeName em uma $filter cláusula. O exemplo de consulta a seguir expande todos os links relacionados e filtra todos os outros tipos de link para o item de trabalho 103.

Pedir

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

Response

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

Próximos passos