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

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

Analytics OData クエリを使用して、ブラウザーまたは Excel や Power BI などのクライアント ツールで Azure DevOps から作業追跡データを取得します。 この記事では、アイテムのカウント、 $selectを使用した特定のフィールドの選択、 $filterによるフィルター処理、 $expandを使用したナビゲーション プロパティの展開、日付範囲のクエリ、 $orderbyによる並べ替えについて説明します。

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

前提条件

アイテムの数を取得する

他のデータなしでカウントのみを返すには、エンティティ セットの URL に $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)

Projects組織のfabrikam クエリは、次を返します。

{
  "value": [
    {
      "Count": 16
    }
  ]
}

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

データと共にカウントを返すには、$count=true句を含むクエリに$selectを追加します。 次のクエリは、プロジェクト内の作業項目、エリア パス、およびユーザーのカウントと選択したプロパティを返します。

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

有効なプロパティ名については、「 Azure Boards Analytics のメタデータ リファレンス 」と 「カレンダーの日付、プロジェクト、およびユーザーメタデータリファレンス」を参照してください。

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

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

応答には、 @odata.count の合計数と、一致するレコードが valueに含まれます。

{
  "@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句を追加して、必要なプロパティのみを返します。 プロパティ名では大文字と小文字が区別され、スペースを含めず、作業項目のフィールド名に対応します。 たとえば、 $select=WorkItemId,WorkItemType,Title,State はこれら 4 つのフィールドを返します。

カスタム フィールドを含むプロパティ名の参照については、 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

{
  "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 句を追加します。 eq、ne、gt、ge、lt、leなどの比較演算子を使用し、条件をandとorと組み合わせます。 たとえば、次のクエリは進行中の機能を返します。

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'

複数のフィルター条件を結合する

かっこを使用して、or条件をより広範なandフィルター内でグループ化します。 次のクエリは、特定の状態のユーザー ストーリー、バグ、およびカスタム型を返します。

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

{
  "value": [
    { "WorkItemId": 210, "Title": "Slow response on form", "State": "Active" },
    ...
    { "WorkItemId": 160, "Title": "Game store testing", "State": "New" }
  ]
}

フィルター式では、 contains、 startswith、 endswith などの文字列関数を使用することもできます。 詳細については、「 サポートされている関数」を参照してください。

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

一部のクエリでは、パス文字列ではなく代理キー (AreaSK または IterationSK) が必要です。 Areas または Iterations エンティティ セットを使用して、特定のパスのキーを検索します。

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

次のクエリは、Fabrikam Fiber\Production Planning\Webエリア パスのAreaSK を返します。 その他の使用可能なプロパティについては、「 区分」を参照してください。

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

{
  "value": [
    { "AreaSK": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" }
  ]
}

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

次のクエリは、Fabrikam Fiber\Release 1\Sprint 3イテレーション パスに対するIterationSKを返します。 その他の使用可能なプロパティについては、「 イテレーション」を参照してください。

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、Area、AssignedToなどのナビゲーション プロパティは、他のエンティティとのリレーションシップを表します。 関連エンティティからフィールドをフィルター処理するには、 NavigationProperty/Field形式の完全なパスを使用します。 たとえば、Iteration/IterationPathは、IterationPath ナビゲーション プロパティを使用してIteration フィールドを参照します。

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

次のクエリは、完全なナビゲーション パスを使用して、特定のイテレーションの上位 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

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

ナビゲーション プロパティによるフィルター処理では、そのデータは応答に含まれません。 関連エンティティからフィールドを返すには、 $expandを使用します。 $expandがないと、$selectを介してナビゲーション プロパティ フィールドにアクセスすることはできません。

次のクエリは、展開された480 エンティティのすべてのフィールドを含む作業項目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展開にはIterationが適用されないため、応答にはすべての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",
        "IterationName": "Sprint 3",
        "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",
        ...
        "Depth": 2,
        "IsEnded": false
      }
    }
  ]
}

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

展開されたエンティティから返されるフィールドを制限するには、構文$selectを使用して$expand内に$expand=Entity($select=Field1,Field2)句を追加します。 次のクエリは Iteration を展開しますが、 IterationName と IterationPathのみを返します。

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)

{
  "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と共に示しています。

1 つのクエリで複数のナビゲーション プロパティを展開するには、コンマ区切りのリストを使用します。

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

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

既に展開されているエンティティ内でナビゲーション プロパティを展開するには、1 つの $expand を別のエンティティ内に入れ子にします。 次のクエリでは、Iterationを展開し、Project内の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($expand=Project)

入れ子になった展開と$selectを組み合わせるには、セミコロン (;) を使用して、かっこ内の$selectから$expandを区切ります。 セミコロンを指定しないと、クエリはエラーを返します。 次のクエリは、IterationNameからIterationPathとIterationと入れ子になったProjectのみを返します。

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)

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "Project": {
          "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber"
        }
      }
    }
  ]
}

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

次のクエリ例は、最後の 変更日 が 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 and ChangedDate le 2025-11-07Z

結果を並べ替える

$orderbyを追加して、1 つ以上のプロパティで結果を並べ替えます。 既定では、結果は昇順で並べ替えられます。降順の desc を追加します。 複数の並べ替えフィールドをコンマで区切ります。

次のステップ

関連コンテンツ

• Analytics の OData クエリを作成する
• Analytics を使用してデータを集計する
• Azure Boards Analytics のメタデータ リファレンス
• Analytics に対してクエリを実行するときに使用するベスト プラクティス
• サポートされている OData 機能
• OData v4.0 パート 2: URL 規則と Errata 02