リンクの種類に関するリファレンス ガイド

  • [アーティクル]

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

さまざまなリンクの種類を使って、作業項目と他の成果物 (ビルド、コミット、pull request など) の間のさまざまな関係を管理できます。 この記事では、次のリンクの種類について説明します。

特定のフィールドでは、最初の 4 つのリンクの種類 ("関連リンク数"、"ハイパーリンク数"、"外部リンク数"、"リモート リンク数" など) のリンク数を保持します。

  • 作業リンクの種類: テスト ケース管理作業項目の選択を含む作業項目をリンクします
  • ハイパーリンク: 作業項目を任意の URL またはネットワーク共有に接続します
  • 外部リンクの種類: 作業項目をコード オブジェクト、ビルド、または Wiki ページなどの外部オブジェクトに接続します
  • GitHub リンクの種類: 作業項目を GitHub リポジトリのコミットまたは pull request に接続します。

特定のフィールドでは、最初の 3 つのリンクの種類 (" 関連リンク数"、"ハイパーリンク数"、"外部リンク数" など) のリンク数を保持します。

リンクの種類は、そのトポロジに基づいて特定の制限を受けます。 次の表に記載されているガイダンスを使い、作成するクエリやレポートの種類に基づいて使うリンクの種類を選びます。 さまざまなトポロジの詳細については、「リンクの種類のトポロジと制限」を参照してください。

作業リンクの種類は、システム定義、プロセス定義、またはユーザー定義 (カスタム) です。 次の表に示すリンクはシステム定義です。

作業リンクの種類ごとに、作業項目間のリンクの構築時に使われるリンク ラベル、トポロジの種類、制限事項が定義されます。 たとえば、親子リンクの種類では、親と子という 2 つのラベルが定義されています。 また、リンクの種類は階層型トポロジやツリー トポロジをサポートし、作業項目間で循環参照が作成されないようにします。

作業項目リンクの種類の概念イメージ。

作業項目の "関連リンク数" は、作業リンクの種類で定義されたすべてのリンクの合計に対応します。

次の表では、WorkItemLinksFilter XML 要素を使って、リンク コントロールのスコープを設定するために指定できる作業項目リンクの種類について説明します。

名前

参照名

使用方法

影響先 - 影響元 (CMMI のみ) 影響のリンクの種類の概念図。リンクの種類によって受ける影響の概念図。

Microsoft.VSTS.Common.Affects-Forward
Microsoft.VSTS.Common.Affects-Reverse
トポロジの種類: 依存関係
リンクのカテゴリ: プロセス定義

この方向リンクを使って、任意の作業項目セット間のリンクを作成しますが、閉じたループを作成するものではありません。 通常、要件に対して行われた変更要求を追跡するために使われます。

制限事項と推奨事項:

  • 変更要求を [影響先] を使用してリンクできるのは、1 つの要件だけです。 要件は、[影響元] を使用して、必要なだけの数の子変更要求にリンクすることができます。
  • 同じプロジェクトの作業項目は、[影響先]-[影響元] リンクだけを使ってリンクします。 この操作は、Excel を使って作業項目のデータを変更または更新する予定がある場合に推奨されます。

子-親
子リンクの種類の概念図。
親リンクの種類の概念図。

System.LinkTypes.Hierarchy-Forward
System.LinkTypes.Hierarchy-Reverse
トポロジの種類: ツリー
リンクのカテゴリ: システム定義

この方向リンクを使って、1 つの親と 1 つ以上の子項目との間に一対多の関係を作成します。 階層内の作業項目を整理するために使います。 この階層は、マッピング機能を使ってバックログ項目間に、またはスプリント バックログかタスクボードを使ってバックログ項目とタスク間にすばやく作成できます。

一般的な用途は次のとおりです。

  • タスク サマリーの関係を維持します。 親子リンクは、サマリー タスクとその下位のタスクに対して作成されます。
  • タスクをPBI、ユーザー ストーリー、または要件にリンクします。 バックログの概要、ストーリーの概要、要件の概要のレポートをサポートします。

制限事項と推奨事項:

  • Excel を使用して、作業項目と親子リンクの両方を一括編集します。 Excel での作業項目の一括追加または変更に関する記事を参照してください。
  • 1 つの作業項目が持てる親は 1 つだけです。 1 つの親作業項目は、多数の子を持つことができます。
  • 同じプロジェクトの作業項目は、親子リンクだけを使ってリンクします。 この操作は、Excel を使って作業項目のデータを変更または更新する予定がある場合に推奨されます。

複製-複製元前方へのツリー複製の概念図。後方へのツリー複製の概念図。

System.LinkTypes.Duplicate-Forward
System.LinkTypes.Duplicate-Reverse
トポロジの種類: ツリー
リンクのカテゴリ: システム定義

