L'API Ad Manager propose à la fois des versions nommées de la version majeure et des versions in situ rétrocompatibles avec la version majeure actuelle.
Les services, les méthodes et les champs peuvent être marqués comme obsolètes à tout moment dans une version majeure (par exemple, la version 1). Toutefois, ils resteront compatibles jusqu'à ce que cette version majeure soit abandonnée.
Versions majeures
Une version majeure est définie comme une version avec des modifications de l'API incompatibles avec les versions antérieures. 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 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
Les modifications rétrocompatibles, y compris les nouvelles fonctionnalités et les corrections de bugs, sont publiées dans la version majeure actuelle de l'API. Les clients doivent gérer les 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é se définit comme suit :
Compatibilité avec la source : le code écrit avec une version précédente est compilé avec une version plus récente et s'exécute avec une version plus récente de la bibliothèque cliente.
Compatibilité avec les réseaux: code écrit par rapport à une version précédente communique correctement avec un serveur plus récent. En d'autres termes, non seulement les entrées et les sorties sont compatibles, mais les attentes de sérialisation et de désérialisation continuent de correspondre.
Compatibilité sémantique : le code écrit pour une version précédente continue de recevoir ce à quoi la plupart des développeurs 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 un sous-message ou en dehors | Non |
| Passer un champ du mode obligatoire au mode 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 des champs obsolètes
Champs de remplacement
Pour les champs ayant un remplacement, les deux champs seront renseignés lorsque cela est 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 requêtes de mise à jour peuvent définir l'une ou l'autre valeur. 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é de produit est abandonnée, les champs correspondants sont marqués comme obsolètes et peuvent renvoyer une valeur par défaut sémantiquement appropriée. Les 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,
}