Contrôle de version, support et stratégies de modification importante pour Microsoft Graph

  • Article

Cet article décrit la prise en charge et les stratégies de modification importante pour Microsoft Graph et les versions de l’API Microsoft Graph qui sont actuellement disponibles.

Stratégie de prise en charge et informations d’obsolescence

Microsoft Graph suit la politique concernant le cycle de vie de Microsoft.

À mesure que de nouvelles versions des API REST Microsoft Graph seront publiées, les versions antérieures seront mises hors service. Microsoft déclare une version comme déconseillée au moins 24 mois avant le retrait. De même, pour les API individuelles qui ont atteint la disponibilité générale( GA), Microsoft déclare une API comme déconseillée au moins 24 mois avant de la supprimer de la version ga.

Pour les sdk Microsoft Graph, seule la dernière version principale d’une bibliothèque donnée est prise en charge et mise à jour avec de nouvelles fonctionnalités, des correctifs de bogues et des solutions de contournement. La version principale qui précède la dernière version est prise en charge pendant 12 mois à partir de la date de publication de la dernière version majeure, uniquement pour les correctifs de sécurité. Nous vous recommandons d’effectuer une mise à niveau vers la dernière version des Kits de développement logiciel (SDK) dans la mesure du possible.

Lorsque nous incrémentons la version principale de l’API (par exemple, de v1.0 à v2.0), nous annonçons que la version actuelle (dans cet exemple, v1.0) est immédiatement déconseillée et que nous ne la prendrons plus en charge 24 mois après l’annonce. Nous pouvons définir des exceptions à cette stratégie en cas de problèmes de sécurité du service ou de fiabilité de l’intégrité.

Lorsqu’une API est marquée comme obsolète, nous vous recommandons vivement de migrer vers la dernière version dès que possible. Dans certains cas, nous allons annoncer que les nouvelles applications devront commencer à utiliser les nouvelles API peu de temps après la dépréciation des API d’origine. Dans ces cas, seules les applications actives qui utilisent actuellement les API déconseillées peuvent continuer à les utiliser.

Contrat d’API et modifications non rétrocompatibles

Microsoft Graph possède un journal des modifications entre les versions. Ces modifications sont répertoriées dans le journal des modifications Microsoft Graph. À mesure que de nouvelles fonctionnalités et données sont ajoutées à Microsoft Graph, nous incrémentons le numéro de version de l’API pour toutes les modifications de l’API non compatibles avec les back-back.

Voici des exemples de modifications non compatibles avec les back-back :

  • Modifications apportées à l’URL ou à une requête/réponse fondamentale associée à une ressource
  • Suppression, changement de nom ou modification du type d’une propriété déclarée
  • Suppression ou modification du nom des API ou des paramètres de l’API
  • Ajout d’un en-tête de requête requis

Voici quelques exemples de modifications à compatibilité descendante :

  • Ajout de propriétés qui peuvent avoir la valeur Null ou comportent une valeur par défaut
  • Ajout d’un membre à une énumération
  • Suppression, changement de nom ou modification du type d’une extension d’ouverture
  • Suppression, changement de nom ou modification du type d’une annotation
  • Présentation de pagination pour des collections existantes
  • Modifications apportées aux codes d’erreur
  • Modifications apportées à l’ordre des propriétés
  • Modifications apportées à la longueur ou au format de chaînes opaques, notamment des ID de ressource

Note: Au fil du temps, nous mettons à jour la liste des modifications de compatibilité descendante. Si vous générez vos propres proxys clients (par exemple, les clients WCF), nous vous conseillons de préparer vos applications clientes à recevoir des propriétés et des types dérivés qui n’ont pas été préalablement définis par le service API Microsoft Graph. L’API Microsoft Graph suit les instructions décrites dans la section Contrôle de version des modèles dans les instructions de l’API REST Microsoft.

Versions

Les versions suivantes de l’API Microsoft Graph sont actuellement disponibles.

Version bêta

En général, les API sont lancées dans la version bêta et sont accessibles dans le point de terminaison https://graph.microsoft.com/beta. Pour une documentation de l’API bêta, voir Référence du point de terminaison bêta de Microsoft Graph. Prévoyez des modifications importantes et la dépréciation des API de la version bêta de temps à autre. L’utilisation d’API bêta dans les applications de production n’est pas prise en charge.

Nous ne fournissons aucune garantie qu’une fonctionnalité bêta sera promue vers la version actuelle. Lorsque l’équipe de l’API Microsoft Graph estime qu’une fonctionnalité bêta est prête pour la disponibilité générale, nous ajoutons cette fonctionnalité à la dernière version actuelle. Si la promotion de la fonctionnalité entraîne un changement cassant de la version actuelle, le numéro de version est incrémenté, la nouvelle version devenant la version actuelle.

Version actuelle

La version actuelle de Microsoft Graph est la version 1.0. Ces API sont accessibles dans le point de https://graph.microsoft.com/v1.0 terminaison. La version de l’API Microsoft Graph v1.0 contient des fonctionnalités généralement disponibles et prêtes à être utilisées en production. Pour obtenir la documentation de l’API v1.0, consultez Informations de référence sur le point de terminaison Microsoft Graph v1.0.

État de préversion

Une API ou une fonctionnalité dans Microsoft Graph est étiquetée « (préversion) » pour indiquer que son comportement est unique dans le point de terminaison bêta.

Le comportement de la plupart des fonctionnalités et API de la version v1.0 va de pair avec la version bêta. Certaines API sont marquées comme « préversion » pour l’une des raisons suivantes :

  • Les API sont disponibles uniquement en version bêta
  • Le comportement des API est différent dans la version bêta de la version 1.0

Comme toute autre API dans le point de terminaison bêta, nous pouvons introduire des modifications cassants dans les API qui sont marquées comme préversion sans préavis. N’accédez pas aux API à partir du point de terminaison bêta dans les applications de production.

Note: Les API peuvent être en préversion même lorsque la fonctionnalité ou le produit lui-même est généralement disponible.

Versions déconseillées et non prises en charge

Actuellement, aucune version de Microsoft Graph n’est déconseillée ou non prise en charge.

Conditions d’utilisation

En utilisant les API Microsoft Graph, vous acceptez leurs conditions d’utilisation.

Votre avis compte beaucoup pour nous. Contactez-nous sur Microsoft Q&A. Étiquetez vos questions avec [microsoft-graph-*].