OData Analytics を使用して基本的なクエリを定義する

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

Azure DevOps 用の Analytics を使用して、関心のあるデータを返す OData クエリを作成できます。これらのクエリは、ブラウザーまたは Excel や Power BI などのクライアントソフトウェアで実行できます。

この記事では、Azure Boards の作業追跡エンティティセットを取得するためのクエリに焦点を当てていますが、原則は他のエンティティセットのクエリに適用されます。詳細については、「Azure Boards Analytics の分析とメタデータに関する OData クエリの構築」を参照してください。

このチュートリアルでは、次の方法について説明します。

データの有無にかかわらず、項目数を返すクエリを定義します。
特定のプロパティに関連するデータを返すために選択してください。
特定のプロパティでデータをフィルター処理します。
IDENTITY、Area Path、Iteration Path などのナビゲーションプロパティのデータを返します。
expand句と入れ子になったexpand ステートメントを使用します。
クエリの日付範囲。
結果を並べ替えるには、 orderby オプションを使用します。

注

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 サービスをインストールできます。

前提条件

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

注

プロジェクト間クエリは、クエリを実行しているユーザーがすべてのプロジェクトにアクセスできない場合に失敗します。要件の詳細については、「プロジェクトと組織スコープのクエリ」を参照してください。

注

この記事の OData クエリでは、Azure DevOps Services ( https://analytics.dev.azure.com/) に定義されているクエリ URL を使用します。 OData のクエリに慣れるには、クエリで自分の組織名とプロジェクト名を置き換えます。

オンプレミスサーバーの場合は、サーバーとプロジェクトコレクションに基づく URL を使用して同様のクエリを作成 https://<servername>/<ProjectCollectionName>/。詳細については、「 Analytics の OData クエリを作成する」を参照してください。

アイテムの数を取得する

他の情報を含めずに、組織またはプロジェクトで定義されているアイテムまたはエンティティの数のみを返すには、 $apply=aggregate($count as Count) クエリオプションを適用します。次のクエリは、組織内のプロジェクト、作業項目、エリアパス、およびユーザーの数を返します。

https://analytics.dev.azure.com/<OrganizationName>/_odata/v4.0-preview/Projects?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/<OrganizationName>/_odata/v4.0-preview/WorkItems?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/<OrganizationName>/_odata/v4.0-preview/Areas?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/<OrganizationName>/_odata/v4.0-preview/Users?$apply=aggregate($count as Count)

上記のクエリは、 fabrikam 組織内のプロジェクトの次の例のような結果を返します。

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(Count)",
  "value": [
    {
      "@odata.id": null,
      "Count": 16
    }
  ]
}

アイテムとそのデータの数を取得する

項目の数と選択した項目のデータを返すには、$count=true ステートメントで select クエリオプションを指定します。次のクエリは、指定されたプロパティと共に、プロジェクトに対して定義された作業項目、エリアパス、およびユーザーの数を返します。有効なプロパティについては、Azure Boards Analytics のMetadata リファレンスとAzure DevOps Analytics の日付、プロジェクト、ユーザーのメタデータリファレンスを参照してください。

https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/v4.0-preview/WorkItems?$count=true&$select=WorkItemId,Title,WorkItemType 
https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/v4.0-preview/Areas?$count=true&$select=AreaName,AreaPath 
https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/v4.0-preview/Users?$count=true&$select=UserName,UserEmail

注

指定したエンティティ型に対して定義されているすべてのプロパティを返すには、$count=true句のないselectを使用できます。ただし、 $select 句や $apply 句を含めない場合は、 VS403507: The specified query does not include a $select or $apply clause which is recommended for all queries. Details on recommended query patterns are available here: https://go.microsoft.com/fwlink/?linkid=861060などの警告が表示されます。使用制限に達しないようにするには、常にクエリに $select 句または $apply 句を含めます。

たとえば、次のクエリでは、Fabrikam Fiber プロジェクトのユーザーの数とユーザー名が要求されます。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Users?$count=true&$select=UserName

