Guia de referência para tipos de link

Artigo
04/05/2024

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

Você pode usar diferentes tipos de links para gerenciar as diversas relações entre itens de trabalho e outros artefatos, como builds, commits, PRs e muito mais. Neste artigo, descrevemos os tipos de link a seguir.

Tipo de link de trabalho: vincula itens de trabalho, incluindo itens de trabalho de gerenciamento de casos de teste selecionados
Hiperlink: conecta um item de trabalho a qualquer URL ou compartilhamento de rede
Tipo de link externos: conecta um item de trabalho a um objeto externo, como um objeto de código, um build ou uma página de wiki
Tipo de link de trabalho remoto: conecta itens de trabalho definidos em diferentes organizações
Tipo de link do GitHub: conecta um item de trabalho a um commit, um problema ou um pull request de um repositório do GitHub.

Um campo específico mantém uma contagem de links para os quatro primeiros tipos de link, como Contagem de Links Relacionados, Contagem de Hiperlinks, Contagem de Links Externos e Contagem de Links Remotos.

Tipo de link de trabalho: vincula itens de trabalho, incluindo itens de trabalho de gerenciamento de casos de teste selecionados
Hiperlink: conecta um item de trabalho a qualquer URL ou compartilhamento de rede
Tipo de link externos: conecta um item de trabalho a um objeto externo, como um objeto de código, um build ou uma página de wiki
Tipo de link do GitHub: conecta um item de trabalho a um commit ou uma PR do repositório do GitHub.

Um campo específico mantém uma contagem de links para os três primeiros tipos de link, como Contagem de Links Relacionados, Contagem de Hiperlinks e Contagem de Links Externos.

Os tipos de link estão sujeitos a determinadas restrições com base na respectiva topologia. Use as diretrizes fornecidas nas tabelas a seguir para escolher o tipo de link a ser usado com base nos tipos de consultas e relatórios que você deseja criar. Para saber mais sobre as diferentes topologias, confira Topologias e restrições de tipos de links.

Tipo de link de trabalho

Os tipos de links de trabalho são definidos pelo sistema, pelo processo ou pelo usuário (personalizado). Os links listados na tabela a seguir são definidos pelo sistema.

Cada tipo de link de trabalho define os rótulos do link, o tipo de topologia e as restrições usadas quando links entre itens de trabalho são construídos. Por exemplo, o tipo de link pai-filho define dois rótulos: Pai e Filho. O tipo de link dá suporte a uma topologia de árvore ou hierárquica e impede a criação de referências circulares entre itens de trabalho.

Imagem conceitual de um tipo de link de item de trabalho.

A Contagem de Links Relacionados de um item de trabalho corresponde à soma de todos os links definidos com um tipo de link de trabalho.

A tabela a seguir descreve os tipos de links de item de trabalho que você pode especificar para definir o escopo de um controle de link usando o elemento XML WorkItemLinksFilter.

Nome

Nome de referência

Usage

Afeta-Afetado por (somente CMMI) Imagem conceitual do tipo de link Afeta. Imagem conceitual de Afeta pelo tipo de link.

Microsoft.VSTS.Common.Affects-Forward
Microsoft.VSTS.Common.Affects-Reverse
Tipo de topologia: dependência
Categoria de link: definido pelo processo

Use esse link direcional para criar links entre qualquer conjunto de itens de trabalho, mas não os que criariam loops fechados. Normalmente usado para rastrear solicitações de alteração feitas aos requisitos.

Restrições e recomendações:

É possível vincular uma solicitação de alteração a apenas um requisito usando Afeta. É possível vincular requisitos às solicitações de alteração filhas necessárias usando Afetado por.
Use links do tipo Afeta-Afetado por apenas para vincular itens de trabalho no mesmo projeto. Recomendamos essa ação se você pretende usar o Excel para modificar ou atualizar dados do item de trabalho.

Filho-Pai
Imagem conceitual de um tipo de link Filho.

System.LinkTypes.Hierarchy-Forward
System.LinkTypes.Hierarchy-Reverse
Tipo de topologia: árvore
Categoria de link: definido pelo sistema