この方向リンクを使って、1 つの親と 1 つ以上の子項目との間に一対多の関係を作成します。 互いに複製元となるタスク、バグ、または他の作業項目を追跡するために使います。

制限事項と推奨事項:

  • 1 つの作業項目が持てる [複製] は 1 つだけです。
  • 同じプロジェクト内の作業項目をリンクするには、[複製] または [複製元] リンクのみを使います。 この操作は、Excel を使って作業項目のデータを変更または更新する予定がある場合に推奨されます。

参照元-参照
リンクの種類によるテスト済みの概念図。テストのリンクの種類の概念図。

Microsoft.VSTS.TestCase.
SharedParameterReferencedBy
トポロジの種類: 依存関係
リンクのカテゴリ: プロセス定義

テスト ケースを共有パラメーターにリンクするために使います。 テスト ケースを共有パラメーターにリンクして、異なるデータでテストを繰り返す機能をサポートするために使います。 一般に、このリンクの種類をスコープ付きリンク コントロールに追加することはありません。

関連項目
関連リンクの種類の概念図。

System.LinkTypes.Related
トポロジの種類: ネットワーク
リンクのカテゴリ: システム定義

この非方向リンクは、任意の作業項目セット間のリンクを作成するために使います。 相互に重複する機能を定義する 2 つのユーザー ストーリーなど、同じレベルにある作業項目をリンクするために使います。 関連リンクの種類は、ほとんど制限のない単純な関係を作成します。

  • 相互に重複する機能を定義する 2 つのユーザー ストーリーなど、同じレベルにある作業項目に関連付けます。
  • 異なるプロジェクトで定義され異なるチームで管理される作業項目をリンクします。
  • 2 階層のビューで、作業項目とそれに関連する作業項目を検索および表示する。
  • 制限がほとんどない単純な関係を作成する。

後続処理-先行処理
前方への後続依存関係の概念図。後方への先行依存関係の概念図。

System.LinkTypes.Dependency

トポロジの種類: 依存関係
リンクのカテゴリ: システム定義
リンク元の作業項目より先に完了すべき作業項目にリンクする場合は、先行処理リンクの種類を選びます。 リンク元の作業項目の "後" に完了すべき作業項目にリンクする場合は、後続処理リンクの種類を選びます。

この方向リンクを使って、任意の作業項目セット間のリンクを作成しますが、閉じたループを作成するものではありません。 他のタスクを開始する前に完了する必要があるタスクを追跡するために使います。 リンクされたタスクは、Azure Boards の先行タスクの後続リンクとして表されます。

  • 他のタスクが開始可能になる前に、完了する必要があるタスクを追跡します。
  • 一対多の関係をサポートします。
  • 2 階層のダイレクト リンク クエリのビューで、先行作業項目とその後続作業項目を検索および表示します。

制限事項と推奨事項:

  • 循環関係を定義するリンクを作成しようとするとエラーが表示されます。
  • 先行処理-後続処理リンクは、同じプロジェクト内の作業項目に対してのみ作成します。 別々のプロジェクトで定義されている作業項目の間に先行処理/後続処理リンクを作成できます。 ただし、クエリを Excel にエクスポートすると、クエリが定義されているプロジェクトに対して定義されている作業項目のみがインポートされます。

テスト担当者-テスト
リンクの種類によるテスト済みの概念図。テストのリンクの種類の概念図。

Microsoft.VSTS.Common.TestedBy-Forward
Microsoft.VSTS.Common.TestedBy-Reverse
トポロジの種類: 依存関係
リンクのカテゴリ: プロセス定義

テスト ケースを、バグ、ユーザー ストーリー、要件、プロダクト バックログ項目などの作業項目にリンクします。 ユーザー ストーリー (アジャイル)、プロダクト バックログ項目 (スクラム)、または要件 (CMMI) をテストするテスト ケースを追跡するために使います。 また、バグ、issue、タスクなど、他の作業項目の種類にリンクすることもできます。 オンプレミスの Azure DevOps では、これらのリンクに依存するいくつかの SQL レポートがあります。 「役に立つレポートをサポートするチーム アクティビティの確認」を参照してください。

テスト ケース - 共有ステップ
リンクの種類によるテスト済みの概念図。テストのリンクの種類の概念図。

Microsoft.VSTS.TestCase.
SharedStepReferencedBy
トポロジの種類: 依存関係
リンクのカテゴリ: プロセス定義

テスト ケースと共有ステップをリンクさせるために使います。 テスト ケース間でステップを共有することで、同じ一連のステップのエントリを複数作成する必要がなくなります。

ハイパーリンクは、作業項目を任意の URL にリンクできます。 ハイパーリンク数 は、作業項目に対するハイパーリンクの数を追跡します。

