Control de versiones de la API de OData

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

A medida que el servicio analytics madura, estamos dedicados a proporcionar coherencia y confiabilidad a nuestros usuarios. Por lo tanto, Analytics para Azure DevOps proporciona una API de OData con versiones que es compatible con los clientes diseñados para esas versiones. Cada versión se puede mejorar con más funcionalidad y cambios no importantes. Los cambios incompatibles o importantes se inscribirán en versiones futuras de la API.

La versión de la API sigue el elemento _odata en la ruta de acceso de solicitud y tiene el valor como una de nuestras versiones admitidas: v1.0, v2.0, v3.0-preview o v4.0-preview.

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

Nota

El servicio Analytics se habilita automáticamente y se admite en producción para todas las Azure DevOps Services. 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.

Versiones preliminares

• v3.0-preview
• v4.0-preview

Versiones publicadas

• v1.0
• v2.0

Conjuntos de entidades admitidos en cada versión

Para obtener información sobre qué EntitySets son compatibles con cada versión de API, consulte Modelo de datos para Analytics, Entidades.

Ciclo de vida de una versión

Cada versión de la API de OData pasará por tres fases durante su ciclo de vida.

Versión preliminar

Todos los cambios importantes se combinarán y se publicarán juntos en futuras versiones de la API. Para que esta funcionalidad esté disponible lo antes posible, publique también nuevas versiones en modo de vista previa . Los cambios importantes siguen siendo posibles mientras una versión está en modo de vista previa. Además, no hay ninguna garantía de que lo que se incluya en una versión preliminar se incluirá en una versión publicada.

La versión preliminar de una versión estará disponible durante un mínimo de seis semanas después de su lanzamiento.

Lanzamiento

Una vez que una versión preliminar madura lo suficiente para la versión, estará disponible sin el sufijo -preview . No se introducirán cambios importantes en las versiones publicadas, pero el modelo de datos puede seguir creciendo con funcionalidad de adición. Las versiones publicadas se admitirán durante un mínimo de 12 meses.

Obsoleto

Ya no se admiten las versiones en desuso. No se cumplirán las solicitudes realizadas a una versión en desuso. 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 no importantes

El modelo de datos expuesto por Analytics define el contrato entre el servicio y sus clientes. La especificación de OData requiere que los clientes sean tolerantes a cambios aditivos en el modelo de datos. Los cambios importantes se introducirán en versiones futuras. Para obtener más información, vea OData Version 4.0 Part 5: Versioning

Nota

El sistema no versiona ningún campo de elemento de trabajo personalizado. Además, es posible provocar cambios importantes en el modelo quitando o cambiando los tipos de elementos de trabajo o campos personalizados. Todos los elementos de trabajo y sus revisiones reflejarán la configuración actual del campo personalizado.

Ejemplo de cambios no importantes

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>

Para la versión v4.0-preview , se han aumentado los metadatos. Los cambios son aditivos y 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

Ahora considere un escenario en el que reviertemos a la estructura original de la entidad User, lo que provoca 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>

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

Artículos relacionados

• Modelo de datos para Analytics
• Versión 4.0 de OData, parte 5: Control de versiones