Metadatos de OData de Analytics

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

Comprender los metadatos asociados al modelo de entidad 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 habilitar el consumo de cliente.

Nota:

"Open Data Protocol (OData) es un protocolo de acceso a datos basado en protocolos básicos 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 en 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 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 y se admite en producción para todos los servicios de Azure DevOps. 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 envíe sus comentarios. Los datos disponibles dependen de la versión. La versión más reciente admitida es v2.0y la versión preliminar más reciente es v4.0-preview. Para obtener 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>

Claves

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

Propiedades de navegación

Consultar una entidad individual es útil. Finalmente, probablemente quiera 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 NavigationProperty 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 de propiedades de navegación asociados y anotaciones.

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

Modelo de datos para Analytics

Artículos relacionados

• Modelo de datos para Analytics
• Consultas de ámbito de proyecto y organización.
• Datos disponibles de análisis
• Consulta de datos de seguimiento del trabajo mediante Analytics
• Referencia de entidades y propiedades para Azure Boards

Recursos relacionados

• Extensión wiql to OData Marketplace
• Tutorial básico de la organización de OData
• OData versión 4.0. Parte 3: Common Schema Definition Language (CSDL) Plus Errata 03, Entity Model Wrapper