ハイパーリンクの概念図。

リンク名

サポートされているツール

成果物の種類

使用方法

ハイパーリンク

作業項目トラッキング

ハイパーリンク

作業項目を URL にリンクするために使います。 作業項目ハイパーリンクは、成果物リンクの種類 API におけるこのリンクの種類の名前です。

外部リンクの種類は、次の図に示すように、作業項目を Azure DevOps 内に格納されている他のオブジェクトにリンクすることをサポートする、システム定義のリンクの種類です。 作業項目の "外部リンク数" は、外部リンクの種類で定義されたすべてのリンクの合計に対応します。

外部リンクの種類の概念図。

Note

外部リンクの種類は、Azure DevOps オブジェクトへのリンクにのみ使用できます。 作業項目を Azure DevOps 以外の他のオブジェクトにリンクするには、ハイパーリンクを使用します。

次の表では、作業項目またはテスト ケースからリンクの種類を追加するときに選択できる外部リンクの種類について説明します。

次の表では、作業項目またはテスト ケースからリンクの種類を追加するときに選択できる外部リンクの種類について説明します。 また、ExternalLinksFilter XML 要素を使い、これらのリンクの種類の 1 つを指定して、リンク コントロールのスコープを設定することもできます。

リンク名

サポートされているツール

成果物の種類

使用方法

[Branch]\(ブランチ)

Git

[Branch]\(ブランチ)

作業項目をブランチにリンクするために使います。

パイプライン/ビルド

Build

Build

作業項目をビルドにリンクするために使います。

変更セット (または変更セットで修正)

VersionControl

[変更セット]

作業項目を変更セットにリンクするために使います。

コミット (またはコミットで修正)

Git

Commit

作業項目をコミットにリンクするために使います。

発見されたビルド

パイプライン/ビルド

Build

作業項目をビルドにリンクするために使います。

ビルドに統合

Build

ビルド パイプライン

作業項目をビルドにリンクするために使います。

リリース環境に統合

リリース

リリース パイプライン

リリースを作業項目にリンクするために使います。 ユーザーがリリース定義の [配置の状態を作業として報告] オプションを有効にすると、システムでこの種類のリンクが作成されます。

Pull Request

Git

PullRequestId

作業項目を pull request にリンクするために使います。

結果の添付ファイル

テスト管理

TcmResultAttachment

作業項目をテスト結果に関連付けられた添付ファイルにリンクするために使います。 これらのリンクは、作業項目を、[テスト] または Microsoft Test Manager からのテスト結果に関連付けた場合に表示されます。

ソース コード ファイル<

VersionControl

LatestItemVersion

作業項目を Team Foundation バージョン管理 (TFVC) 下のファイルにリンクするために使います。

Storyboard

必要条件

Storyboard

PowerPoint ファイル、またはネットワーク上のストーリー ボード情報が含まれる他のファイルに作業項目をリンクするために使います。

タグ

Git

Tag

作業項目を git コミットまたは git リポジトリに定義されているタグにリンクするために使います。 詳細については、Git コマンド プロンプトの作業に関する記事を参照してください。

テスト結果

テスト管理

TcmResult

作業項目をテスト結果にリンクするために使います。 これらのリンクは、作業項目を、[テスト] または Microsoft Test Manager からのテスト結果に関連付けた場合に表示されます。

バージョン管理された項目

VersionControl

LatestItemVersion

TFVC リポジトリ内で定義されているファイルまたは変更セットに作業項目をリンクするために使います。 ソース コード ファイルは成果物リンクの種類 API におけるこのリンクの種類の名前です。

Wiki

Wiki

Wiki

作業項目を Wiki ページにリンクするために使います。 TFS 2018.2 以降のバージョンでサポートされています。

GitHub リンクの種類はシステム定義であり、次の図に示すように、GitHub オブジェクトへの作業項目のリンクをサポートします。

GitHub リンクの種類の概念図。

GitHub リンクの種類の概念図。

重要

Azure Boards に接続したリポジトリを使用する GitHub 成果物にのみリンクできます。

次の表では、作業項目からリンクの種類を追加するときに選択できる GitHub リンクの種類について説明します。

リンク名

成果物の種類

使用方法

GitHub コミット

GitHub リポジトリ コミット

作業項目を GitHub のコミットにリンクするために使います。

GitHub issue

GitHub リポジトリ issue

作業項目を GitHub の issue にリンクするために使います。

GitHub pull request

GitHub リポジトリ pull request

作業項目を GitHub の pull request にリンクするために使います。

リモート作業リンクの種類はシステム定義のリンクの種類で、「組織を Microsoft Entra ID に接続する」で説明されているように、同じ Microsoft Entra ID で管理されている限り、異なる組織で定義された作業項目のリンクをサポートします。