Use esse link direcional para criar relações de um para muitos entre um pai e um ou mais itens filho. Use para organizar o item de trabalho dentro de uma hierarquia. Você pode criar rapidamente essa hierarquia entre itens da lista de pendências usando a função de mapeamento ou entre itens de lista de pendências e tarefas usando a lista de pendências do sprint ou o Quadro de Tarefas.

Os usos típicos incluem:

Mantenha relacionamentos de resumo de tarefa. Vínculos de pai-filho são criados para tarefas de resumo e suas tarefas subordinadas.
Vincule tarefas a PBIs, histórias do usuário ou requisitos. Oferece suporte a relatórios de Visão geral da lista de pendências, Visão geral de histórias e Visão geral de requisitos.

Restrições e recomendações:

Use o Excel para editar em massa itens de trabalho e vínculos de pai-filho. Confira Adicionar ou modificar itens de trabalho em massa com o Excel.
Um item de trabalho pode ter apenas um Pai. Um item de trabalho pai pode ter muitos filhos.
Use links do tipo pai-filho apenas para vincular itens de trabalho no mesmo projeto. Essa ação é recomendada se você planeja usar o Excel para modificar ou atualizar dados do item de trabalho.

Duplicado-Duplicado de Imagem conceitual de Duplicado de árvore dianteira.

System.LinkTypes.Duplicate-Forward
System.LinkTypes.Duplicate-Reverse
Tipo de topologia: árvore
Categoria de link: definido pelo sistema

Use esse link direcional para criar relações de um para muitos entre um pai e um ou mais itens filho. Use para rastrear tarefas, bugs ou outros itens de trabalho que são duplicados uns dos outros.

Restrições e recomendações:

Um item de trabalho pode ter apenas uma Duplicata.
Use links do tipo Duplicado ou Duplicado de apenas para vincular itens de trabalho no mesmo projeto. Essa ação é recomendada se você planeja usar o Excel para modificar ou atualizar dados do item de trabalho.

Referenciado por-Referencia
Imagem conceitual de Testado pelo tipo de link. Imagem conceitual do tipo de link Testes.

Microsoft.VSTS.TestCase.
SharedParameterReferencedBy
Tipo de topologia: dependência
Categoria de link: definido pelo processo

Use para vincular casos de teste a parâmetros compartilhados. Use para vincular Casos de Teste a Parâmetros Compartilhados para dar suporte à capacidade de repetir um teste usando dados diferentes. Em geral, você não adicionaria esse tipo de link a um controle de links com escopo.

Relacionado
Imagem conceitual de um tipo de link Relacionado.

System.LinkTypes.Related
Tipo de topologia: rede
Categoria de link: definido pelo sistema

Use esse link não direcional para criar links entre qualquer conjunto de itens de trabalho. Use para vincular itens de trabalho que estão no mesmo nível, como duas histórias do usuário que definem recursos sobrepostos. O tipo de link Relacionado cria relações simples com poucas restrições.

Relacione itens de trabalho que estão no mesmo nível, como duas histórias do usuário que definem recursos sobrepostos.
Vincule itens de trabalho definidos em projetos diferentes e gerenciados por equipes diferentes.
Localize a visualize itens de trabalho e seus itens de trabalho relacionados em uma visualização de dois níveis.
Crie relacionamentos simples com poucas restrições.

Sucessor-Predecessor
Imagem conceitual da dependência do sucessor, dianteiro.

System.LinkTypes.Dependency

Tipo de topologia: dependência
Categoria de link: definido pelo sistema
Escolha o tipo de link Predecessor ao vincular a um item de trabalho que deve ser concluído antes do item de trabalho do qual você está vinculando. Escolha o tipo de link Sucessor ao vincular a um item de trabalho que deve ser concluído depois do item de trabalho do qual você está vinculando.

Use esse link direcional para criar links entre qualquer conjunto de itens de trabalho, mas não os que criariam loops fechados. Use para rastrear tarefas que precisam ser concluídas antes que outras possam ser iniciadas. As tarefas vinculadas são representadas como links de predecessor/sucessor no Azure Boards.

Acompanha tarefas que devem ser concluídas antes de outras poderem ser iniciadas.
Dá suporte a relacionamentos de um para muitos.
Encontre e visualize itens de trabalho predecessores e seus itens de trabalho sucessores em um modo de exibição de consulta com vínculos diretos em dois níveis.

