Gestion des versions

L'API REST Ad Manager comporte à la fois des versions majeures nommées versions sur place rétrocompatibles vers la version majeure actuelle.

Les services, méthodes et champs peuvent être marqués comme obsolètes à tout moment dans une Les versions majeures (par exemple, v1) restent compatibles jusqu'à est supprimée.

Versions majeures

Une version majeure est définie comme une version ayant une incompatibilité ascendante Modifications apportées à l'API. Ces versions seront nommées et auront des points de terminaison d'API différents. Les versions majeures précédentes sont compatibles pendant une période de migration.

L'API REST Ad Manager n'a pas de fréquence de publication régulière pour les niveaux majeurs versions. Les nouvelles versions majeures ne seront publiées qu'en cas de nécessité.

Versions sur place

Publication de modifications rétrocompatibles, y compris de nouvelles fonctionnalités et corrections de bugs vers la version majeure actuelle de l'API. Les clients doivent gérer des champs inconnus dans les réponses de l'API.

Rétrocompatibilité

La rétrocompatibilité est maintenue pour les modifications apportées dans une version majeure. La compatibilité est définie comme suit:

  1. Compatibilité avec la source: le code écrit sur une version précédente est compilé par rapport à une nouvelle version et s'exécute avec succès avec une version plus récente du bibliothèque cliente.

  2. Compatibilité avec les réseaux: code écrit par rapport à une version précédente communique correctement avec un serveur plus récent. Autrement dit, les entrées et les sorties, mais les attentes en termes de sérialisation et de désérialisation continuent de correspondre.

  3. Compatibilité sémantique: le code écrit par rapport à une version précédente continue de recevoir ce à quoi les développeurs les plus raisonnables s'attendent.

Les tableaux suivants énumèrent les types de modifications apportées à l'API et indiquent si elles sont prises en compte rétrocompatible.

Services

Type de modification Rétrocompatible
Ajouter un service Oui
Supprimer un service Non

Méthodes

Type de modification Rétrocompatible
Ajouter une méthode Oui
Supprimer une méthode Non
Modifier le type de requête ou de réponse d'une méthode Non

Objets

Type de modification Rétrocompatible
Ajouter un champ obligatoire Non
Ajouter un champ facultatif Oui
Déplacer un champ vers ou depuis un sous-message Non
Faire passer un champ de obligatoire à facultatif Oui
Remplacer un champ facultatif par obligatoire Non
Supprimer une restriction immuable Oui
Ajouter une restriction immuable Non

Énumérations

Type de modification Rétrocompatible
Ajouter une valeur d'énumération Oui
Supprimer une valeur d'énumération Non

Comportement de champ obsolète

Champs de remplacement

Pour les champs comportant un remplacement, les deux champs seront renseignés dans la mesure du possible. Lors de la mise à jour, vous pouvez définir l'un ou l'autre des champs. Inclure les deux champs dans une mise à jour la requête génère une erreur INVALID_ARGUMENT.

Prenons le schéma suivant:

{
  // The cost of this Foo in micros.
  // Deprecated: Use `cost` instead.
  "costMicros": number,

  // The cost of this Foo.
  "cost": {
    object (Money)
  }
}

Une réponse de lecture renseigne les deux champs avec des valeurs équivalentes:

{
  "costMicros": 1250000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 250000000
  }
}

Les demandes de mise à jour peuvent définir l'une ou l'autre des valeurs. Inclure les deux champs génère INVALID_ARGUMENT erreur:

costMicros 

// Update payload
{
  "costMicros": 1500000
}

// Response payload
{
  "costMicros": 1500000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

coût 

// Update payload
{
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

// Response payload
{
  "costMicros": 1500000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

Les deux 

// Update payload
{
  "costMicros": 1250000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

// Response payload
{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "costMicros",
            "description": "Cannot update both costMicros and cost."
          }
        ]
      }
    ]
  }
}

Fonctionnalités abandonnées

Si une fonctionnalité du produit n'est plus disponible, les champs correspondants seront marqués comme obsolète et peut renvoyer une valeur par défaut sémantiquement appropriée. Mises à jour peuvent être ignorées.

{
  // The salesperson split amount in micros.
  // Deprecated: The Sales Management feature has been deprecated. This field
  // will always be `0`.
  "salespersonSplitMicros": number,
}