作業項目の "リモートリンク数" は、リモート作業リンクの種類で定義されたすべてのリンクの合計に対応します。

名前

参照名

使用方法

使用元-生成対象
(依存関係トポロジ) トポロジーからの消費量の概念図。トポロジーへの生成の概念図。

System.LinkTypes.Remote.Dependency-Forward
System.LinkTypes.Remote.Dependency-Reverse
トポロジの種類: 依存関係
リンクのカテゴリ: システム定義

この方向リンクを使用して、同じ Microsoft Entra ID で管理されている限り、依存関係があり、異なる組織で定義されている作業項目間のリンクを作成します。 通常、要件に対して行われた変更要求を追跡するために使われます。

リモート関連
リモート関連トポロジーの概念図。

System.LinkTypes.Remote.Related
トポロジの種類: ネットワーク
リンクのカテゴリ: システム定義

同じ Microsoft Entra ID で管理されている限り、この非方向リンクを使用して、異なる組織で定義された作業項目間のリンクを作成します。

カスタム リンクの種類の作成、リンクの種類の定義のエクスポートとインポート、リンクの種類の削除、アクティブ化、非アクティブ化、再アクティブ化を実行できます。 次の記事をご覧ください。

リンクの種類の一覧を取得するには、サポートするコマンド ライン ツールのいずれかを使います。

az boards work-item relation list-type

az boards work-item relation list-type コマンドまたは Work Item Relation Types - List REST API コマンドで、組織でサポートするリンクの種類を一覧表示できます。 開始するには、「Azure DevOps CLI の概要」を参照してください。

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

省略可能なパラメーター

  • org: Azure DevOps 組織の URL。 az devops configure -d organization=ORG_URL を使用して、既定の組織を構成できます。 既定として設定されていない場合、または git config を使用して取得された場合は必須です。 例: --org https://dev.azure.com/MyOrganizationName/.

例

次のコマンドは、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

既定の json 形式では、リンクの種類に定義されている属性に関する追加情報が提供されます。 たとえば、リンクの種類 "生成対象" と "使用元" の情報は、次のように一覧表示されます。

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

witadmin listlinktypes コマンド ライン ツールまたは Work Item Relation Types - List REST API コマンドを使うと、プロジェクト コレクションでサポートされているリンクの種類を一覧表示できます。

ここでは、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

次の表では、Azure Boards CLI または REST API で返されるリンクの種類の各属性について説明します。

属性

説明

名前、name

リンクの種類に割り当てられたフレンドリ名を指定します。 方向リンクはペアで定義されるため、順方向と逆方向の名前が含まれます。

参照名、referenceName

リンクの種類、またはリンクの種類のペアに割り当てられた名前を指定します。

acyclic

リンクの種類が循環関係を許容するか (true)、制限するか (false) を示します。 たとえば、ツリー型のリンクは、循環関係を制限します。 詳細については「LinkTypes 要素リファレンス」を参照してください。

directional

リンクの種類が方向付きか (true)、そうでないか (false) を示します。 方向リンクの種類は、順方向と逆方向のコンポーネントのペアで定義されます。 詳細については「LinkTypes 要素リファレンス」を参照してください。

editable

リンクの種類が編集可能か (true)、そうでないか (false) を示します。 witadmin リンクの種類の管理コマンド ライン ツールを使って、オンプレミス デプロイでのカスタム リンクの種類の追加と編集のみができます。 システム リンクの種類は常に editable=false になります。

アクティブ、enabled

リンクの種類がアクティブか (true)、そうでないか (false) を示します。 witadminリンクの種類の管理コマンドライン ツールを使って、オンプレミス デプロイでのカスタム リンクの種類のみを使用できます。

isForward

リンクの種類が、リンクの種類のペア内の順方向リンクを指定しているか (true)、いないか (False) を示します。

oppositeEndReferenceName

リンクの種類のペアの逆方向にリンクを定義するリンクの種類の参照名を指定します。

remote

リンクの種類がリモート作業項目へのリンクをサポートするか (true)、しないか (False) を示します。 remote=false のリンクの種類では、ターゲット作業項目が元の作業項目と同じ組織またはコレクションに存在する必要があります。

singleTarget

リンクの種類が複数のターゲットを許容するか (false)、1 つのターゲットに制限されるか (true) を示します。

topology

トポロジの種類 (依存関係, ネットワーク, and ツリー) を指定します。 詳細については、「リンクの種類のトポロジと制限」を参照してください。

usage

使用の種類 (resourceLink または workItemLink) を指定します。 workItemLinkvalue indicates a link type that links two work items. TheresourceLink' の値は、URL や添付ファイルなどのリソースに作業項目をリンクするために使用されるリンクの種類を示します。

url

リンクの種類の属性を json 形式のリストにします。