Restrições e recomendações:

Um erro é exibido quando você tenta criar vínculos que definem relacionamentos circulares.
Crie links do tipo predecessor-sucessor apenas para itens de trabalho dentro do mesmo projeto. É possível criar vínculos de predecessor-sucessor entre itens de trabalho definidos em projetos diferentes. Porém, se você exportar uma consulta para o Excel, somente os itens de trabalho definidos para o projeto ao qual a consulta foi definida serão importados.

Testado por-Testes
Imagem conceitual de Testado pelo tipo de link. Imagem conceitual do tipo de link Testes.

Microsoft.VSTS.Common.TestedBy-Forward
Microsoft.VSTS.Common.TestedBy-Reverse
Tipo de topologia: dependência
Categoria de link: definido pelo processo

Vincule casos de teste a itens de trabalho, como bugs, histórias de usuário, requisitos e itens da lista de pendências do produto. Use para rastrear casos de teste que testam histórias de usuário (Agile), itens da lista de pendências do produto (Scrum) ou requisitos (CMMI). Também é possível vincular a outros tipos de item de trabalho, como bugs, problemas ou tarefas. Para o Azure DevOps local, há vários relatórios SQL que dependem desses links. Confira Revisar atividades da equipe para dar suporte a relatórios úteis.

Caso de Teste-Etapas Compartilhadas
Imagem conceitual de Testado pelo tipo de link. Imagem conceitual do tipo de link Testes.

Microsoft.VSTS.TestCase.
SharedStepReferencedBy
Tipo de topologia: dependência
Categoria de link: definido pelo processo

Use para vincular casos de teste com etapas compartilhadas. Compartilhe as etapas entre os casos de teste para evitar a necessidade de criar várias entradas da mesma sequência de etapas.

Hyperlink

Um hiperlink pode vincular um item de trabalho a qualquer URL. A Contagem de Hiperlinks acompanha o número de hiperlinks em um item de trabalho.

Imagem conceitual de um hiperlink.

Nome do link

Ferramenta com suporte

Tipo de artefato

Usage

Hyperlink

Acompanhamento do item de trabalho

Hyperlink

Usado para vincular um item de trabalho a uma URL. Hiperlink de item de trabalho é o nome desse tipo de link na API de Tipos de Link de Artefato.

Tipo de link externo

Tipos de links externos são tipos de link definidos pelo sistema que dão suporte à vinculação de itens de trabalho a outros objetos armazenados no Azure DevOps, conforme mostrado na imagem a seguir. A Contagem de Links Externos de um item de trabalho corresponde à soma de todos os links definidos com um tipo de link externo.

Imagem conceitual de um tipo de link Externo.

Observação

Você pode usar um tipo de link externo apenas para vincular a um objeto do Azure DevOps. Para vincular itens de trabalho a outros objetos fora do Azure DevOps, use um hiperlink.

A tabela a seguir descreve os tipos de link externos que você pode escolher ao adicionar um tipo de link de um item de trabalho ou de um caso de teste.

A tabela a seguir descreve os tipos de link externos que você pode escolher ao adicionar um tipo de link de um item de trabalho ou caso de teste. Além disso, você pode especificar um desses tipos de link para definir o escopo de um controle de links usando o elemento XML ExternalLinksFilter.

Nome do link

Ferramenta com suporte

Tipo de artefato

Usage

Branch

Git

Branch

Usado para vincular um item de trabalho a um branch.

Pipelines/Build

Build

Usado para vincular um item de trabalho a um build.

Conjunto de alterações (ou Corrigido no Conjunto de Alterações)

VersionControl

Conjunto de alterações

Usado para vincular um item de trabalho a um conjunto de alterações.

Commit (ou Corrigido no Commit)

Git

Commit

Usado para vincular um item de trabalho a um commit.

Encontrado no build

Pipelines/Build

Build

Usado para vincular um item de trabalho a um build.

Integrado no build

Build

Pipeline de build

Usado para vincular um item de trabalho a um build.

Integrado ao ambiente de versão

Versão

Pipeline de lançamento

Usado para vincular uma versão a um item de trabalho. O sistema cria um link desse tipo quando um usuário habilita a opção Relatar status da implantação para Trabalho para uma definição da versão.

