Exploración de los metadatos de OData para Analytics

Azure DevOps Services | Azure DevOps Server 2020 | 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 por máquina del modelo de entidad diseñado para habilitar el consumo de cliente.

Nota

El servicio Analytics se habilita automáticamente para todos los Azure DevOps Services. Se admite para su uso en producción. Power BI integración 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. .

Nota

El servicio Analytics se instala automáticamente en todas las nuevas colecciones de proyectos para Azure DevOps Server 2020. Se admite para su uso en producción. Power BI integración 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. Si actualizó desde Azure DevOps Server 2019, se le proporciona la opción de instalar el servicio Analytics durante la actualización.

Nota

El servicio Analytics está en versión preliminar para Azure DevOps Server 2019. Puede acceder a Analytics habilitando o instalando para una colección de proyectos. Power BI integración 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.

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, propiedades y propiedades de navegación asociadas a una entidad
  • Identificación de las funcionalidades del punto de conexión de OData de Analytics

Consulta de metadatos en el servicio

Analytics expone el modelo de entidad en la dirección URL de metadatos, formada por $metadata a la dirección URL raíz del servicio. Analytics proporciona raíces de servicio para un proyecto o una organización completa en Azure DevOps.

Consulta de metadatos en un proyecto específico

Cree la dirección URL raíz del servicio para un proyecto como se muestra a continuación:

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

Nota

El {version} valor tiene el formato v1.0 . La versión compatible más reciente es v2.0 y 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.

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

Nota

Los ejemplos que se muestran en este documento se basan en una Azure DevOps Services url, tendrá que sustituirla en la dirección URL Azure DevOps Server url.

Interpretación de la respuesta de metadatos

Los componentes principales de la respuesta de metadatos son EntityType y 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 definen cada una de las entidades del modelo, incluidas las propiedades y las relaciones.

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

Teclas

Las claves definen 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>

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.

Una propiedad navigational con un tipo Collection representa una relación de varios a varios en el modelo.

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

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

EntitySets representa una colección de entidades y enlaces de propiedades de navegación y anotaciones asociados.

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

Funcionalidades

Las funcionalidades y las anotaciones de agregación 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>
<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>

Pasos siguientes