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

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

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

Note

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

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

Analytics OData クエリを作成します。
クエリ分析メタデータ。
エンティティセットに対して OData を用いたクエリ解析。
推奨される順序でクエリオプションを使用します。
サーバー側ページングを理解する。

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

前提条件

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

メタデータのクエリを実行する

Analytics は、サービスルート URL にを追加して形成されたメタデータ URL で $metadataを公開します。 Analytics は、Azure DevOps プロジェクトまたは組織全体およびコレクションにサービスルートを提供します。

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

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

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

https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/version/$metadata

次の例では、 fabrikam 組織のメタデータを照会します。

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

クエリ文字列では、 analytics.dev.azure.com は Analytics サービスのルート URL で、その後に組織名、プロジェクト名、OData バージョン、および $metadata 指定が続きます。

サーバーのメタデータを照会するには、Web ブラウザーで次の URL 構文を入力します。 <ServerName>、<CollectionName>、および<ProjectName>を、クエリを実行するサーバー、コレクション、およびプロジェクトの名前に置き換えます。コレクションのすべてのメタデータを返すには、プロジェクト名を指定しないでください。

https://<ServerName>/<CollectionName>/<ProjectName>/_odata/version/$metadata

次の例では、 fabrikam-devops とその DefaultCollectionという名前のサーバーのメタデータを照会します。

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

Note

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

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

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

ヒント

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

分析メタデータは、次の主要なスキーマを定義します。

Microsoft.VisualStudio.Services.Analytics.Model は、エンティティ型と列挙型とそのメンバーを定義します。
Default スキーマでは、エンティティコンテナーとエンティティセット、およびサポートされている 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>

詳細については、「Analytics の OData メタデータ」をご覧ください。

すべてのエンティティ型には、クエリのフィルター処理に使用できるプロパティとナビゲーションプロパティがあります。これらのプロパティは、各PropertyのNavigationPropertyまたはEntityTypeとしてメタデータに一覧表示されます。関連エンティティを使用して、イテレーションパス、エリアパス、チームなど、さらに多くのフィルターを指定できます。

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

<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"/>
...

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

クエリエンティティセット

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

EntitySet、WorkItems、WorkItemSnapshotなど、特定のPipelineRunsに対してクエリを実行するには、次の URL 構文を使用します。 <EntitySet>を検索するエンティティに置き換え、「クエリオプションを使用する」の説明に従って、<QueryOptions>をクエリオプションに置き換えます。

https://analytics.dev.azure.com/<OrganizationName>/<ProjectName>/_odata/version/<EntitySet>?<QueryOptions>

次の例では、Fabrikam Fiber組織のfabrikam プロジェクト内の作業項目の数を照会します。

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
   }
 ]
}

https://<ServerName>/<CollectionName>/<ProjectName>/_odata/version/<EntitySet>?<QueryOptions>

次の例では、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 句をクエリに含めます。 $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 句を省略することは、すべての列とすべての行を返すエンティティセットに対してselect ステートメントを実行することと同じです。レコードの数が多い場合、クエリには数秒かかることがあります。項目数が 10,000 を超える場合は、サーバー側のページングが適用されます。

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

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

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

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

分析は 、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 に対してクエリを実行し、 ProjectName プロパティを返すように選択することで、サーバーとコレクションに定義されているプロジェクトの一覧を取得できます。次の例は、DefaultCollection サーバー上のfabrikamのクエリ URL を示しています。

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

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

[!div class="tabbedCodeSnippets"]

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

クエリオプションを使用する

クエリオプションは、リソースに対して返されるデータの量を制御するのに役立つクエリ文字列パラメーターです。次の表に示す順序でクエリオプションを指定します。

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

ヒント

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

サーバーサイドページングの理解

クエリ結果が 10,000 レコードを超えると、Analytics によって強制的にページングされます。その場合は、データの最初のページと、次のページを取得するためのリンクを取得します。 Power BI Desktop や Excel などのクライアントツールは自動的に @odata.nextLink に従い、データをプルするときに必要なすべてのレコードを読み込みます。

JSON 出力の最後に @odata.nextLink リンクがあります。リンクは、元のクエリの後に $skip または $skiptokenのように見えます。例えば次が挙げられます。

{
  "@odata.context":"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#WorkItems",
  "value":[
   // 10000 values here
  ],
  "@odata.nextLink":"https://https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/WorkItems?$skiptoken=10000"
}

次のステップ

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

フィードバック

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

Last updated on 2025-11-07

次の方法で共有

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

前提条件

メタデータのクエリを実行する

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

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

クエリ エンティティ セット

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

クエリ オプションを使用する

サーバーサイドページングの理解

次のステップ

関連コンテンツ

フィードバック

その他のリソース

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

クエリエンティティセット

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

クエリオプションを使用する