Guide de gestion des versions de Compute Engine : API, bibliothèques clientes et outils

Ce guide explique comment Compute Engine gère les versions dans les API REST, les bibliothèques clientes et l'outil de ligne de commande gcloud. Il décrit la différence entre la gestion des versions basée sur les canaux (CBV) et la gestion des versions basée sur les interfaces (IBV), en se concentrant principalement sur cette dernière.

Avant de commencer

  • Si ce n'est pas déjà fait, configurez l'authentification. L'authentification permet de valider votre identité pour accéder aux services et aux API Google Cloud . Pour exécuter du code ou des exemples depuis un environnement de développement local, vous pouvez vous authentifier auprès de Compute Engine en sélectionnant l'une des options suivantes :

    Sélectionnez l'onglet correspondant à la façon dont vous prévoyez d'utiliser les exemples de cette page :

    Console

    Lorsque vous utilisez la console Google Cloud pour accéder aux services et aux API Google Cloud , vous n'avez pas besoin de configurer l'authentification.

    gcloud

    1. Installez la Google Cloud CLI. Une fois que la Google Cloud CLI est installée, initialisez-la en exécutant la commande suivante : 

      gcloud init

      Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  • Définissez une région et une zone par défaut.

    • REST

    Pour utiliser les exemples API REST de cette page dans un environnement de développement local, vous devez utiliser les identifiants que vous fournissez à la gcloud CLI.

      Installez la Google Cloud CLI.

      Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

    Pour en savoir plus, consultez la section S'authentifier pour utiliser REST dans la documentation sur l'authentification Google Cloud .

Gestion des versions basée sur les canaux et sur les interfaces

L'API Compute Engine est compatible avec deux systèmes de gestion des versions : la gestion des versions basée sur les canaux (CBV) et la gestion des versions basée sur les interfaces (IBV).

  • Dans la gestion des versions basée sur les canaux, les versions sont durables et reçoivent des mises à jour sur place. Compute Engine est compatible avec les canaux v1, bêta et alpha.

  • Dans la gestion des versions basée sur les interfaces, les interfaces, les méthodes et les ressources individuelles sont versionnées et peuvent évoluer de manière incrémentielle et indépendante.

L'IBV remplace la CBV. Toutefois, les implémentations existantes de CBV ne sont pas affectées par l'introduction d'IBV ni par les nouvelles versions. Vous pouvez continuer à utiliser le CVB si vous préférez rester sur la version existante de l'API.

L'IBV vous aide à vous assurer que le comportement de l'API, ainsi que sa charge utile de requête et de réponse, sont conformes à une version d'API prévue. Pour utiliser IBV, vous devez spécifier une version de l'API dans votre requête, à l'aide d'un paramètre de requête ou d'un en-tête. Pour en savoir plus, consultez Créer une requête API.

L'utilisation de l'IBV présente les avantages suivants :

  • Stabilité accrue : IBV protège les applications en cours d'exécution contre les modifications en vous permettant d'indiquer la version de l'API avec laquelle le service doit répondre.
  • Contrôle de l'adoption des modifications : avec l'IBV, vous choisissez la version qui répond à votre demande. Cela vous permet de passer aux nouvelles fonctionnalités du service selon votre propre calendrier.

Pour en savoir plus sur les stratégies de gestion des versions, consultez la proposition 185 d'amélioration de l'API.

Règles de gestion des versions basées sur l'interface

Chaque version de l'API Compute Engine IBV est un ensemble de modifications d'interface qui partagent la même version de service, même si les interfaces peuvent changer de version indépendamment.

L'API Compute Engine IBV est compatible avec les versions stables et en preview.

Versions stables

La plupart des versions d'API sont des versions stables. Les versions stables maintiennent une compatibilité stricte, comme défini dans AIP-180. Cela signifie que les nouvelles versions stables de la même version ne cassent pas les fonctionnalités existantes et ne nécessitent pas de réécriture du code.

Compute Engine identifie les versions stables de l'API à l'aide de dates standards au format YYYY-MM-DD (par exemple, 2026-09-01). Les dates ultérieures indiquent des versions plus récentes.

Compute Engine est compatible avec les versions stables sur de longues périodes, ce qui permet à vos systèmes de production de rester fiables et ininterrompus. Pour la plupart des applications, vous n'avez besoin que d'une seule version stable pour effectuer vos tâches quotidiennes.

Versions d'aperçu

