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

[アーティクル]
11/09/2024

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

Azure DevOps 用の Analytics を使用すると、関心のあるデータを返す基本的なクエリとフィルター処理されたクエリを作成できます。これらのクエリは、ブラウザーまたは Power BI 内で直接実行できます。

この記事では、 Analytics の OData クエリの構築および Azure Boards Analytics の Metadata リファレンスで提供される情報を基にしています。また、この記事のクエリは作業追跡エンティティセットの取得に重点を置いていますが、原則は他のエンティティセットのクエリに適用されます。

この記事では、次のデータを返すクエリを定義する方法について説明します。

項目の数 (他のデータなし)
アイテムとデータの数
[領域] または [反復パス] に定義されているプロパティ
選択した列またはフィールド
フィルター処理されたデータ
[ID]、[エリアパス]、[反復パス] フィールドのデータを返します
ナビゲーションプロパティでフィルター処理する
日付範囲のクエリを実行する
expand ステートメントを入れ子にする
結果の並べ替え、並べ替えオプション

Note

Analytics サービスは、すべての Azure DevOps Services で自動的に有効になり、運用環境でサポートされます。 Power BI の統合 Analytics サービスの OData フィードへのアクセスが一般公開されています。お使いいただき、フィードバックをお寄せください。使用可能なデータはバージョンによって異なります。サポートされている最新バージョンが v2.0され、最新のプレビューバージョンが v4.0-preview。詳細については、 OData API のバージョン管理に関するページを参照してください。

Note

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

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

Note

Analytics サービスは、Azure DevOps Server 2019 のプレビュー段階です。プロジェクトコレクション有効またはインストールできます。 Power BI 統合 Analytics Service の OData フィードへのアクセスはプレビュー段階です。お使いいただき、フィードバックをお寄せください。

前提条件

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

Note

この記事では、OData クエリ URL が Azure DevOps Services 用に定義されています。オンプレミスサーバーに対して同様のクエリを作成するには、「 Analytics の OData クエリを構成するに関するページで説明されているガイダンスを参照してください。ブラウザーを使用した 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)

ヒント

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

プロジェクト数

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

作業項目数

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)"
value	
  0	
     @odata.id	null
     Count	    1166

面積の数

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value	
  0	
     @odata.id	null
     Count	    70

ユーザー数

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

アイテムとデータの数を返す

項目の数とアイテムの選択データを返すには、 $count=true クエリオプションを指定します。たとえば、次のクエリは、指定されたプロパティと共に、プロジェクトに対して定義された作業項目、エリアパス、およびユーザーの数を返します。有効なプロパティについては、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

Areas プロパティまたは Iterations プロパティ

Area Path または Iteration Path のAreaSKまたはIterationSK、またはその他のプロパティを検索するには次のクエリを使用します。

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

次のクエリでは、Fabrikam Fiber\Service Delivery\Internet Area Path に対して定義されたAreaSK プロパティを返すように指定します。 Areas エンティティセットに対して定義されているその他のプロパティを指定するには、Azure Boards Analytics、Areas のMetadata リファレンスを参照してください。

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

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

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Areas(AreaSK)",
  "value": [
    {
      "AreaSK": "637dc203-0549-4415-9663-b6358ac27d21"
    }
  ]
}

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

次のクエリでは、Fabrikam Fiber\Release 1\Sprint 3 Iteration Path に対して定義されたIterationSK プロパティを返すように指定します。 Iterations エンティティセットに対して定義されているその他のプロパティを指定するには、「Azure Boards Analytics のMetadata リファレンスイテレーションを参照してください。

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

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

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Iterations(IterationSK)",
  "value": [
    {
      "IterationSK": "862e961a-ac7a-4fcc-9ebc-8afd0c12fed5"
    }
  ]
}

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

特定のプロパティまたは作業項目フィールドを返すには、プロパティ名を指定する $select 句を追加します。

たとえば、作業項目の アイテム ID、 Work Item Type、 Title、および State を返すには、クエリに次の句を追加します。この句は、名前付きフィールドに対応するプロパティを指定します。

Note

プロパティ名にはスペースが含まれません。スペースを追加すると、クエリは失敗します。 OData クエリでは、間隔と大文字と小文字の両方に注意が必要です。ユーザー設定フィールドのプロパティのラベル付け方法については、「Azure Boards のMetadata リファレンスカスタムプロパティを参照してください。

ここでは、上位 3 つの作業項目を返すように指定します。

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

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

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value	
   0	
      WorkItemId    462
      Title         "Test case"
      WorkItemType  "Test Case"
      State         "Design"
   1	
      WorkItemId	   491
      Title          "Change color settings"
      WorkItemType   "Shared Steps"
      State          "Active"
   2	
      WorkItemId	   461
      Title          "Test impediment"
      WorkItemType   "Impediment"
      State          "Open"

データのフィルター選択

