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

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

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

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

この記事では、次の内容について説明します。

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

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

Note

OData は、RESTful (REST= Representational State Transfer) インターフェイスを介してデータを操作するためのアプリケーションレベルのプロトコルであり、データモデルの説明と、それらのモデルに従ったデータの編集とクエリをサポートします。エンティティデータモデル (EDM) またはメタデータは、データのクエリを実行してレポートを作成するために使用するエンティティ、エンティティ型、プロパティ、リレーションシップ、列挙型など、Analytics から入手できる情報を記述します。 OData の概要については、「 Welcome to OData」を参照してください。

前提条件

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

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

分析では、メタデータ URL で存在モデルサービスルート URL に $metadata を追加して形成されたモデルが公開されます。 Analytics は、Azure DevOps のプロジェクトまたは組織全体のサービスルートを提供します。

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

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

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

Cloud (Azure DevOps Services
オンプレミス (Azure DevOps Server

クラウドでホストされている組織またはプロジェクトのメタデータを照会するには、Web ブラウザーで次に示すように URL 構文を入力します。 {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 のバージョンと使用可能なデータの詳細については、「 Data model for Analytics」を参照してください。

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

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

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

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

Note

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

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

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

分析は、データモデルの 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>

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

次のコードスニペットは、 WorkItem エンティティのメタデータの部分的なビューを提供します。プロパティは、作業項目フィールドと、 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 は、WorkItems、WorkItemSnapshot、PipelineRunsなど、特定のEntitySetに対してクエリを実行するために使用されます。

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

Fabrikam プロジェクトに対して定義された作業項目の数を返す fabrikam server DefaultCollection の例を次に示します。

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 ステートメントを実行し、すべてを返すのと同じ"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."、すべての列とすべての行を返すなどの警告が表示されます。レコードの数が多い場合は、数秒かかる場合があります。 10,000 個を超える作業項目がある場合は、サーバー駆動ページングが適用されます。

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

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

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

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

Cloud (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"
   }
 ]
}

fabrikam サーバーの DefaultCollection で定義されているすべてのプロジェクトの名前を返すために、Projects エンティティセットを照会する例を次に示します。

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 を使用した Query の作業追跡データを参照してください。
`$top`/`$skip`	返されるレコードの数を制限するために使用します。例については、「 Project と組織スコープのクエリを参照してください。
`$select`/`$expand`	`$select`を使用して、レポートを作成するために必要な列を指定します。 `$expand`を使用して、他のクエリオプションを入れ子にします。各 `expandItem` は、展開されるナビゲーションプロパティまたはストリームプロパティを含むエンティティを基準に評価されます。ナビゲーションプロパティ名をかっこで囲んだ、セミコロンで区切られたクエリオプションの一覧。使用できるシステムクエリオプションは、 `$filter`、 `$select`、 `$orderby`、 `$skip`、 `$top`、 `$count`、 `$search`、および `$expand`です。例については、Analytics を使用した Query の作業追跡データを参照してください。
`$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 コンポーネント

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

クエリ オプション

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

次のステップ

関連記事

フィードバック

その他のリソース

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

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

クエリオプション