このクエリは、ユーザー名を持つ 5 ユーザーの数 を返します。

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Users(UserName)",
  "@odata.count": 5,
  "value": [
    {
      "UserName": "Microsoft.VisualStudio.Services.TFS"
    },
    {
      "UserName": "fabrikamfiber1@hotmail.com"
    },
    {
      "UserName": "Jamal Hartnett"
    },
    {
      "UserName": "fabrikamfiber5@hotmail.com"
    },
    {
      "UserName": "fabrikamfiber2@hotmail.com"
    }
  ]
}

特定のプロパティまたはフィールドを選択する

特定のプロパティまたは作業項目フィールドを返すには、プロパティ名を指定する $select 句を追加します。たとえば、 作業項目 ID、 作業項目の種類、 タイトル、および作業項目の状態を返すには、 $select=WorkItemId,WorkItemType,Title,State 句をクエリに追加します。

$select句は、名前付きフィールドに対応するプロパティ名を指定します。 OData クエリのプロパティ名では、スペースや文字の大小に注意が必要です。 作業項目 ID などのプロパティ表示名にはスペースを含めることができますが、仮のプロパティ名にはスペースを含めることはできません。

プロパティ名とラベルの詳細については、「 Azure Boards のメタデータリファレンス」を参照してください。ユーザー設定フィールドプロパティのラベル付け方法については、「カスタムプロパティ」を参照してください。

次のクエリ例では、Fabrikam Fiber プロジェクトの上位 3 つの作業項目の作業項目 ID、タイトル、および状態を要求します。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$top=3

分析では、次のデータが返されます。

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikamprime/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)",
  "value": [
    {
      "WorkItemId": 31,
      "Title": "About screen",
      "WorkItemType": "Task",
      "State": "New"
    },
    {
      "WorkItemId": 30,
      "Title": "Change background color",
      "WorkItemType": "Task",
      "State": "Active"
    },
    {
      "WorkItemId": 32,
      "Title": "Standardize on form factors",
      "WorkItemType": "Task",
      "State": "Active"
    }
  ]
}

データのフィルター処理

エンティティセットをフィルター処理して特定のアイテムを返すには、項目が満たす必要がある条件を指定する $filter 句を追加します。次のフィルター句は、処理中の状態のフィーチャー作業項目の種類のみを返します。

/WorkItems?$filter=WorkItemType eq 'Feature' and State eq 'In Progress'

次のクエリ例では、機能作業項目のうち、作業中の状態にあるものについてのみ、作業項目 ID、作業項目の種類、タイトル、および状態を返すように指定します。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,AssignedTo,State&$filter=WorkItemType eq 'Feature' and State eq 'In Progress'

複数のフィルター句を指定する

andとorを使用して、1 つの$select句で複数のフィルターを指定できます。たとえば、次のクエリでは、 ユーザーストーリー、バグ、またはカスタム型 のバックログ作業 の種類の作業項目のうち、新規、 コミット済み、または アクティブ 状態の複数のフィールドを指定します。かっこを使用して、必要に応じてフィルター句をグループ化します。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,AssignedTo,State&$filter=(WorkItemType eq 'User Story' or WorkItemType eq 'Bug' or WorkItemType eq 'Backlog Work') and (State eq 'New' or State eq 'Committed' or State eq 'Active')

このクエリは、次の結果のようなデータを返します。


{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,AssignedTo,State)",
  "value": [
    {
      "WorkItemId": 210,
      "Title": "Slow response on form",
      "State": "Active"
    },
    ...
    {
      "WorkItemId": 160,
      "Title": "Game store testing",
      "State": "New"
    }
  ]
}

contains句では、startswith、endswith、$selectなど、さまざまな関数を適用することもできます。サポートされている関数を参照してください。

クエリ領域のパスまたは反復パスのプロパティ

特定のエリアパスまたは反復パスの AreaSK、 IterationSK、またはその他のプロパティを検索するには、次のクエリを使用します。

特定のエリアパスの AreaSK を返します

次のクエリは、AreaSK領域パスに対して定義されたFabrikam Fiber\Production Planning\Web プロパティを要求します。 Areas エンティティセットの他の定義済みプロパティを表示するには、「区分」を参照してください。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Areas?$filter=AreaPath eq 'Fabrikam Fiber\Production Planning\Web' &$select=AreaSK