Pull Request

Git

PullRequestId

Usado para vincular um item de trabalho a uma PR.

Anexo de resultado

Gerenciamento de testes

TcmResultAttachment

Usado para vincular um item de trabalho a um anexo associado a um resultado de teste. Esses links aparecem quando você associa um item de trabalho a um resultado de teste do Teste ou do Microsoft Test Manager.

Arquivo de código-fonte<

VersionControl

LatestItemVersion

Usado para vincular um item de trabalho a um arquivo no TFVC (Controle de Versão do Team Foundation).

Storyboard

Requisitos

Storyboard

Usado para vincular um item de trabalho a um arquivo do PowerPoint ou outro arquivo que contém informações sobre story boarding em uma rede.

Marca

Git

Marca

Usado para vincular um item de trabalho a uma marca definida para um Repositório do Git ou um git commit. Para saber mais, confira Trabalhar no prompt de comando do Git.

Resultado do teste

Gerenciamento de testes

TcmResult

Usado para vincular um item de trabalho a um resultado do teste. Esses links aparecem quando você associa um item de trabalho a um resultado de teste do Teste ou do Microsoft Test Manager.

Item com controle de versão

VersionControl

LatestItemVersion

Usado para vincular um item de trabalho a um arquivo ou conjunto de alterações definido em um repositório do TFVC. Arquivo de Código-fonte é o nome desse tipo de link na API de Tipos de Link de Artefato.

Wiki

Usado para vincular um item de trabalho a uma página do wiki. Compatível com o TFS 2018.2 e versões posteriores.

Tipo de link do GitHub

Os tipos de link do GitHub são definidos pelo sistema e dão suporte à vinculação de itens de trabalho a objetos do GitHub, conforme mostrado na imagem a seguir.

Imagem conceitual de um tipo de link GitHub.

Importante

Você só pode vinculá-los aos artefatos do GitHub com repositórios conectados ao Azure Boards.

A tabela a seguir descreve os tipos de link do GitHub que você pode escolher ao adicionar um tipo de link de um item de trabalho.

Nome do link

Tipo de artefato

Usage

Commit do GitHub

Commit do repositório do GitHub

Usado para vincular um item de trabalho a um commit do GitHub.

Problema do GitHub

Problema de repositório do GitHub

Usado para vincular um item de trabalho a um problema do GitHub.

PR do GitHub

Solicitação de pull do repositório do GitHub

Usado para vincular um item de trabalho a uma PR do GitHub.

Tipo de link de trabalho remoto

Os tipos de vínculo de trabalho remoto são tipos de link definidos pelo sistema que dão suporte à vinculação de itens de trabalho definidos em organizações diferentes, desde que a mesma ID do Microsoft Entra os gerencie, conforme descrito em Conectar sua organização ao Microsoft Entra ID.

A Contagem de Links Remotos de um item de trabalho corresponde à soma de todos os links definidos com um tipo de link de trabalho remoto.

Nome

Nome de referência

Usage

Consome de-Produzido para
(Topologia de dependência) Imagem conceitual da topologia Consume de.

System.LinkTypes.Remote.Dependency-Forward
System.LinkTypes.Remote.Dependency-Reverse
Tipo de topologia: dependência
Categoria de link: definido pelo sistema

Use esse link direcional para criar links entre itens de trabalho que têm dependências e são definidos em organizações diferentes, desde que a mesma ID do Microsoft Entra os gerencie. Normalmente usado para rastrear solicitações de alteração feitas aos requisitos.

Remoto Relacionado
Imagem conceitual da topologia Relacionado Remotamente.

System.LinkTypes.Remote.Related
Tipo de topologia: rede
Categoria de link: definido pelo sistema

Use esse link não direcional para criar links entre itens de trabalho definidos em organizações diferentes, desde que a mesma ID do Microsoft Entra os gerencie.

Tipo de link personalizado

É possível criar um tipo de link personalizado, exportar e importar definições de tipos de link, bem como excluir, ativar, desativar e reativar tipos de link. Veja os artigos a seguir:

Listar tipos de link

Para obter uma lista de tipos de link, você pode usar uma das ferramentas de linha de comando com suporte.

az boards work-item relation list-type

