Explore the Analytics OData metadata

Azure DevOps Services | Azure DevOps Server 2019

Understanding the metadata associated with the entity model for the Analytics service is a pre-requisite for programmatically querying the Data model for the Analytics Service. OData metadata is a machine readable description of the entity model designed to enable client consumption.

Note

The Analytics Service is generally available for all organizations using Azure DevOps Services. It provides several advanced widgets. Power BI integration and access to the OData feed of the Analytics Service is in Preview. We encourage you to use it and provide us feedback. As we add features, we will post them on the Microsoft DevOps Blog.

If you are looking for information about Azure Analysis Services, see Azure Analysis Services.

Note

The Analytics Service is in preview for Azure DevOps Server 2019. While in preview, it is available to everyone free of charge. We encourage you to use it and provide us feedback. As we add features, we will post them on the Microsoft DevOps Blog.

You access the Analytics Service by installing the Analytics Marketplace extension. Installing it provides several advanced widgets, Power BI integration, and access to the OData feed.

If you are looking for information about Azure Analysis Services, see Azure Analysis Services.

In this article you'll learn how to:

  • Query the metadata on a specific project
  • Query the metadata on an organization
  • Identify the keys, properties, and navigational properties associated with an Entity
  • Identify the capabilities of the Analytics OData endpoint

How to query the service for metadata

Analytics exposes the entity model at the metadata URL, formed by appending $metadata to the service root URL. Analytics provides service roots for a project or an entire organization in Azure DevOps.

Query for metadata on a specific project

You construct the service root URL for a project as shown:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata

Note

The {version} value is formatted as v1.0. The latest supported version is v2.0, and the latest preview version is v3.0-preview. For more information, see OData API versioning.

https://{servername}:{port}/tfs/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata

Note

The examples shown in this document are based on a Azure DevOps Services URL, you will need to substitute in your Azure DevOps Server URL

Interpret the metadata response

The core components of the metadata response are EntityType and EntityContainer.

<?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>

EntityTypes

EntityTypes define each of the Entities in the model including properties and relationships.

<EntityType Name="Project">
   <Key>
      <PropertyRef Name="ProjectSK"/>
   </Key>
   <Property Name="ProjectSK" Nullable="false" Type="Edm.Guid"/>
   <Property Name="ProjectId" Nullable="false" Type="Edm.Guid">
      <Annotation String="Project Id" Term="Display.DisplayName"/>
   </Property>
   <Property Name="ProjectName" Nullable="false" Type="Edm.String">
      <Annotation String="Project Name" Term="Display.DisplayName"/>
   </Property>
   <NavigationProperty Name="Areas" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Area)"/>
   <NavigationProperty Name="Iterations" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Iteration)"/>
   <NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>
</EntityType>

Keys

Keys define the Entity properties available for use as a Navigational Property.

<Key>
   <PropertyRef Name="ProjectSK"/>
</Key>

Properties

The set of Entity properties available for query. Annotations represent additional details about a given property.

Any property of Analytics that should be visible to end users is annotated with a DisplayName.

<Property Name="ProjectSK" Nullable="false" Type="Edm.Guid"/>
<Property Name="ProjectId" Nullable="false" Type="Edm.Guid">
   <Annotation String="Project Id" Term="Display.DisplayName"/>
</Property>
<Property Name="ProjectName" Nullable="false" Type="Edm.String">
   <Annotation String="Project Name" Term="Display.DisplayName"/>
</Property>

ReferenceName is another common annotation used to define the system identifier for a specific property.

<Property Name="State" Type="Edm.String">
   <Annotation String="State" Term="Display.DisplayName"/>
   <Annotation String="System.State" Term="Ref.ReferenceName"/>
</Property>

Querying an individual Entity is useful, but eventually you will want to be able to filter or expand details of another Entity. To do this, you need to understand how to use the Navigational Properties of the Entity model.

A Navigational Property with a Collection type represents a many to many relationship in the model.

<NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>

ReferentialConstraints tie Navigational Properties to a specific key of an Entity, representing a many to one relationship in the model.

<NavigationProperty Name="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project">
   <ReferentialConstraint ReferencedProperty="ProjectSK" Property="ProjectSK"/>
</NavigationProperty>

Containers (OData capabilities)

EntitySets

EntitySets represents a collection of entities and associated Navigational Property Bindings and Annotations.

<EntitySet Name="Projects" EntityType="Microsoft.VisualStudio.Services.Analytics.Model.Project">
   <NavigationPropertyBinding Target="Teams" Path="Teams"/>
   <Annotation String="Projects" Term="Org.OData.Display.V1.DisplayName"/>
</EntitySet>

Capabilities

Capabilities and Aggregation annotations define the set of functions understood by the Analytics OData endpoint.

<Annotation Term="Org.OData.Capabilities.V1.FilterFunctions">
   <Collection>
      <String>contains</String>
      <String>endswith</String>
      <String>startswith</String>
      <String>length</String>
      <String>indexof</String>
      <String>substring</String>
      <String>tolower</String>
      <String>toupper</String>
      <String>trim</String>
      <String>concat</String>
      <String>year</String>
      <String>month</String>
      <String>day</String>
      <String>hour</String>
      <String>minute</String>
      <String>second</String>
      <String>fractionalseconds</String>
      <String>round</String>
      <String>floor</String>
      <String>ceiling</String>
      <String>date</String>
      <String>time</String>
      <String>isof</String>
      <String>cast</String>
   </Collection>
</Annotation>
<Annotation Term="Org.OData.Aggregation.V1.ApplySupported">
   <Record>
      <PropertyValue Property="Transformations">
         <Collection>
            <String>aggregate</String>
            <String>filter</String>
            <String>groupby</String>
         </Collection>
      </PropertyValue>
   </Record>
</Annotation>
<Annotation Term="Org.OData.Capabilities.V1.BatchSupportType" Bool="true"/>
<Annotation Term="Org.OData.Capabilities.V1.BatchSupportType">
   <Record>
      <PropertyValue Property="Supported" Bool="true"/>
      <PropertyValue Property="ContinueOnErrorSupported" Bool="false"/>
      <PropertyValue Property="ReferencesInRequestBodiesSupported" Bool="false"/>
      <PropertyValue Property="ReferencesAcrossChangeSetsSupported" Bool="false"/>
      <PropertyValue Property="EtagReferencesSupported" Bool="false"/>
   </Record>
</Annotation>

Try this next