クエリは次のデータを返します。

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikamprime/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Areas(AreaSK)",
  "value": [
    {
      "AreaSK": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
    }
  ]
}

特定のイテレーションパスの IterationSK を返します

次のクエリは、IterationSKイテレーションパスに対して定義されたFabrikam Fiber\3Week Sprints\Sprint 3 プロパティを返します。 Iterations エンティティセットの他の定義済みプロパティを表示するには、「イテレーション」を参照してください。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Iterations?$filter=IterationPath eq 'Fabrikam Fiber\Release 1\Sprint 3' &$select=IterationSK

ナビゲーションプロパティは、エンティティ型間のリレーションシップを表します。フィルター条件の一部としてナビゲーションプロパティを指定する場合は、ナビゲーションプロパティの完全なパスを指定する必要があります。たとえば、次の句は、ナビゲーションプロパティの指定されたIterationに基づいて作業項目をフィルター処理します。

/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

Iteration はナビゲーションプロパティであり、 IterationPath は関心のあるフィールドです。 Iteration/IterationPath は、 IterationPath プロパティの完全なパスです。

次のクエリ例では、Fabrikam Fiber\3Week Sprints\Sprint 3の完全なパスを指定して、Iteration/IterationPathイテレーションパスの上位 5 つの作業項目からデータを要求します。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Iteration/IterationPath eq 'Fabrikam Fiber\3Week Sprints\Sprint 3'&$select=WorkItemId, WorkItemType, Title, State&$orderby=WorkItemId asc

前の例のクエリでは、 Iteration データは返されません。これは、 Iteration が関連エンティティであるためです。 Identity、Area、Iterationなどのナビゲーションプロパティのプロパティには、$select ステートメントを使用して直接アクセスすることはできません。関連エンティティからデータを返すには、 $expand ステートメントを使用する必要があります。

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 00000&$expand=Iteration

次のクエリ例では、展開された480 データなど、作業項目 ID Iterationに関連付けられている情報を要求します。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration

このクエリは、展開された Iteration プロパティのすべてのフィールドを含む次のデータを返します。

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)",
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "IterationSK": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationId": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationName": "Sprint 3",
        "Number": 276,
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "StartDate": "2025-12-04T00:00:00-12:00",
        "EndDate": "2025-12-25T23:59:59.999-12:00",
        "IterationLevel1": "Fabrikam Fiber",
        "IterationLevel2": "3Week Sprints",
        "IterationLevel3": "Sprint 3",
        "IterationLevel4": null,
        "IterationLevel5": null,
        "IterationLevel6": null,
        "IterationLevel7": null,
        "IterationLevel8": null,
        "IterationLevel9": null,
        "IterationLevel10": null,
        "IterationLevel11": null,
        "IterationLevel12": null,
        "IterationLevel13": null,
        "IterationLevel14": null,
        "Depth": 2,
        "IsEnded": false,
        "AnalyticsUpdatedDate": "2025-10-22T17:28:14.7166667Z"
      }
    }
  ]
}

expand ステートメントで select を使用する

展開されたプロパティが必要以上のデータを返す場合は、プロパティに対して $select ステートメントを追加します。

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 00000&$expand=Iteration($select=Name,IterationPath)

たとえば、次のクエリ例では、展開されたIterationName プロパティからIterationPathとIterationデータのみを選択します。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath)

クエリは次のデータを返します。

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration(IterationName,IterationPath))",
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3"
      }
    }
  ]
}

次の表は、 $expand 句と $select 句を使用して、ナビゲーションプロパティで複数のフィールドを選択する方法を示しています。たとえば、$expand=AssignedTo($select=UserName)を使用して、ナビゲーションプロパティの [ユーザー名] フィールドの Identity] プロパティを取得します。

