Gestion des versions

Certaines API Fiche d'établissement sont disponibles dans plusieurs versions et canaux de publication. La version est le segment de l'URL de la requête qui suit le nom d'hôte, par exemple v1 ou v1alpha. Cette page explique comment les versions sont numérotées, comment la stabilité de chaque canal de publication est assurée et comment appeler le canal alpha.

Numérotation des versions

Chaque version d'API comporte un numéro de version majeure et un suffixe de canal facultatif :

  • Version majeure (v1, v2, etc.) : version stable en disponibilité générale. Une version majeure ne reçoit que des modifications rétrocompatibles, telles que de nouvelles méthodes, de nouveaux champs ou de nouvelles valeurs d'énumération. Les modifications qui ne sont pas rétrocompatibles sont publiées dans une nouvelle version majeure.
  • Canal alpha (v1alpha, v2alpha, etc.) : canal de pré-publication d'une version majeure. Il inclut tout ce qui est compris dans cette version majeure, ainsi que des fonctionnalités qui ne sont pas encore en disponibilité générale.

Canaux de publication

Canal Stabilité Sommaire
Disponibilité générale (v1) Stable. Les modifications apportées à une version majeure sont rétrocompatibles. Lorsqu'une version majeure est obsolète, elle reste disponible pendant au moins 12 mois après l'annonce de l'obsolescence. Les abandons et les dates d'arrêt sont publiés sur la page Calendrier d'abandon. Fonctionnalités en disponibilité générale.
Alpha (v1alpha) Version préliminaire, sans engagement de stabilité ni durée de vie définie. Les fonctionnalités alpha peuvent être modifiées ou arrêtées avec un préavis d'au moins 30 jours. N'utilisez pas de fonctionnalités alpha dans les intégrations de production. Tout ce qui est inclus dans v1, plus des fonctionnalités qui ne sont pas encore en disponibilité générale.

Comment les fonctionnalités passent d'un canal à un autre

Lorsqu'une fonctionnalité passe de v1alpha à v1, elle reste disponible dans v1alpha.

Les guides et les pages de référence des fonctionnalités disponibles uniquement dans v1alpha sont marqués comme alpha. Les nouvelles fonctionnalités alpha et en disponibilité générale, ainsi que les modifications ou suppressions de fonctionnalités alpha, sont annoncées dans les Dernières mises à jour et dans le journal des modifications de chaque API.

Utiliser la version alpha

Pour appeler le canal alpha, remplacez v1 par v1alpha dans l'URL de la requête. Exemple :

GET https://mybusinessbusinessinformation.googleapis.com/v1alpha/locations/{locationId}?readMask={readMask}

Les deux canaux appartiennent à la même API. Ils partagent donc les éléments suivants :

  • Activation des API dans la console Google Cloud.
  • Champs d'application OAuth 2.0 et conditions d'accès.
  • Les noms de ressources, comme locations/{locationId}
  • Quota. Les requêtes adressées à v1 et v1alpha sont comptabilisées dans le même quota par projet. Pour en savoir plus, consultez Limites de quota.
  • Les données d'entreprise sous-jacentes. Les modifications que vous apportez via v1alpha sont visibles via v1, et inversement.

Les bibliothèques clientes et l'annuaire d'API publiques n'incluent que v1. Pour appeler v1alpha, envoyez directement des requêtes REST.

Bonnes pratiques

  • Utilisez la version stable, par exemple v1, pour les intégrations en production.
  • Utilisez le canal alpha, tel que v1alpha, pour adopter de nouvelles fonctionnalités avant qu'elles n'atteignent la disponibilité générale. Pour nous envoyer des commentaires, consultez la page Assistance.
  • Faites en sorte que votre client tolère les champs et les valeurs d'énumération qu'il ne reconnaît pas.
  • Avant de créer une fonctionnalité alpha, consultez son guide et le journal des modifications pour connaître les limites connues.