Metadatos de OData de Analytics

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

Comprender los metadatos asociados al modelo de entidades para Analytics es un requisito previo para consultar mediante programación el modelo de datos para Analytics. Los metadatos de OData son una descripción legible de la máquina del modelo de entidad diseñado para permitir el consumo de cliente.

Nota

"Open Data Protocol (OData) es un protocolo de acceso a datos basado en protocolos principales como HTTP y metodologías comúnmente aceptadas como REST para la web. Hay varios tipos de bibliotecas y herramientas que se pueden usar para consumir servicios de OData". - Tutorial básico de la organización de OData.

En este artículo, aprenderá a:

  • Consulta de los metadatos en un proyecto específico
  • Consulta de los metadatos de una organización
  • Identificar las claves, las propiedades y las propiedades de navegación asociadas a una entidad
  • Identificación de las funcionalidades del punto de conexión de OData de Analytics

Para obtener descripciones detalladas de todos los elementos de OData, consulte Modelo de OData. Para obtener información sobre cómo consultar los metadatos, consulte Construcción de consultas de OData para Analytics.

Nota

El servicio Analytics se habilita automáticamente para todas las Azure DevOps Services. Se admite para su uso en producción. La integración de Power BI y el acceso a la fuente OData del servicio Analytics están disponibles con carácter general. Le recomendamos que lo use y nos proporcione sus comentarios. >
Los datos disponibles dependen de la versión. La versión compatible más reciente es v2.0y la versión preliminar más reciente es v4.0-preview. Para más información, consulte Control de versiones de la API de OData.

Nota

El servicio Analytics se instala automáticamente en todas las colecciones de proyectos nuevas para Azure DevOps Server 2020 y versiones posteriores. Se admite para su uso en producción. La integración de Power BI y el acceso a la fuente OData del servicio Analytics están disponibles con carácter general. Le recomendamos que lo use y nos proporcione sus comentarios. Si ha actualizado desde Azure DevOps Server 2019, se le proporciona la opción de instalar el servicio Analytics durante la actualización.

Los datos disponibles dependen de la versión. La versión compatible más reciente es v2.0y la versión preliminar más reciente es v4.0-preview. Para más información, consulte Control de versiones de la API de OData.

Nota

El servicio Analytics está en versión preliminar para Azure DevOps Server 2019. Para acceder a Analytics, habilite o instale para una colección de proyectos. La integración de Power BI y el acceso a la fuente OData del servicio Analytics se encuentran en versión preliminar. Le recomendamos que lo use y nos proporcione sus comentarios.

Los datos disponibles dependen de la versión. La versión compatible más reciente es v2.0y la versión preliminar más reciente es v4.0-preview. Para más información, consulte Control de versiones de la API de OData.

Conjuntos de entidades y tipos de entidad

Las entidades son los tipos de identidad principales de un modelo de datos. Los conjuntos de entidades se denominan colecciones de entidades. Por ejemplo, Projects es un conjunto de entidades que contiene Project entidades. Una entidad puede ser miembro de, como máximo, un conjunto de entidades.

EntitySets y EntityTypes definen cada una de las entidades del modelo de Analytics, incluidas las propiedades y las relaciones. Los tipos de entidad definen las propiedades y relaciones con nombre de una entidad. Los tipos de entidad pueden derivarse por herencia única de otros tipos de entidad. La clave de un tipo de entidad se forma a partir de un subconjunto de sus propiedades primitivas.

En el ejemplo siguiente se muestran los metadatos asociados al tipo de Project entidad.

<EntityType Name="Project">
  <Key>
    <PropertyRef Name="ProjectSK"/>
  </Key>
  <Property Name="ProjectSK" Type="Edm.Guid" Nullable="false"/>
  <Property Name="ProjectId" Type="Edm.Guid" Nullable="false">
    <Annotation Term="Display.DisplayName" String="Project Id"/>
  </Property>
  <Property Name="ProjectName" Type="Edm.String" Nullable="false">
    <Annotation Term="Display.DisplayName" String="Project Name"/>
  </Property>
  <Property Name="AnalyticsUpdatedDate" Type="Edm.DateTimeOffset"/>
  <Property Name="ProjectVisibility" Type="Microsoft.VisualStudio.Services.Analytics.Model.ProjectVisibility">
    <Annotation Term="Display.DisplayName" String="Project Visibility"/>
  </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>

Teclas

Keys defina las propiedades de entidad disponibles para su uso como propiedad de navegación.

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

Propiedades

Conjunto de "Propiedades de entidad disponibles para la consulta. Las anotaciones representan otros detalles sobre una propiedad determinada.

Cualquier propiedad de Analytics que debe ser visible para los usuarios finales se anota con .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 es otra anotación común que se usa para definir el identificador del sistema para una propiedad específica.

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

Consultar una entidad individual es útil. Finalmente, probablemente querrá filtrar o expandir los detalles de otra entidad. Para ello, debe comprender cómo usar las propiedades de navegación del modelo de entidad.

Un NavigationaProperty objeto con un tipo de colección representa una relación de varios a varios en el modelo.

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

ReferentialConstraints vincula las propiedades de navegación a una clave específica de una entidad, que representa una relación de varios a uno en el modelo.

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

Contenedores (funcionalidades de OData)

EntitySets

Las entidades son los tipos de identidad principales de un modelo de datos. Los conjuntos de entidades se denominan colecciones de entidades. Por ejemplo, WorkItems y WorkItemRevisions están EntitySets dentro del EntityContainer objeto denominado Container. Una entidad puede ser miembro de, como máximo, un conjunto de entidades. Los conjuntos de entidades proporcionan los puntos de entrada principales en el modelo de datos y representan una colección de entidades y enlaces y anotaciones de propiedades de navegación asociadas.

La sintaxis siguiente indica el modelo de datos del Projects conjunto de entidades. Para obtener una descripción de cada conjunto de entidades, consulte Modelo de datos para Analytics.

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

Funcionalidades

Las funcionalidades definen el conjunto de funciones que entiende el punto de conexión de OData de Analytics.

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

Agregaciones

Las anotaciones de agregación definen el conjunto de transformaciones que entiende el punto de conexión de OData de Analytics.

<Annotation Term="Org.OData.Aggregation.V1.ApplySupported">
   <Record>
      <PropertyValue Property="Transformations">
         <Collection>
            <String>aggregate</String>
            <String>filter</String>
            <String>groupby</String>
            <String>compute</String>
            <String>expand</String>
         </Collection>
      </PropertyValue>
      <PropertyValue Property="CustomAggregationMethods ">
         <Collection>
           <String>ax.ApproxCountDistinct</String>
           <String>ax.StandardDeviation</String>
           <String>ax.StandardDeviationP</String>
           <String>ax.Variance</String>
           <String>ax.VarianceP</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>

Pasos siguientes