Control de versiones de la API de OData

  • Artículo

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

Analytics para Azure DevOps ofrece una API de OData con versiones compatible con clientes diseñados para versiones específicas. Cada versión puede incluir mejoras y cambios de no interrupción, mientras que los cambios importantes se introducen en versiones futuras.

La versión de la API sigue el _odata elemento de la ruta de acceso de solicitud y puede ser una de las versiones admitidas: v1.0, v2.0, v3.0-preview o v4.0-preview.

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

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

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.

Nota:

El servicio Analytics se instala y admite automáticamente en producción para todas las colecciones de proyectos nuevas para Azure DevOps Server 2020 y versiones posteriores. 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. Si ha actualizado desde Azure DevOps Server 2019, puede instalar el servicio Analytics durante la actualización.

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.

Nota:

El servicio Analytics está en versión preliminar para Azure DevOps Server 2019. Puede habilitarlo o instalarlo para una colección de proyectos. La integración y el acceso de Power BI a la fuente OData del servicio Analytics se encuentran en versión preliminar. 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.

Diferencias entre versiones

v1.0 y v2.0: las versiones publicadas de la API de OData son estables y no incluyen cambios importantes. v2.0 incluye mejoras y más funcionalidad en comparación con v1.0.

v3.0-preview y v4.0-preview: las versiones preliminares pueden incluir cambios importantes y no se garantiza que tengan las mismas características en la versión final. Ofrecen acceso anticipado a nuevas características y mejoras que aún no están disponibles en las versiones publicadas.

¿Por qué elegir una versión específica?

  • Estabilidad: si necesita una API estable y confiable sin cambios importantes, debe elegir una de las versiones publicadas (v1.0 o v2.0).
  • Nuevas características: si desea aprovechar las últimas características y mejoras, puede optar por una de las versiones preliminares (v3.0-preview o v4.0-preview). Sin embargo, estas versiones pueden incluir cambios importantes y están sujetos a cambios.
  • Compatibilidad: asegúrese de que la versión que elija sea compatible con los clientes y sistemas existentes. La versión de la API sigue el _odata elemento de la ruta de acceso de solicitud y puede ser una de las versiones admitidas: v1.0, v2.0, v3.0-preview o v4.0-preview.

Conjuntos de entidades admitidos en cada versión

Para obtener información sobre qué EntitySets se admite con cada versión de API, consulte Modelo de datos para Análisis, Entidades.

Ciclo de vida de una versión

Cada versión de la API de OData pasa por las tres fases siguientes durante su ciclo de vida.

1. Fase de vista previa

Combinamos y liberamos todos los cambios importantes juntos en versiones futuras de la API. Para que esta funcionalidad esté disponible lo antes posible, publicamos nuevas versiones en modo de versión preliminar . Los cambios importantes siguen siendo posibles mientras una versión está en modo de versión preliminar y no hay ninguna garantía de que lo que se incluye en una versión preliminar se incluya en la versión publicada. La versión preliminar de una versión permanece disponible durante un mínimo de seis semanas después de su lanzamiento.

2. Publicado

Una vez que una versión preliminar madura y está lista para su lanzamiento, estará disponible sin el sufijo -preview . Las versiones publicadas no incluyen cambios importantes, aunque es posible que el modelo de datos siga expandiéndose con más funcionalidad. Se admiten versiones publicadas durante un mínimo de 12 meses.

3. En desuso

Las versiones en desuso ya no se admiten y no se cumplen las solicitudes a estas versiones. Si intenta solicitar una versión en desuso o no admitida, recibirá un código de respuesta HTTP 410 y un mensaje como:

No se admite el punto de conexión de OData {version} para Analytics. La información sobre la versión recomendada más reciente está disponible aquí: https://go.microsoft.com/fwlink/?linkid=856818

Cambios importantes frente a cambios que no se rompen

El modelo de datos expuesto por Analytics define el contrato entre el servicio y sus clientes. Según la especificación de OData, los clientes deben ser tolerantes a cambios aditivos en el modelo de datos. Los cambios importantes se introducen en versiones futuras. Para obtener más información, vea Versión 4.0 de OData, parte 5: Control de versiones.

