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.

Lorsque de nouvelles versions des API REST Microsoft Graph et des kits de développement logiciel Microsoft Graph sont publiées, les versions antérieures sont supprimées. Microsoft déclare une version comme déconseillée au moins 24 mois avant le retrait. De même, pour les API individuelles généralement disponibles, Microsoft estime qu’une API est hors service au moins 24 mois avant de la supprimer de la version GA.

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

Remarque :au fil du temps, nous mettrons à jour la liste des modifications à 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. N’utilisez pas de dépendance de production sur les API bêta.

Nous ne fournissons aucune garantie qu’une fonctionnalité bêta sera promue vers la version actuelle. Lorsque l’équipe Microsoft API 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. Notre communauté de développeurs peut publier des demandes de fonctionnalités sur le forum d’idées de plateforme de développement Microsoft 365, y compris les demandes de nouvelles fonctionnalités et les demandes de promotion des API bêta existantes vers la version actuelle.

Version actuelle

La version actuelle de Microsoft Graph est la version 1.0. Présentée sous https://graph.microsoft.com/v1.0, la version v1.0 de l’API Microsoft Graph contient des fonctionnalités qui sont généralement disponibles et prêtes pour une utilisation en production. Parcourez la documentation pour les API v1.0.

État de préversion

Une API ou une fonctionnalité dans Microsoft Graph est étiquetée comme « (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. « préversion » qualifie une minorité de fonctionnalités et d’API dans l’un des deux cas suivants :

  • Disponible uniquement en version bêta
  • Disponible dans une version bêta différente de la version v1.0

Comme toutes les autres API du point de terminaison bêta, les API marquées dans la documentation comme « (préversion) » peuvent subir des modifications sans préavis. N’accédez pas aux API à partir du point de terminaison bêta dans les applications de production.

Par exemple, la formation à la simulation d’attaques est une fonctionnalité généralement disponible pour les administrateurs dans le portail Microsoft 365 Defender. Lorsque l’API REST pour l’entraînement à la simulation d’attaque devient disponible dans Microsoft Graph uniquement dans le point de terminaison bêta, la documentation de l’API REST est étiquetée comme « (préversion) ». L’étiquette « (aperçu) » s’applique à l’API REST et à sa documentation dans Microsoft Graph, même si le service lui-même est généralement disponible.

Versions déconseillées et non prises en charge

Il n’existe actuellement aucune version déconseillée de Microsoft Graph.

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-*].