Você pode listar os tipos de link com suporte de sua organização com o comando az boards work-item relation list-type ou com o comando da API REST Work Item Relation Types - List. Para começar, confira Introdução à CLI do Azure DevOps.

az boards work-item relation list-type [--org]

Parâmetros opcionais

org: a URL da organização do Azure DevOps. Você pode configurar a organização padrão usando az devops configure -d organization=ORG_URL. Obrigatório se não estiver configurado como padrão ou selecionado usando git config. Exemplo: --org https://dev.azure.com/MyOrganizationName/.

Exemplo

O comando a seguir lista os tipos de link de item de trabalho no formato de tabela que foram definidos para a organização fabrikam.

az boards work-item relation list-type --org fabrikam --output table
Name                  ReferenceName                                                Enabled    Usage
--------------------  -----------------------------------------------------------  ---------  ------------
Produces For          System.LinkTypes.Remote.Dependency-Forward                   True       workItemLink
Consumes From         System.LinkTypes.Remote.Dependency-Reverse                   True       workItemLink
Duplicate             System.LinkTypes.Duplicate-Forward                           True       workItemLink
Duplicate Of          System.LinkTypes.Duplicate-Reverse                           True       workItemLink
Referenced By         Microsoft.VSTS.TestCase.SharedParameterReferencedBy-Forward  True       workItemLink
References            Microsoft.VSTS.TestCase.SharedParameterReferencedBy-Reverse  True       workItemLink
Tested By             Microsoft.VSTS.Common.TestedBy-Forward                       True       workItemLink
Tests                 Microsoft.VSTS.Common.TestedBy-Reverse                       True       workItemLink
Test Case             Microsoft.VSTS.TestCase.SharedStepReferencedBy-Forward       True       workItemLink
Shared Steps          Microsoft.VSTS.TestCase.SharedStepReferencedBy-Reverse       True       workItemLink
Successor             System.LinkTypes.Dependency-Forward                          True       workItemLink
Predecessor           System.LinkTypes.Dependency-Reverse                          True       workItemLink
Child                 System.LinkTypes.Hierarchy-Forward                           True       workItemLink
Parent                System.LinkTypes.Hierarchy-Reverse                           True       workItemLink
Related               System.LinkTypes.Related                                     True       workItemLink
Remote Related        System.LinkTypes.Remote.Related                              True       workItemLink
Attached File         AttachedFile                                                 True       resourceLink
Hyperlink             Hyperlink                                                    True       resourceLink
Artifact Link         ArtifactLink                                                 True       resourceLink

O formato json padrão fornece informações adicionais sobre os atributos definidos para os tipos de link. Por exemplo, as informações dos tipos de link Produz para e Consome de são listadas conforme indicado a seguir.

  {
    "attributes": {
      "acyclic": true,
      "directional": true,
      "editable": false,
      "enabled": true,
      "isForward": true,
      "oppositeEndReferenceName": "System.LinkTypes.Remote.Dependency-Reverse",
      "remote": true,
      "singleTarget": true,
      "topology": "dependency",
      "usage": "workItemLink"
    },
    "name": "Produces For",
    "referenceName": "System.LinkTypes.Remote.Dependency-Forward",
    "url": "https://dev.azure.com/mseng/_apis/wit/workItemRelationTypes/System.LinkTypes.Remote.Dependency-Forward"
  },
  {
    "attributes": {
      "acyclic": true,
      "directional": true,
      "editable": false,
      "enabled": true,
      "isForward": false,
      "oppositeEndReferenceName": "System.LinkTypes.Remote.Dependency-Forward",
      "remote": true,
      "singleTarget": true,
      "topology": "dependency",
      "usage": "workItemLink"
    },
    "name": "Consumes From",
    "referenceName": "System.LinkTypes.Remote.Dependency-Reverse",
    "url": "https://dev.azure.com/mseng/_apis/wit/workItemRelationTypes/System.LinkTypes.Remote.Dependency-Reverse"
  },

`witadmin listlinktypes`

Você pode listar os tipos de link com suporte para sua coleção de projetos usando a ferramenta de linha de comando witadmin listlinktypes ou o comando da API REST Work Item Relation Types - List.

Aqui, listamos os tipos de link para a coleção padrão fabrikam-sever:

