Azure DevOps で Analytics の OData クエリを構築する

[アーティクル]
02/24/2025

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

Azure DevOps 用のレポートプラットフォームである Analytics は、プロジェクトの過去または現在の状態に関する定量的な質問に回答できます。 Analytics では、メタデータとエンティティセットデータに対する OData クエリがサポートされています。 Web ブラウザーから簡単なクエリを実行することで、データモデルとクエリプロセスに慣れることができます。

この記事では、以下のことについて説明します。

クラウドまたはオンプレミスの Analytics で OData クエリを構築する方法
メタデータに対して Analytics のクエリを実行する方法
エンティティセットに対して Analytics の OData クエリを実行する方法
サポートされているクエリオプションと推奨されるシーケンス
サーバー側のページングが適用される場合

Analytics クエリは、サポートされている任意の Web ブラウザーから実行できます。 Analytics のクエリに使用できるその他のツールについては、「分析クエリツール」をご覧ください。

Note

OData は、RESTful (REST= Representational State Transfer) インターフェイスを介してデータを操作するためのアプリケーションレベルのプロトコルであり、データモデルの記述と、それらのモデルに従ったデータの編集とクエリをサポートします。 Entity Data Model (EDM) またはメタデータは、Analytics から入手できる情報を記述するものです。これには、データに対してクエリを実行してレポートを作成するのに使用する、エンティティ、エンティティ型、プロパティ、リレーションシップ、リストが含まれます。 OData の概要については、OData の概要に関するページをご覧ください。

前提条件

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

メタデータに対してクエリを実行するための URL コンポーネント

Analytics では、サービスルート URL に $metadata を付加して作成されるメタデータ URL でエンティティモデルを公開します。 Analytics は、Azure DevOps 内のプロジェクトまたは組織全体のサービスルートを提供します。

メタデータに対してクエリを実行することで、次のいずれかのデータ要素を検索できます。

エンティティ型とエンティティセット
プロパティとナビゲーションプロパティ
代理キー
列挙リスト
EntitySet
Containers
フィルター関数 (Org.OData.Capabilities.V1.FilterFunctions)
サポートされている集計 (Org.OData.Aggregation.V1.ApplySupported)
バッチのサポート (Org.OData.Capabilities.V1.BatchSupportType)

使用する URL は、Azure DevOps Services (クラウド) またはオンプレミスの Azure DevOps Server のどちらのデータに対してクエリを実行するかによって異なります。

