Contrôle de version de l’API OData

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

À mesure que le service Analytics évolue, nous nous engageons à fournir cohérence et fiabilité à nos utilisateurs. Par conséquent, Analytics pour Azure DevOps fournit une API OData avec version qui est compatible avec les clients conçus pour ces versions. Chaque version peut être améliorée avec davantage de fonctionnalités et des modifications non cassants. Les modifications incompatibles ou cassants seront déployées dans les versions futures de l’API.

La version de l’API suit l’élément _odata dans le chemin de la demande et a la valeur comme l’une de nos 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

Notes

Le service Analytics est automatiquement activé et pris en charge en production pour tous les Azure DevOps Services. L’intégration power BI et l’accès au flux OData du service Analytics sont en disponibilité générale. 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 préversion est v4.0-preview. Pour plus d’informations, consultez Gestion des versions de l’API OData.

Préversions

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

Versions publiées

• v1.0
• v2.0

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

Pour plus d’informations sur les EntitySets pris en charge avec chaque version d’API, consultez Modèle de données pour Analytics, Entités.

Cycle de vie des révisions

Chaque version de l’API OData passe par trois phases au cours de son cycle de vie.

Préversion

Toutes les modifications cassants seront combinées et publiées ensemble dans les versions futures de l’API. Pour rendre cette fonctionnalité disponible le plus tôt possible, publiez de nouvelles versions en mode préversion . Des modifications cassants sont toujours possibles lorsqu’une version est en mode préversion. En outre, il n’y a aucune garantie que ce qui est inclus dans une version préliminaire sera inclus dans une version publiée.

La préversion d’une version sera disponible pendant au moins six semaines après sa publication.

Final

Une fois qu’une version préliminaire mûrit suffisamment pour être publiée, elle est rendue disponible sans le suffixe -preview . Aucune modification cassant ne sera apportée aux versions publiées, mais le modèle de données peut encore croître avec des fonctionnalités additives. Les versions publiées seront prises en charge pendant au moins 12 mois.

Déprécié

Les versions dépréciées ne sont plus prises en charge. Les demandes adressées à une version déconseillée ne seront pas traitées. 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 comme :

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 ou non cassants

Le modèle de données exposé par Analytics définit le contrat entre le service et ses clients. La spécification OData exige que les clients soient tolérants aux modifications additives apportées au modèle de données. Des modifications cassants seront introduites dans les versions futures. Pour plus d’informations, consultez OData Version 4.0 Partie 5 : Gestion des versions

Notes

Le système ne versionner aucun champ d’élément de travail personnalisé. En outre, il est possible de provoquer des modifications cassantes dans votre modèle en supprimant ou en modifiant les types d’éléments de travail ou de champs personnalisés. Tous les éléments de travail et leurs révisions reflètent la configuration actuelle des champs personnalisés.

Exemple de modifications non cassants

Envisagez un scénario où une nouvelle UserType propriété est ajoutée à l’entité User . Par exemple, les métadonnées de la version v1.0 sont comme indiqué 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>

Pour la version v4.0-preview , les métadonnées ont été augmentées. Les modifications sont additives et peuvent être rendues disponibles 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 modifications cassants

Envisagez maintenant un scénario où nous revenons à la structure d’origine de l’entité Utilisateur, entraînant 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 suppression du UserType champ est une modification cassant, le champ n’est supprimé qu’après la version v2.0 de l’API. 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 : Gestion des versions