C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer>witadmin listlinktypes /collection:http://fabrikam-server/DefaultCollection

Reference Name: Microsoft.VSTS.TestCase.SharedParameterReferencedBy
Names: Referenced By, References
Topology: Dependency
Is Active: True

Reference Name: Microsoft.VSTS.Common.TestedBy
Names: Tested By, Tests
Topology: Dependency
Is Active: True

Reference Name: Microsoft.VSTS.TestCase.SharedStepReferencedBy
Names: Test Case, Shared Steps
Topology: Dependency
Is Active: True

Reference Name: System.LinkTypes.Duplicate
Names: Duplicate, Duplicate Of
Topology: Tree
Is Active: True

Reference Name: System.LinkTypes.Dependency
Names: Successor, Predecessor
Topology: Dependency
Is Active: True

Reference Name: System.LinkTypes.Hierarchy
Names: Child, Parent
Topology: Tree
Is Active: True

Reference Name: System.LinkTypes.Related
Name: Related
Topology: Network
Is Active: True

Atributos de tipo de link

A tabela a seguir fornece descrições de cada um dos atributos de tipo de link retornados pela CLI do Azure Boards ou pela API REST.

Atributo

Descrição

Nomes, name

Especifica o nome amigável atribuído aos tipos de link. Links direcionais são definidos em pares, portanto, incluem um nome para frente e um inverso.

Nome de referência, referenceName

Especifica o nome atribuído ao tipo de link ou ao par de tipos de link.

acyclic

Indica se o tipo de link permite (true) ou restringe (false) relações circulares. Por exemplo, links de tipo de árvore restringem relações circulares. Para saber mais, confira Referência de elementos LinkTypes.

directional

Indica se o tipo de link é direcional (true) ou não (false). Os tipos de link direcionais são definidos em pares com um componente de avanço e um inverso. Para saber mais, confira Referência de elementos LinkTypes.

editable

Indica se o tipo de link é editável (true) ou não (false). Você só pode adicionar e editar tipos de link personalizados para implantações locais usando a ferramenta de linha de comando witadmin Gerenciar tipo de link. Os tipos de link do sistema sempre têm editable=false.

Está Ativo, enabled

Indica se o tipo de link está ativo (true) ou não (false). Você só pode usar tipos de link personalizados para implantações locais por meio da ferramenta de linha de comando witadmin Gerenciar tipo de link.

isForward

Indica se o tipo de link especifica o link para frente (true) ou não (False) em um par de tipos de link.

oppositeEndReferenceName

Especifica o nome de referência do tipo de link que define o link na direção oposta de um par de tipos de link.

remote

Indica se o tipo de link dá suporte à vinculação a um item de trabalho remoto (true) ou não (False). Os tipos de link com remote=false exigem que o item de trabalho de destino resida na mesma organização ou coleção que o item de trabalho de origem.

singleTarget

Indica se o tipo de link permite mais de um destino (false) ou se é restrito a um só destino (true).

topology

Especifica o tipo de topologia — dependência, rede, and árvore. Para ver descrições, confira Topologias e restrições de tipo de link.

usage

Especifica o tipo de uso — resourceLink ou workItemLink. O valor de workItemLinkvalue indicates a link type that links two work items. TheresourceLink indica um tipo de link usado para vincular um item de trabalho a um recurso, como uma URL ou um anexo.

url

Lista os atributos do tipo de link no formato JSON.

Compartilhar via

Guia de referência para tipos de link

Tipo de link de trabalho

Hyperlink

Tipo de link externo

Tipo de link do GitHub

Tipo de link de trabalho remoto

Tipo de link personalizado

Listar tipos de link

az boards work-item relation list-type

Parâmetros opcionais

Exemplo

`witadmin listlinktypes`

Atributos de tipo de link

Comentários

Recursos adicionais

Compartilhar via

Guia de referência para tipos de link

Tipo de link de trabalho

Hyperlink

Tipo de link externo

Tipo de link do GitHub

Tipo de link de trabalho remoto

Tipo de link personalizado

Listar tipos de link

az boards work-item relation list-type

Parâmetros opcionais

Exemplo

witadmin listlinktypes

Atributos de tipo de link

Artigos relacionados

Comentários

Recursos adicionais

`witadmin listlinktypes`