Google Ads API : guide de migration entre versions et gestion des sunset dates
La Google Ads API suit un cycle de versionnement strict : Google publie plusieurs versions par an et applique des sunset dates au-delà desquelles les anciennes versions cessent de fonctionner. En 2026, la version v24 est la plus récente. Rester sur une version dépréciée expose vos intégrations à des interruptions critiques — comprendre le cycle de vie des versions est donc indispensable pour tout développeur utilisant l’API.
Comprendre le cycle de versionnement de la Google Ads API
Google publie généralement 3 à 4 versions majeures par an. Chaque version reste active pendant environ 12 mois avant d’être dépréciée. Le calendrier suit une logique prévisible :
| Phase | Durée typique | Description |
|---|---|---|
| Release | J+0 | Nouvelle version disponible, annonce officielle dans les release notes |
| Active | ~12 mois | Version supportée, correctifs de bugs appliqués |
| Sunset announced | ~3 mois avant fin | Google annonce la date de sunset avec 90 jours de préavis minimum |
| Sunset | Fin | Les appels API retournent des erreurs, migration obligatoire |
Versions actives et sunset dates en 2026
Depuis la sortie de la Google Ads API v24 le 22 avril 2026, voici l’état des versions :
- v24 (avril 2026) — Version actuelle, supportée
- v23.2 / v23.1 / v23 — Versions encore actives, sunset à prévoir fin 2026
- v22 et antérieures — Dépréciées ou en cours de sunset — migration urgente requise
⚠️ Consultez toujours la roadmap officielle Google Ads API pour les dates exactes. Les sunset dates sont publiées sur le portail développeurs Google avec un préavis minimum de 90 jours.
Comment préparer une migration de version
Étape 1 — Auditer vos intégrations existantes
Avant toute migration, cartographiez l’ensemble de vos appels API actuels :
- Listez tous les services utilisés (CampaignService, AdGroupService, ReportingService…)
- Identifiez les champs et enums présents dans vos requêtes GAQL
- Repérez les bibliothèques client utilisées et leur version
- Documentez les breaking changes listés dans les release notes entre votre version actuelle et la cible
Si vous n’avez pas encore configuré votre accès à l’API, commencez par notre guide : obtenir son developer token et configurer OAuth2.
Étape 2 — Lire les release notes de chaque version intermédiaire
Si vous migrez de v21 vers v24 par exemple, lisez les release notes de chaque version intermédiaire (v22, v23, v23.1, v23.2, v24). Les breaking changes s’accumulent — en sauter une peut provoquer des erreurs silencieuses.
Structure des release notes à analyser :
- Breaking changes : champs supprimés, types modifiés, comportements changés
- New features : nouveaux champs et services disponibles
- Deprecations : éléments qui seront supprimés dans la prochaine version
Étape 3 — Mettre à jour les bibliothèques client
Google fournit des bibliothèques client officielles pour 6 langages. Chaque version majeure de l’API correspond à une version spécifique de la bibliothèque :
| Langage | Gestionnaire de paquets | Mise à jour |
|---|---|---|
| Python | pip | pip install --upgrade google-ads |
| Java | Maven / Gradle | Mettre à jour la version dans pom.xml |
| PHP | Composer | composer update google/ads-googleads |
| Ruby | Bundler | Mettre à jour Gemfile |
| .NET | NuGet | Mettre à jour le package NuGet |
| Go | Go modules | go get google.golang.org/genproto |
Étape 4 — Tester en environnement sandbox
Avant toute mise en production, validez votre migration sur un compte de test Google Ads :
- Créez un compte test depuis votre MCC (option disponible dans les paramètres)
- Exécutez l’ensemble de vos requêtes GAQL sur ce compte test
- Vérifiez que les réponses correspondent aux structures attendues dans la nouvelle version
- Testez spécifiquement chaque breaking change identifié à l’étape 1
Étape 5 — Déploiement progressif
Déployez la migration en production de manière progressive :
- Commencez par 1 à 2 comptes clients peu critiques
- Monitorez les erreurs API en temps réel pendant 24-48h
- Étendez progressivement à l’ensemble du parc de comptes
- Gardez la possibilité de rollback rapide vers l’ancienne version pendant la période de transition
Breaking changes fréquents entre versions
Suppressions de champs
C’est la cause numéro 1 d’erreurs lors des migrations. Un champ supprimé dans vos requêtes GAQL provoque une erreur FIELD_NOT_FOUND. Stratégie : avant la migration, grep l’ensemble de votre codebase avec les noms des champs supprimés listés dans les release notes.
Changements de types
Certains champs changent de type entre versions (ex: passage de InsightsAudienceAttributeGroup à common.InsightsAudienceAttributeGroup en v24). Ces changements cassent silencieusement les bibliothèques client typées (Java, .NET, Go) sans provoquer d’erreur explicite.
Enums supprimés ou renommés
Les enums supprimés (ex: LOYALTY_SIGN_UPS en v24) causent des erreurs lors de la création ou la lecture d’entités qui référencent ces valeurs. Mettez à jour toutes les comparaisons et mappings d’enums dans votre code.
Automatiser la surveillance des sunset dates
Pour ne jamais être surpris par un sunset, mettez en place ces pratiques :
- S’abonner au blog développeurs Google Ads (ads-developers.googleblog.com)
- Créer une alerte Google Alerts sur « Google Ads API sunset »
- Intégrer un check de version dans vos scripts de monitoring
- Planifier une revue trimestrielle des versions et roadmap API
FAQ — Migration Google Ads API
Que se passe-t-il si je ne migre pas avant le sunset ?
Après la sunset date, tous vos appels API sur la version dépréciée retournent une erreur. Vos campagnes continuent de fonctionner normalement dans Google Ads, mais toute automatisation ou reporting via votre intégration API s’arrête immédiatement. La migration devient alors urgente et sous pression.
Combien de temps prend une migration entre versions ?
Cela dépend de la complexité de votre intégration et du nombre de breaking changes. Pour une intégration simple (reporting + création de campagnes), comptez 1 à 3 jours de développement. Pour une plateforme complexe couvrant tous les services, prévoyez 1 à 2 semaines incluant les tests.
Faut-il migrer à chaque nouvelle version ?
Non, vous n’êtes pas obligé de migrer à chaque release. En revanche, ne restez jamais plus de 2 versions en retard — les breaking changes s’accumulent et la migration devient plus lourde. Migrez au minimum une fois tous les 6 mois pour maintenir une dette technique raisonnable.
Les nouveautés de la v24 nécessitent-elles une migration urgente ?
La Google Ads API v24 introduit plusieurs breaking changes (champs vidéo obligatoires, suppression de champs Planning, modification de types). Si vous utilisez ces fonctionnalités, une mise à jour est recommandée dans les 3 mois suivant la release pour rester dans la fenêtre de support confortable.
Voir aussi : Conversions offline avec la Google Ads API — un cas d’usage courant qui évolue à chaque version majeure.
Article rédigé par l’équipe AdSim, agence de marketing digital à Liège. Mise à jour : mai 2026.
