Contrôle de version de l’API OData

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

Analytics pour Azure DevOps offre une API OData avec version compatible avec les clients conçus pour des versions spécifiques. Chaque version peut inclure des améliorations et des modifications sans rupture, tandis que les modifications cassantes sont introduites dans les versions futures.

La version de l’API suit l’élément _odata du chemin de requête et peut être l’une des versions prises en charge : v1.0, v2.0, v3.0-preview ou v4.0-preview.

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

Remarque

Le service Analytics est automatiquement activé et pris en charge en production pour tous les services Azure DevOps. L’intégration de Power BI et l’accès au flux OData du service Analytics sont généralement disponibles. Nous vous encourageons à l’utiliser et à nous faire part de vos commentaires. Les données disponibles dépendent de la version. La dernière version prise en charge est v2.0, et la dernière version d’évaluation est v4.0-preview. Pour plus d’informations, consultez gestion des versions de l’API OData.

Différences entre les versions

v1.0 et v2.0 : les versions publiées de l’API OData sont stables et n’incluent pas les modifications cassantes. v2.0 inclut des améliorations et plus de fonctionnalités par rapport à la version 1.0.

v3.0-preview et v4.0-preview : les versions préliminaires peuvent inclure des modifications cassants et ne sont pas garanties d’avoir les mêmes fonctionnalités dans la version finale. Ils offrent un accès anticipé aux nouvelles fonctionnalités et améliorations qui ne sont pas encore disponibles dans les versions publiées.

Pourquoi choisir une version spécifique ?

• Stabilité : si vous avez besoin d’une API stable et fiable sans modifier les changements cassants, vous devez choisir l’une des versions publiées (v1.0 ou v2.0).
• Nouvelles fonctionnalités : si vous souhaitez tirer parti des dernières fonctionnalités et améliorations, vous pouvez opter pour l’une des versions préliminaires (v3.0-preview ou v4.0-preview). Toutefois, ces versions peuvent inclure des changements cassants et sont susceptibles de changer.
• Compatibilité : vérifiez que la version que vous choisissez est compatible avec vos clients et systèmes existants. La version de l’API suit l’élément _odata du chemin de requête et peut être l’une des versions prises en charge : v1.0, v2.0, v3.0-preview ou v4.0-preview.

Jeux d’entités pris en charge dans chaque version

Pour plus d’informations sur les EntitySets pris en charge avec chaque version de l’API, consultez Le modèle de données pour Analytics, Entities.

Cycle de vie des révisions

Chaque version de l’API OData passe par les trois phases suivantes pendant son cycle de vie.

1. Phase d’aperçu

Nous allons combiner et publier toutes les modifications cassants ensemble dans les futures versions de l’API. Pour rendre cette fonctionnalité disponible dès que possible, nous mettons en production de nouvelles versions en mode préversion . Les modifications cassants sont toujours possibles pendant qu’une version est en mode préversion et il n’existe aucune garantie que ce qui est inclus dans une version préliminaire est inclus dans la version publiée. La préversion d’une version reste disponible pendant un minimum de six semaines après sa publication.

2. Publiée

Une fois qu’une préversion arrive à maturité et qu’elle est prête pour la mise en production, elle devient disponible sans le suffixe -preview . Les versions publiées n’incluent pas de changements cassants, bien que le modèle de données puisse encore s’étendre avec plus de fonctionnalités. Nous prenons en charge les versions publiées pendant un minimum de 12 mois.

3. Déconseillé

Les versions déconseillées ne sont plus prises en charge et les demandes adressées à ces versions ne sont pas remplies. Si vous tentez de demander une version déconseillée ou non prise en charge, vous recevez un code de réponse HTTP 410 et un message tel que :

Le point de terminaison OData {version} pour Analytics n’est pas pris en charge. Les informations sur la dernière version recommandée sont disponibles ici : https://go.microsoft.com/fwlink/?linkid=856818

Changements cassants et non cassants

Le modèle de données exposé par Analytics définit le contrat entre le service et ses clients. Selon la spécification OData, les clients doivent être tolérants aux modifications additives apportées au modèle de données. Les changements cassants sont introduits dans les futures versions. Pour plus d’informations, consultez OData Version 4.0 Partie 5 : Contrôle de version.

Remarque

Le système ne met pas en version aucun champ d’élément de travail personnalisé. Le système ne met pas en version aucun champ d’élément de travail personnalisé. La suppression ou la modification des types d’éléments de travail ou de champs personnalisés peut entraîner des changements cassants dans votre modèle. Tous les éléments de travail et leurs révisions reflètent la configuration actuelle du champ personnalisé.

Exemple de modifications non cassantes

Envisagez un scénario dans lequel une nouvelle UserType propriété est ajoutée à l’entité User . Par exemple, les métadonnées de la version v1.0 sont indiquées dans la syntaxe suivante.

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

Dans la version v4.0-preview , les métadonnées sont augmentées avec des modifications additives. Ces modifications peuvent également être mises à disposition dans les versions précédentes.

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

Exemple de changements cassants

Envisagez un scénario dans lequel nous revenons à la structure d’origine de l’entité User , ce qui entraîne la suppression d’une fonctionnalité précédemment disponible.

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

Étant donné que la UserType suppression du champ est une modification cassante, le champ n’est pas supprimé tant que la version v2.0 de l’API n’est pas supprimée. La version v1.0 du modèle de données continue d’inclure le UserType champ.

Articles connexes

• Modèle de données pour Analytics
• OData Version 4.0 Partie 5 : Contrôle de version