選択項目を返すようにエンティティセットをフィルター処理するには、項目が満たす必要がある条件を指定する $filter 句を指定します。最後のクエリに基づいて、In Progress 状態にある作業項目の種類Featureのみを返すフィルター句を追加します。

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=State eq 'In Progress'

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

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

  
@odata.context	"https://analytics.dev.azure.com/kelliott/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,State)"
value	
  0	
      WorkItemId	380
      Title	"Refresh web look, feel, performance factors"
      State	"In Progress"
  1	
      WorkItemId	480
      Title	"Customer Phone - Phase 1"
      State	"In Progress"
  2	
      WorkItemId	493
      Title	"Change initial view"
      State	"In Progress"
  3	
      WorkItemId	479
      Title	"Customer Web - Phase 1"
      State	"In Progress"
  4	
      WorkItemId	551
      Title	"Mobile feedback"
      State	"In Progress"

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

ANDとORを使用して、複数のフィルター句を指定できます。

たとえば、次のクエリでは、New、Committed、または Active 状態にあるUser Story、Bug、Backlog Work (カスタム作業項目の種類) の作業項目を返すように指定します。かっこを使用して、必要に応じてフィルター句をグループ化します。

さらに、 contains、 startswith、 endswith など、さまざまな機能を適用できます。サポートされている OData の機能と句、サポートされている関数を参照してください。

[ID]、[エリアパス]、[反復パス] フィールドのデータを返します

選択プロパティはナビゲーションプロパティに関連付けられているので、 $select ステートメントを使用して直接アクセスすることはできません。目的のデータを返すには、 $expand ステートメントを使用する必要があります。これらのプロパティは、多くの場合、独自のいくつかのプロパティに関連付けられています。たとえば、[ID] フィールドを使用して、ユーザー名またはユーザーの電子メールを返すように指定できます。

次の表に、これらのプロパティのいくつかを展開する方法の例を示します。

型フィールド	Referenced プロパティ	含める句の例
DateTime	`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)`
Project	`ProjectSK`	`$expand=Project($select=ProjectName)`
Team	`TeamSK`	`$expand=Teams($select=TeamName)`

展開する必要がある複数のプロパティを指定するには、コンマ区切りリスト内の 1 つの展開句でプロパティを指定します。

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

フィルター条件の一部としてナビゲーションプロパティを指定する場合は、必要な形式で指定する必要があります。

たとえば、次の句は、プロジェクトに対して定義された Iteration 1 に基づいて作業項目をフィルター処理することを指定します。

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

この例では、 Iteration はナビゲーションプロパティ名であり、 IterationPath はイテレーションの完全なパスに対応します。別のエンティティをフィルターとして使用するには、ナビゲーションプロパティの後にスラッシュの後にフィルターを適用するフィールドの名前を付けます。

完全な OData クエリを次に示します。

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

Fabrikam Fiber\Service Delivery\Voice Area Path の上位 5 つの作業項目を要求する別の例を次に示します。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Area/AreaPath eq 'Fabrikam Fiber\Service Delivery\Voice'&$select=WorkItemId, WorkItemType, Title, State&$orderby=WorkItemId asc

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value	
  0	
     WorkItemId	361
     Title        "Hello World Web Site"
     WorkItemType	"Product Backlog Item"
     State        "Removed"
  1	
     WorkItemId	362
     Title        "Resume"
     WorkItemType	"Product Backlog Item"
     State        "New"
  2	
     WorkItemId	363
     Title        "Welcome back page"
     WorkItemType	"Product Backlog Item"
     State        "Done"
  3	
     WorkItemId	365
     Title        "Pause"
     WorkItemType	"Feature"
     State        "New"
  4	
     WorkItemId	374
     Title        "Fix performance issues"
     WorkItemType	"Task"
     State        "To Do"

ヒント

$select ステートメントでは、ナビゲーションプロパティを直接使用することはできません。代わりに、 $expandを使用する必要があります。

イテレーションパスの前のフィルター処理の例では、関連するエンティティに含まれているため、イテレーションパスは返されません。関連エンティティのデータを返すには、 $expand ステートメントを追加します。

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

作業項目 ID 480 に割り当てられた情報を返す例を次に示します。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&&$expand=Iteration
   
@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)"
value	
  0	
      WorkItemId           480
      Title                "Customer Phone - Phase 1"
      WorkItemType	       "Feature"
      State	               "In Progress"
      Iteration	
          ProjectSK	       "56af920d-393b-4236-9a07-24439ccaa85c"
          IterationSK	       "c7063041-ff3a-4d7f-bb46-c433c7030d59"
          IterationId	       "c7063041-ff3a-4d7f-bb46-c433c7030d59"
          IterationName	   "Sprint 1"
          Number	            55297
          IterationPath	    "Fabrikam Fiber\\Release 1\\Sprint 1"
          StartDate	        "2022-01-17T00:00:00-08:00"
          EndDate	            "2022-02-04T23:59:59.999-08:00"
          IterationLevel1	    "Fabrikam Fiber"
          IterationLevel2	    "Release 1"
          IterationLevel3	    "Sprint 1"
          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	        	true
      AnalyticsUpdatedDate	"2022-01-18T22:18:58.17Z"

