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

[アーティクル]
03/20/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 の概要については、「OData へようこそ」を参照してください。

前提条件

分析データを表示してサービスにクエリを実行するには、 Basic アクセス以上のプロジェクトのメンバーである必要があります。既定では、すべてのプロジェクトメンバーには、Analytics のクエリと分析ビューの定義に対するアクセス許可が付与されます。
サービスと機能の有効化と一般的なデータ追跡アクティビティに関するその他の前提条件については、「 Analytics にアクセスするためのアクセス許可と前提条件」を参照してください。

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

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

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

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

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

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

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

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

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

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

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

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

ヒント

使用しているブラウザーによっては、このファイルが読み取り可能な方法で書式設定される場合とできない場合があります。書式設定されていない場合は、Web ブラウザー検索で無料のオンライン XML フォーマッタを見つけることができます。

Analytics メタデータで定義されている 2 つのメインスキーマはMicrosoft.VisualStudio.Services.Analytics.Model、エンティティ型と列挙型とそのメンバーを定義するスキーマとDefault、エンティティコンテナーとエンティティセット、およびサポートされている OData フィルター、変換、およびカスタム集計関数を定義するスキーマです。詳細については、「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>

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

次のコードスニペットは、エンティティのメタデータの部分的なビューを WorkItem 提供します。プロパティは、作業項目フィールドと、分析によってキャプチャされた特定のデータに対応します。たとえばLeadTimeDaysCycleTimeDays、ナビゲーションプロパティは、他のエンティティセット、またはエンティティ型に対してキャプチャされた特定の Analytics データ (例: Revisions、、Links、ChildrenParent) に対応します。

<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 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 サーバー 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

or $apply 句を$select含めない場合は、エンティティセットに対して 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 を超える作業項目がある場合は、サーバー駆動型ページングが適用されます。

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

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

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

などの特定のエンティティセットに対してクエリを実行するには、WorkItemsAreasProjectsエンティティセットの名前を追加します。 /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

分析は、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`, `computeexpand,concat` 例については、「Analytics を使用して作業追跡データを集計する」を参照してください。
`$compute`	、`$filter`または`$orderby`式で`$select`使用できる計算プロパティを定義するために指定できる、サポートされている 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` します。レコードのカウントとクエリされたデータの両方を返すには、Enter キーを押 `$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 コンポーネント

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

クエリ オプション

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

次のステップ

関連記事

フィードバック

フィードバック

その他のリソース

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

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

クエリオプション