次の方法で共有

チュートリアル: リンクされた作業項目のクエリ

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

Azure DevOps の Analytics に対して Open Data Protocol (OData) クエリを実行すると、作業項目に関する情報を取得できます。 リンクされた作業項目に対してクエリを実行することもできます。 作業項目は、親リレーションシップや子リレーションシップなど、階層的にリンクできます。 作業項目は、作業項目が関連している場合や重複している場合など、非階層的にリンクすることもできます。

リンクされた作業項目に対してクエリを実行する方法は、ナビゲーション プロパティを使用してエンティティ セットのクエリをフィルター処理する方法と似ています。 ただし、リンクはエンティティであるため、複雑さが増します。 リンクされた作業項目に対してクエリを実行するには、次の 2 つの方法があります。

  • ParentまたはChildrenナビゲーション プロパティを使用する
  • Links ナビゲーション プロパティを使用する

このチュートリアルでは、次のことを行います。

  • 階層的にリンクされた作業項目を返すクエリを作成します。
  • 非階層的にリンクされた作業項目を返すクエリを作成します。

手記

Analytics サービスは、Azure DevOps Services 内のすべてのサービスに対して運用環境で自動的に有効になり、サポートされます。 Power BI の統合 と、Analytics サービスの OData フィード へのアクセスが一般公開されています。 Analytics OData フィードを使用し、フィードバックを提供することをお勧めします。

使用可能なデータはバージョンによって異なります。 OData API のサポートされている最新バージョンが v2.0され、最新のプレビュー バージョンが v4.0-preview。 詳細については、OData API のバージョン管理 を参照してください。

手記

Analytics サービスは、Azure DevOps Server 2020 以降のすべての新しいプロジェクト コレクションに対して、運用環境で自動的にインストールされ、サポートされます。 Power BI の統合 と、Analytics サービスの OData フィード へのアクセスが一般公開されています。 Analytics OData フィードを使用し、フィードバックを提供することをお勧めします。 Azure DevOps Server 2019 からアップグレードする場合は、アップグレード中に Analytics サービスをインストールできます。

使用可能なデータはバージョンによって異なります。 OData API のサポートされている最新バージョンが v2.0され、最新のプレビュー バージョンが v4.0-preview。 詳細については、OData API のバージョン管理 を参照してください。

前提 条件

カテゴリ 必要条件
アクセス レベル - プロジェクトメンバー。
- 少なくとも ベーシック アクセス。
アクセス許可 既定では、プロジェクト メンバーには Analytics にクエリを実行してビューを作成する権限があります。 サービスと機能の有効化と一般的なデータ追跡アクティビティに関するその他の前提条件の詳細については、「アクセス許可と、Analyticsにアクセスするための前提条件」を参照してください。

手記

この記事の例では、Azure DevOps Services URL を次の形式で使用します。

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

Azure DevOps Server の場合は、代わりに次の形式を使用します。これにはオンプレミス サーバーが含まれます。

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

親または子の作業項目を取得するクエリ

$expandおよびParent ナビゲーション プロパティのChildren オプションを使用して、親子リンクを介して関連するアイテムに対してクエリを実行できます。

例: アイテムの子要素を取得する

アイテムの子に関する情報を返すには、$expand ナビゲーション プロパティでChildrenを使用します。 次の OData コードは、fabrikam 組織内の Fabrikam Fiber プロジェクトに対してクエリを実行します。 ID 359 の作業項目の子項目を返します。

要求

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)

応答には、ID 479 と 480 の機能作業項目に関する情報が一覧表示されます。 これらの機能は、ID 359 のエピック作業項目の子である。

手記

作業項目リンク情報を要求するほとんどの OData クエリは、結果を返しますが、警告も返します。 この警告は、 OData Analytics クエリ ガイドラインで説明されている推奨されるクエリ ガイドラインに従うことをお勧めします。 ただし、この記事のクエリ例は有効です。

応答

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

例: アイテムの親を要求する

Childrenを Parent オプションの$expandに置き換えることで、アイテムの先祖を取得できます。

次のコードは、Fabrikam Fiber プロジェクトと fabrikam 組織の ID 1048 を持つ作業項目の親を照会します。

要求

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

応答には、ID 480 の機能に関する情報が一覧表示されます。これは、ID 1048 の製品バックログ項目の親です。

応答

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

親子リンクに加えて、 Related や Duplicate などの他の種類の作業項目もリンクできます。 Links ナビゲーション プロパティを使用すると、非階層リレーションシップを介してリンクされた作業項目に関する情報を要求できます。

アイテムに関連付けられているリンクを取得するには、$expand ナビゲーション プロパティで Links オプションを使用します。 次のクエリでは、作業項目 363 に関連付けられているすべてのリンクの SourceWorkItemId、 TargetWorkItemId、および LinkTypeName の値を取得します。

要求

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)

応答

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

例: リンクされたアイテムに関する詳細情報を要求する

リンクされた作業項目に関する詳細情報を照会するには、$expandまたはTargetWorkItemナビゲーション プロパティのSourceWorkItemオプションを使用します。

前のクエリと同様に、次のクエリは、作業項目に関連付けられているすべてのリンクの SourceWorkItemId、 TargetWorkItemId、および LinkTypeName の値を取得します。 ただし、このクエリでは、各リンクのターゲット作業項目の WorkItemId、 Title、および State 値も取得されます。

要求

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

応答

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

項目間の特定の種類のリンクに関心がある場合は、LinkTypeName句で $filter プロパティを使用できます。 次のクエリは、すべての Related リンクを展開し、作業項目 103 の他のすべてのリンクの種類を除外します。

要求

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

応答

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

関連コンテンツ

  • Last updated on