Compute Engine peut publier des versions Preview pour recueillir les premiers commentaires des utilisateurs sur les nouvelles fonctionnalités. Les versions preview ajoutent un tag -preview à la date (par exemple, 2026-10-01-preview).

Les versions Preview incluent toutes les fonctionnalités de la dernière version stable, ainsi que de nouvelles fonctionnalités expérimentales. Tenez compte des points suivants lorsque vous utilisez des versions Preview :

  • Les fonctionnalités en avant-première ne garantissent pas la compatibilité avec les versions antérieures ou ultérieures.
  • Nous vous déconseillons d'utiliser les versions Preview pour les environnements de production critiques.
  • Nous pouvons modifier, affiner ou supprimer des fonctionnalités en version Preview lorsque nous les faisons passer à une version stable.

Utilisez les versions d'aperçu lorsque vous souhaitez tester de nouvelles fonctionnalités et prévoyez de mettre à jour votre code lorsqu'une version stable sera disponible.

Spécifier une version d'API dans la requête

Pour effectuer des appels d'API à l'aide de l'IBV, vos requêtes spécifient une version cible à l'aide d'un paramètre de requête ou d'un en-tête. Pour obtenir des exemples de requêtes API, consultez Créer une requête API.

Bibliothèques clientes Google Cloud

Les bibliothèques clientes Cloud vous évitent d'avoir à créer et à analyser des appels REST bruts. Chaque version de la bibliothèque est directement liée à une version de l'API basée sur une date spécifique.

Pour accéder aux nouvelles fonctionnalités, mettez à jour votre package de bibliothèques clientes Cloud vers la dernière version. Nous publions des bibliothèques clientes Cloud mises à jour en même temps que les nouvelles versions stables et en preview des API.

Nous vous recommandons d'exécuter les applications de production sur des bibliothèques clientes Cloud stables, tout en isolant les bibliothèques en version Preview dans des environnements de test.

Google Cloud CLI (gcloud)

La CLI gcloud vous permet de gérer les ressources Compute Engine sans avoir à suivre manuellement les points de terminaison REST individuels.

La CLI gcloud divise les commandes en deux catégories :

  • Commandes stables : les commandes standards (telles que gcloud compute instances create) ciblent les versions stables de l'API. Ces commandes sont entièrement compatibles, prévisibles et recommandées pour les scripts de production.
  • Commandes d'aperçu : les fonctionnalités en accès anticipé utilisent le groupe gcloud preview (par exemple, gcloud preview compute ...). Ces commandes affichent un bref avertissement, car les contrats peuvent changer avant la version finale.

Terraform

Le fournisseur Terraform Google Cloud abstrait la gestion des versions de l'API et gère les interactions sous-jacentes de l'API. Les configurations Terraform n'exposent ni ne nécessitent de paramètres d'en-tête de version manuels.

Pour accéder aux nouvelles fonctionnalités, mettez à jour votre Google Cloud fournisseur Terraform vers la dernière version. Pour les fonctionnalités en preview, utilisez le fournisseur google-beta.

Questions fréquentes

Cette section répond aux questions fréquentes sur la gestion des versions de l'API Compute Engine.

  • Dois-je migrer de la version 1 (CBV) vers l'IBV ?

    Non, les requêtes existantes de l'API CBV v1 continuent de fonctionner comme avant. Toutefois, vous ne pourrez pas accéder aux nouvelles fonctionnalités disponibles dans l'API IBV.

  • Combien de temps une version de l'API IBV sera-t-elle prise en charge ?

    Les versions stables sont conservées indéfiniment conformément aux règles standards d'abandon de Google Cloud.

  • À quelle fréquence de nouvelles versions de l'API IBV sont-elles publiées ?

    De nouvelles versions de l'API IBV sont prévues lors des mises à jour trimestrielles. Les versions preview peuvent être publiées à tout moment.

  • Dois-je activer quelque chose dans la console Google Cloud  ?

    Non, l'API IBV est activée par défaut avec l'API Compute Engine.

  • Que se passe-t-il si je ne spécifie pas de version dans ma demande ?

    Votre demande est définie par défaut sur le point de terminaison CBV v1.

  • Où puis-je trouver la version de l'API dans les entrées Cloud Audit Logs ?

    La version de l'API est consignée dans protoPayload.requestMetadata.callerSuppliedUserAgent et dans les en-têtes ou les paramètres de requête.

Étapes suivantes

Pour en savoir plus sur l'API Compute Engine, consultez les documents suivants :