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

[アーティクル]
01/10/2024

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

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

この記事では、「Azure Boards Analytics の分析とメタデータに関する OData クエリの構築」で提供される情報を基にしています。また、この記事のクエリは作業追跡エンティティセットの取得に重点を置いていますが、原則は他のエンティティセットのクエリに適用されます。

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

項目の数 (他のデータなし)
アイテムとデータの数
[領域] または [反復パス] に定義されているプロパティ
選択した列またはフィールド
フィルター処理されたデータ
[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 サービスの OData フィードへのアクセスはプレビュー段階です。お使いいただき、フィードバックをお寄せください。

前提条件

分析データを表示してサービスにクエリを実行するには、 Basic アクセス以上のプロジェクトのメンバーである必要があります。既定では、すべてのプロジェクトメンバーには、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 のメタデータリファレンスと、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 プロパティ

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

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

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

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反復パスに定義されているプロパティを返すようにIterationSK指定します。エンティティセットに対して定義されている他のプロパティをIterations指定するには、「Azure Boards Analytics のメタデータリファレンス」の「イテレーション」を参照してください。

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、作業項目の種類、タイトル、および作業項目の状態を返すには、次の句をクエリに追加します。 この句は、名前付きフィールドに対応するプロパティを指定します。

Note

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

ここでは、上位 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 します。最後のクエリに基づいて、ここでフィルター句を追加して、処理中の状態にある機能作業項目の種類のみを返します。

/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 指定できます。

たとえば、次のクエリでは、"新規"、"コミット済み"、または "アクティブ" 状態のユーザーストーリー、バグ、およびバックログ作業 (カスタム作業項目の種類) の作業項目を返すように指定します。かっこを使用して、必要に応じてフィルター句をグループ化します。

さらに、、などcontainsstartswithendswith、さまざまな関数を適用できます。サポートされている 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)`
プロジェクト	`ProjectSK`	`$expand=Project($select=ProjectName)`
Team	`TeamSK`	`$expand=Teams($select=TeamName)`

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

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

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

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

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

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

完全な 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"
      }
    }
  ]
}

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

次の使用例は、変更日が 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
        }
      }
    }
  ]
}

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

/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 並べ替えるオプションを指定するか、結果が返される順序を指定します。キーワード (keyword)ascを使用して、昇順またはdesc降順で並べ替えることができます。例をいくつか示します

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

次のステップ

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

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

前提条件

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

プロジェクト数

作業項目数

面積の数

ユーザー数

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

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

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

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

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

データのフィルター選択

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

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

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

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

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

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

次のステップ

関連記事

フィードバック

フィードバック

その他のリソース

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

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

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

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

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