ご覧のように、イテレーションパスは結果で展開され、すべてのイテレーションデータが返されます。おそらく、必要以上のデータです。

返されるデータを減らすには、イテレーションに対して $select ステートメントを追加します。

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

次に、次のデータを返します。

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration,Iteration(Name,IterationPath))",
  "value":[
    {
      "WorkItemId":10000,
      "WorkItemType":"Task",
      "Title":"Some title",
      "State":"Completed",
      "Iteration":{
        "Name":"Sprint 55",
        "IterationPath":"Fabrikam\\Sprints\\Sprint 55"
      }
    }
  ]
}

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

次の例では、 Changed Date が 2021 年 1 月 1 日より大きい作業項目を返します。

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-01-01Z

次の例では、2021 年 4 月 26 日から 4 月 30 日の週に 変更日 が発生した作業項目を返します。

https://analytics.dev.azure.com{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-04-26Z&ChangedDate le 2021-04-30Z

expand ステートメントを入れ子にする

OData では、 $expand ステートメントを入れ子にすることができます。たとえば、前のクエリステートメントを記述して、イテレーションの一部であるプロジェクトを表示できます。

/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($expand=Project)

次の JSON が返されます。

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
  "value":[
    {
      "WorkItemId":10000,
      "Revision":3,
      "Watermark":283397,
      "Title":"Production deployment and testing for Entitlement API v2 and Subscriber database",
      "WorkItemType":"Task",
      "ChangedDate":"2014-07-10T19:29:58.41Z",
      "CreatedDate":"2014-04-19T22:44:58.31Z",
      "State":"Completed",
      "Reason":"Completed",
      "Priority":2,
      "CompletedWork":10.0,
      "OriginalEstimate":20.0,
      "Count":1,
      "Iteration":{
        "IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46",
        "Name":"Sprint 55",
        "Number":13021,
        "IterationPath":"Fabrikam\\Sprints\\Sprint 55",
        "StartDate":"2013-09-23T00:00:00Z",
        "EndDate":"2013-10-11T00:00:00Z",
        "IterationLevel1":"Fabrikam",
        "IterationLevel2":" Sprints",
        "IterationLevel3":"Sprint 55",
        "Level":2,
        "IsDeleted":false,
        "Project":{
          "ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
          "ProjectName":"Fabrikam",
          "IsDeleted":false
        }
      }
    }
  ]
}

$expandステートメントと$select ステートメントを組み合わせることもできます。たとえば、前のクエリを変更して、イテレーション名とイテレーションパスのみを返すことができます。

/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($select=IterationId,IterationPath;$expand=Project)

次の JSON が返されます。

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(Iteration(IterationId,IterationPath,Project))",
  "value":[
    {
      "WorkItemId":10000,
      "Revision":3,
      "Watermark":283397,
      "Title":"Production deployment and testing for Entitlement API v2 and Subscriber database","WorkItemType":"Task",
      "ChangedDate":"2014-07-10T19:29:58.41Z",
      "CreatedDate":"2014-04-19T22:44:58.31Z",
      "State":"Completed",
      "Reason":"Completed",
      "Priority":2,
      "CompletedWork":10.0,
      "OriginalEstimate":20.0,
      "Count":1,
      "Iteration":{
        "IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46","IterationPath":"Fabrikam\\Sprints\\Sprint 55",
        "Project":{
          "ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
          "ProjectName":"Fabrikam",
          "IsDeleted":false
        }
      }
    }
  ]
}

ここでの結果には IterationId と IterationPath のみが表示され、Project は JSON 結果内の入れ子になったオブジェクトであることに注意してください。注意すべきもう 1 つの重要な項目は、URL 自体です。 $select ステートメントと$expand句を使用する場合は、$expandの前にセミコロン (;)を使用する必要があります。それ以外の場合はエラーになります。

結果の並べ替え、 `orderby` オプション

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

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

次のステップ

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

次の方法で共有

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

前提条件

項目の数を返します (他のデータは返しません)

プロジェクト数

作業項目数

面積の数

ユーザー数

アイテムとデータの数を返す

Areas プロパティまたは Iterations プロパティ

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

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

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

データのフィルター選択

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

[ID]、[エリアパス]、[反復パス] フィールドのデータを返します

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

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

expand ステートメントを入れ子にする

結果の並べ替え、 `orderby` オプション

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

前提条件

項目の数を返します (他のデータは返しません)

プロジェクト数

作業項目数

面積の数

ユーザー数

アイテムとデータの数を返す

Areas プロパティまたは Iterations プロパティ

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

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

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

データのフィルター選択

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

[ID]、[エリア パス]、[反復パス] フィールドのデータを返します

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

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

expand ステートメントを入れ子にする

結果の並べ替え、 orderby オプション

次のステップ

関連記事

フィードバック

その他のリソース

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

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

[ID]、[エリアパス]、[反復パス] フィールドのデータを返します

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

結果の並べ替え、 `orderby` オプション