Nota:

El sistema no versiona ningún campo de elemento de trabajo personalizado. El sistema no versiona ningún campo de elemento de trabajo personalizado. Quitar o cambiar los tipos de elementos de trabajo o campos personalizados puede provocar cambios importantes en el modelo. Todos los elementos de trabajo y sus revisiones reflejan la configuración del campo personalizado actual.

Ejemplo de cambios que no se rompen

Considere un escenario en el que se agrega una nueva UserType propiedad a la User entidad. Por ejemplo, los metadatos de la versión v1.0 se muestran en la sintaxis siguiente.

<EntityType Name="User">
    <Key>
        <PropertyRef Name="UserSK"/>
    </Key>
    <Property Name="UserSK" Type="Edm.Guid" Nullable="false"/>
    <Property Name="UserId" Type="Edm.Guid">
        <Annotation Term="Display.DisplayName" String="User Id"/>
    </Property>
    <Property Name="UserName" Type="Edm.String">
        <Annotation Term="Display.DisplayName" String="User Name"/>
    </Property>
    <Property Name="UserEmail" Type="Edm.String">
        <Annotation Term="Display.DisplayName" String="User Email"/>
    </Property>
    <!-- New User Type property -->
    <Property Name="UserType" Type="Edm.Int32">
        <Annotation Term="Display.DisplayName" String="User Type"/>
    </Property>
    <!-- New User Type property -->
</EntityType>

En la versión v4.0-preview , los metadatos se aumentan con cambios aditivos. Estos cambios también se pueden hacer disponibles en versiones anteriores.

<EntityType Name="User">
  <Key>
    <PropertyRef Name="UserSK"/>
  </Key>
  <Property Name="UserSK" Type="Edm.Guid" Nullable="false"/>
  <Property Name="UserId" Type="Edm.Guid">
    <Annotation Term="Display.DisplayName" String="User Id"/>
  </Property>
  <Property Name="UserName" Type="Edm.String">
    <Annotation Term="Display.DisplayName" String="User Name"/>
    <Annotation Term="Microsoft.VisualStudio.Services.Analytics.IsPersonallyIdentifiableInformation" Bool="true"/>
  </Property>
  <Property Name="UserEmail" Type="Edm.String">
    <Annotation Term="Display.DisplayName" String="User Email"/>
    <Annotation Term="Microsoft.VisualStudio.Services.Analytics.IsPersonallyIdentifiableInformation" Bool="true"/>
  </Property>
  <Property Name="AnalyticsUpdatedDate" Type="Edm.DateTimeOffset"/>
  <Property Name="GitHubUserId" Type="Edm.String">
    <Annotation Term="Display.DisplayName" String="GitHub User Id"/>
  </Property>
  <Property Name="UserType" Type="Microsoft.VisualStudio.Services.Analytics.Model.UserType">
    <Annotation Term="Display.DisplayName" String="User Type"/>
  </Property>
</EntityType>

Ejemplo de cambios importantes

Considere un escenario en el que se revierte a la estructura original de la User entidad, lo que da lugar a la eliminación de una característica disponible anteriormente.

<EntityType Name="User">
    <Key>
        <PropertyRef Name="UserSK"/>
    </Key>
    <Property Name="UserSK" Type="Edm.Guid" Nullable="false"/>
    <Property Name="UserId" Type="Edm.Guid" Nullable="false">
        <Annotation Term="Display.DisplayName" String="User Id"/>
    </Property>
    <Property Name="UserName" Type="Edm.String">
        <Annotation Term="Display.DisplayName" String="User Name"/>
    </Property>
    <Property Name="UserEmail" Type="Edm.String">
        <Annotation Term="Display.DisplayName" String="User Email"/>
    </Property>
    <!-- User Type property has been removed -->
</EntityType>

Dado que la eliminación del UserType campo es un cambio importante, el campo no se quita hasta la versión v2.0 de la API. La versión 1.0 del modelo de datos sigue incluyendo el UserType campo.