型フィールド	Referenced プロパティ	句の例
日付と時間	`DateSK`	`$expand=CreatedDate($select=Date)` または `$expand=CreatedDate($select=WeekStartingDate)`
ID	`UserSK`	`$expand=AssignedTo($select=UserName)` または `$expand=AssignedTo($select=UserEmail)`
面グラフ	`AreaSK`	`$expand=Area($select=AreaName)` または `$expand=Area($select=AreaPath)`
反復	`IterationSK`	`$expand=Iteration($select=IterationName)` または `$expand=Iteration($select=IterationPath)` または `$expand=Iteration($select=StartDate)`
プロジェクト	`ProjectSK`	`$expand=Project($select=ProjectName)`
チーム	`TeamSK`	`$expand=Teams($select=TeamName)`

コンマ区切りリストを使用して、1 つの $expand 句で展開する複数のプロパティを指定できます。

$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath)

入れ子になった expand ステートメントを使用する

入れ子になった OData $expand ステートメントを使用できます。たとえば、次のクエリでは、入れ子になった $expand ステートメントを使用して、イテレーションが含まれるプロジェクトを表示します。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($expand=Project)

このクエリは、次のデータを返します。

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)",
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "IterationSK": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationId": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationName": "Sprint 3",
        "Number": 276,
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "StartDate": "2025-12-04T00:00:00-12:00",
        "EndDate": "2025-12-25T23:59:59.999-12:00",
        "IterationLevel1": "Fabrikam Fiber",
        "IterationLevel2": "3Week Sprints",
        "IterationLevel3": "Sprint 3",
        "IterationLevel4": null,
        "IterationLevel5": null,
        "IterationLevel6": null,
        "IterationLevel7": null,
        "IterationLevel8": null,
        "IterationLevel9": null,
        "IterationLevel10": null,
        "IterationLevel11": null,
        "IterationLevel12": null,
        "IterationLevel13": null,
        "IterationLevel14": null,
        "Depth": 2,
        "IsEnded": false,
        "AnalyticsUpdatedDate": "2025-10-22T17:28:14.7166667Z",
        "Project": {
          "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber",
          "AnalyticsUpdatedDate": "2025-10-28T20:27:13.5833333Z",
          "ProjectVisibility": "Private"
        }
      }
    }
  ]
}

たとえば、$selectステートメントを追加して、IterationNameからIterationPathとIterationのみを返すことができます。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath;$expand=Project)

このクエリは、次のデータを返します。

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration(IterationName,IterationPath,Project))",
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "Project": {
          "ProjectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber",
          "AnalyticsUpdatedDate": "2025-10-28T20:27:13.5833333Z",
          "ProjectVisibility": "Private"
        }
      }
    }
  ]
}

結果には、IterationNameとIterationPathがIterationからのみ表示され、ProjectはIteration結果内の入れ子オブジェクトとして扱われます。

注

$expand句を $select ステートメント内に入れ子にする場合は、エラーを回避するために、入れ子になった;の前にセミコロン$expandを使用する必要があります。

日付範囲のクエリを実行する

次のクエリ例は、最後の 変更日 が 2025 年 1 月 1 日以上の作業項目を返します。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-01-01Z

次のクエリ例は、2025 年 10 月 31 日から 11 月 7 日の週に最後の 変更日 が発生した作業項目を返します。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-10-31Z&ChangedDate le 2025-11-07Z

結果を並べ替える

結果を並べ替える $orderby オプションを指定するか、結果を返す順序を指定します。キーワード asc または descを使用して、昇順または降順で並べ替えることができます。次の表に例を示します。

並べ替え順	条項
作業アイテム ID	`/WorkItems?$orderby=WorkItemId`
作業項目 ID の降順	`/WorkItems?$orderby=WorkItemId desc`
作業項目の種類と状態	`/WorkItems?$orderby=WorkItemType,State`

次のステップ

プロジェクトと組織スコープのクエリ

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-12-17

次の方法で共有

OData Analytics を使用して基本的なクエリを定義する

前提条件

アイテムの数を取得する

アイテムとそのデータの数を取得する

特定のプロパティまたはフィールドを選択する

データのフィルター処理

複数のフィルター句を指定する

クエリ領域のパスまたは反復パスのプロパティ

特定のエリア パスの AreaSK を返します

特定のイテレーション パスの IterationSK を返します

ナビゲーション プロパティでフィルター処理する

関連エンティティからデータを展開する