クラウド (Azure DevOps Services
オンプレミス (Azure DevOps Server

クラウドでホストされている組織またはプロジェクトのメタデータに対してクエリを実行するには、次に示す URL 構文を Web ブラウザーに入力します。 {OrganizationName} および {ProjectName} を、クエリを実行する組織名とプロジェクト名に置き換えます。組織のすべてのメタデータを返す場合は、プロジェクト名を指定しないでください。

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/version/$metadata 
\______________________________/\______________________________/\______________/\_________/
               |                                 |                       |           |
    Analytics service root URL         Organization/Project        OData version  return metadata

Note

Analytics OData の最新バージョンは v4.0-preview です。このバージョンは、ホストされるサービスに対するすべてのクエリで使用できます。 Analytics のバージョンと使用可能なデータの詳細については、「Analytics のデータモデル」をご覧ください。

Azure DevOps Services でホストされている組織、fabrikam の例を次に示します。

https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata

オンプレミスサーバーのメタデータに対してクエリを実行するには、次に示す URL 構文を Web ブラウザーに入力します。 {ServerName}、{CollectionName}、{ProjectName} を実際のオンプレミス名で置き換えます。コレクションのすべてのメタデータを返す場合は、プロジェクト名を指定しないでください。

https://{ServerName}/{CollectionName}/{ProjectName}/_odata/version/$metadata 
\_________________________________________________/\______________/\________/
                            |                              |            | 
     On-premises server, collection, project         OData version  return metadata

Note

以下に、Azure DevOps Server 2022 でホストされている、fabrikam-devops という名前のサーバーと DefaultCollection の例を示します。

https://fabrikam-devops/DefaultCollection/_odata/v4.0-preview/$metadata

メタデータ応答を解釈する

Analytics は、データモデルの XML ファイルを返します。ブラウザーの検索機能を使用して、目的のエンティティに固有の情報を検索します。

ヒント

お使いのブラウザーによって、このファイルが可読形式になっている場合とそうでない場合があります。可読形式でない場合は、Web ブラウザーで検索して無料のオンライン XML フォーマッタを見つけることができます。

Analytics のメタデータで定義されている 2 つの主要なスキーマは、エンティティ型および列挙型とそのメンバーを定義する Microsoft.VisualStudio.Services.Analytics.Modelと、エンティティコンテナーおよびエンティティセット、サポートされている OData フィルター、変換、カスタム集計関数を定義する Default スキーマです。詳細については、「Analytics の OData メタデータ」をご覧ください。

<?xml version="1.0" encoding="UTF-8"?>
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
    <edmx:DataServices>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Microsoft.VisualStudio.Services.Analytics.Model">
           <EntityType Name="Entity Name"/>
        </Schema>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Default">
           <EntityContainer Name="Container"/>
        </Schema>
    </edmx:DataServices>
</edmx:Edmx>

すべてのエンティティ型には、プロパティとナビゲーションプロパティが関連付けられています。エンティティセットのクエリは、両方の型のプロパティを使用してフィルター処理できます。これらは、EntityType の下のメタデータに Property または NavigationalProperty としてリストされます。関連するエンティティを使用して、イテレーションパス、エリアパス、チームなどの追加のフィルターを指定します。

次のコードスニペットでは、WorkItem エンティティのメタデータを部分的に表示しています。プロパティは、作業項目フィールドと、Analytics によってキャプチャされた特定のデータ (LeadTimeDays や CycleTimeDaysなど) に対応します。ナビゲーションプロパティは、他のエンティティセット、またはエンティティ型に応じてキャプチャされた特定の Analytics データ (Revisions、Links、Children、Parent など) に対応します。

<Key>
   <PropertyRef Name="WorkItemId"/>
</Key>
<Property Name="WorkItemId" Type="Edm.Int32" Nullable="false">
   <Annotation Term="Ref.ReferenceName" String="System.Id"/>
   <Annotation Term="Display.DisplayName" String="Work Item Id"/>
</Property>
<Property Name="InProgressDate" Type="Edm.DateTimeOffset">
   <Annotation Term="Display.DisplayName" String="InProgress Date"/>
   </Property>
<Property Name="CompletedDate" Type="Edm.DateTimeOffset">
   <Annotation Term="Display.DisplayName" String="Completed Date"/>
   </Property>
<Property Name="LeadTimeDays" Type="Edm.Double">
   <Annotation Term="Display.DisplayName" String="Lead Time Days"/>
</Property>
<Property Name="CycleTimeDays" Type="Edm.Double">
   <Annotation Term="Display.DisplayName" String="Cycle Time Days"/>
</Property>
<Property Name="InProgressDateSK" Type="Edm.Int32"/>
<Property Name="CompletedDateSK" Type="Edm.Int32"/>
<Property Name="AnalyticsUpdatedDate" Type="Edm.DateTimeOffset"/>
<Property Name="ProjectSK" Type="Edm.Guid" Nullable="false"/>
<Property Name="WorkItemRevisionSK" Type="Edm.Int32" Nullable="false"/>
...
<NavigationProperty Name="BoardLocations" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.BoardLocation)"/>
<NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>
<NavigationProperty Name="InProgressOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="InProgressDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="CompletedOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="CompletedDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="Revisions" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemRevision)"/>
<NavigationProperty Name="Links" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemLink)"/>
<NavigationProperty Name="Children" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Parent" Type="Microsoft.VisualStudio.Services.Analytics.Model.WorkItem">
<ReferentialConstraint Property="ParentWorkItemId" ReferencedProperty="WorkItemId"/>
</NavigationProperty>
<NavigationProperty Name="Processes" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Process)"/>
<NavigationProperty Name="Descendants" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project" Nullable="false">
<ReferentialConstraint Property="ProjectSK" ReferencedProperty="ProjectSK"/>
<Annotation Term="Display.DisplayName" String="Project"/>
...

エンティティに対してクエリを実行するための URL コンポーネント

Analytics データに対してクエリを実行し、レポートを作成するには、通常はエンティティセットに対してクエリを実行します。サポートされるエンティティの概要については、「Analytics の OData メタデータ」をご覧ください。

次の URL は、特定の EntitySet (WorkItems、WorkItemSnapshot、PipelineRuns など) に対してクエリを実行するのに使用されます。

クラウド (Azure DevOps Services
オンプレミス (Azure DevOps Server

https://analytics.dev.azure.com/OrganizationName/ProjectName/_odata/version/EntityType?{Query-options}
\______________________________/\__________________________/ \____________/\_________/\_____________/
               |                             |                    |               |          |
    Analytics service root URL     Organization/Project      OData version    Entity   Query parts

以下に、組織 fabrikam で、Fabrikam Fiber プロジェクトで定義された作業項目の数を返す例を示します。

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?%20$apply=aggregate($count%20as%20Count)

この例では、1399 個の作業項目が返されます。

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

以下に、fabrikam サーバー、DefaultCollection で、Fabrikam プロジェクトで定義された作業項目の数を返す例を示します。

https://fabrikam/DefaultCollection/Fabrikam/_odata/v4.0-preview/WorkItems?%20$apply=aggregate($count%20as%20Count)

この例では、1399 個の作業項目が返されます。

{
"@odata.context": "http://fabrikam/DefaultCollection/Fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)",
"value": [
   {
      "@odata.id": null,
      "Count": 44
   }
 ]
}

Note

$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 ステートメントを実行し、すべての列と行を返すのと同等の操作です。レコード数が多い場合は、数秒かかる場合があります。 10,000 個を超える作業項目がある場合は、サーバー側でのページングが適用されます。

使用制限に達しないようにするには、常に $select 句または $apply 句を含めます。

エンティティメタデータのプロパティとリレーションシップの情報については、以下の記事をご覧ください。

例: 特定のエンティティセットに対してクエリを実行する

特定のエンティティセット (WorkItems、Areas、 Projects など) に対してクエリを実行するには、エンティティセットの名前 (/WorkItems、/Areas、 /Projects) を追加します。エンティティセットの完全な一覧については、「Analytics のデータモデル」をご覧ください。

クラウド (Azure DevOps Services
オンプレミス (Azure DevOps Server

たとえば、/Projects に対してクエリを実行し、ProjectName プロパティを返すように選択することで、組織で定義されているプロジェクトの一覧を取得できます。組織 fabrikam の場合、URL は次のようになります。

  https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/Projects?$select=ProjectName

Analytics は、組織 fabrikam で定義されているプロジェクトのプロジェクト名を返します。

{
@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(ProjectName)",

"value": [
   {
      "ProjectName": "Basic Fabrikam"
   },
   {
      "ProjectName": "Fabrikam Fiber"
   },
   {
      "ProjectName": "MyFirstProject"
   },
   {
      "ProjectName": "Fabrikam Test"
   },
   {
      "ProjectName": "MyPublicProject"
   }
 ]
}

以下に、Projects エンティティセットに対してクエリを実行し、fabrikam サーバー上の DefaultCollection で定義されているすべてのプロジェクトの名前を返す例を示します。

https://fabrikam/DefaultCollection/_odata/v4.0-preview/Projects?$select=ProjectName

この例では、3 つのプロジェクト名が返されます。

{
"@odata.context": "http://fabrikam/DefaultCollection/_odata/v4.0-preview/$metadata#Projects(ProjectName)",
"value": [
   {
      "ProjectName": "Fabrikam Fiber"
   },
   {
      "ProjectName": "Fabrikam"
   },
   {
      "ProjectName": "Fabrikam Florida"
   }
 ]
}

クエリオプション

クエリオプションは、リソースに適用されるクエリ文字列パラメーターのセットであり、URL 内のリソースについて返されるデータの量を制御するのに役立ちます。

クエリオプションは、次の表に示す順序で指定する必要があります。

クエリオプション	メモ
`$apply`	クエリに適用できる一連の変換 (`filter`、`groupby`、`aggregate`、`compute`、`expand,concat` など) 例については、「 Analytics を使用して作業追跡データを集計する」をご覧ください。
`$compute`	`$select` 式、`$filter` 式、`$orderby` 式で使用可能な計算されたプロパティを定義するために使用できる、サポートされる OData 関数。
`$filter`	返されるリソースの一覧をフィルター処理するために使用します。 `$filter` を使用して指定される式は、コレクション内の各リソースに対して評価され、式が true と評価される項目のみが応答に含まれます。式が false または null に評価されるリソース、またはアクセス許可のために使用できない参照プロパティは、応答から省略されます。例については、「 Analytics を使用して作業追跡データのクエリを実行する」をご覧ください。
`$orderby`	レコードを返す順序を指定するために使用します。例については、「 Analytics を使用して作業追跡データのクエリを実行する」をご覧ください。
`$top`/`$skip`	返されるレコードの数を制限するために使用します。例については、「プロジェクトと組織をスコープとするクエリ」をご覧ください。
`$select`/`$expand`	`$select` は、レポートを作成するのに必要な列を指定するのに使用します。 `$expand` は、他のクエリオプションを入れ子にするのに使用します。各 `expandItem` は、展開されているナビゲーションプロパティまたはストリームプロパティを含むエンティティを基準に評価されます。ナビゲーションプロパティ名に対する、セミコロンで区切り、かっこで囲んだクエリオプションの一覧。使用できるシステムクエリオプションは、`$filter`、`$select`、`$orderby`、`$skip`、`$top`、`$count`、`$search`、`$expand` です。例については、「 Analytics を使用して作業追跡データのクエリを実行する」をご覧ください。
`$skiptoken`	指定した数のレコードをスキップするために使用します。
`$count` または `$count=true`	レコードの数のみを返すには、"`$count`" と入力します。レコード数と照会されたデータの両方を返すには、"`$count=true`" と入力します。例については、「 Analytics を使用して作業追跡データを集計する」をご覧ください。

ヒント

1 つのクエリに $apply 句と $filter 句を混在させないようにします。クエリをフィルター処理するには、2 つのオプションがあります。(1) $filter 句を使用するか、(2) $apply=filter() の組み合わせの句を使用します。これらのオプションはそれぞれ単独ではうまく機能しますが、同時に使用すると予期しない結果が生じる可能性があります。

サーバー側のページングを適用する

クエリの結果が 1,0000 レコードを超えると、Analytics によって強制的にページングが適用されます。その場合は、データの最初のページと、次のページを取得するためのリンクが返されます。リンク (@odata.nextLink) は、JSON 出力の最後にあります。このため、元のクエリの後に $skip または $skiptoken が続いているように見えます。例えば次が挙げられます。

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
  "value":[
   // 10000 values here
  ],
  "@odata.nextLink":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$skiptoken=10000"
}

Note

Power BI Desktop や Excel などのクライアントツールにデータをプルすると、ツールは自動的に次のリンクに従い、必要なすべてのレコードを読み込みます。

次のステップ

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

次の方法で共有

Azure DevOps で Analytics の OData クエリを構築する

前提条件

メタデータに対してクエリを実行するための URL コンポーネント

メタデータ応答を解釈する

エンティティに対してクエリを実行するための URL コンポーネント

例: 特定のエンティティセットに対してクエリを実行する

クエリオプション

サーバー側のページングを適用する

次のステップ

フィードバック

その他のリソース

次の方法で共有

Azure DevOps で Analytics の OData クエリを構築する

前提条件

メタデータに対してクエリを実行するための URL コンポーネント

メタデータ応答を解釈する

関連するエンティティとナビゲーション プロパティ

エンティティに対してクエリを実行するための URL コンポーネント

例: 特定のエンティティ セットに対してクエリを実行する

クエリ オプション

サーバー側のページングを適用する

次のステップ

関連記事

フィードバック

その他のリソース

関連するエンティティとナビゲーションプロパティ

例: 特定のエンティティセットに対してクエリを実行する

クエリオプション