Controllo delle versioni

L'API Ad Manager ha sia release principali con nome sia release in-place compatibili con le versioni precedenti della versione principale corrente.

I servizi, i metodi e i campi possono essere contrassegnati come deprecati in qualsiasi momento all'interno di un Versione Major (ad es. v1), che rimarrà supportata fino alla versione Major viene ritirata.

Uscite delle versioni principali

Una release di versione principale è definita come una release con modifiche alle API non compatibili con le versioni precedenti. Queste release saranno denominate e avranno endpoint API diversi. Le versioni principali precedenti sono supportate per un periodo di migrazione.

L'API Ad Manager non ha una cadenza regolare di rilascio per le versioni principali. Le nuove versioni principali verranno rilasciate solo se necessario.

Release in loco

Vengono rilasciate modifiche compatibili con le versioni precedenti, incluse nuove funzionalità e correzioni di bug rispetto all'attuale versione dell'API principale. I client devono gestire campi sconosciuti nelle risposte delle API.

Compatibilità con le versioni precedenti

La compatibilità con le versioni precedenti viene mantenuta per le modifiche all'interno di una versione principale. La compatibilità è definita come:

  1. Compatibilità del codice sorgente: il codice scritto per una release precedente viene compilato per una release più recente ed eseguito correttamente con una versione più recente della libreria client.

  2. Compatibilità con il cavo: il codice scritto per una release precedente comunicate correttamente con un server più recente. In altre parole, non solo gli input e gli output sono compatibili, ma le aspettative di serializzazione e deserializzazione continueranno a corrispondere.

  3. Compatibilità semantica: il codice scritto per una versione precedente continua a ricevere ciò che la maggior parte degli sviluppatori ragionevoli si aspetterebbe.

Le seguenti tabelle elencano i tipi di modifiche all'API e se vengono considerate compatibili con le versioni precedenti.

Servizi

Tipo di modifica Compatibilità con le versioni precedenti
Aggiungi un nuovo servizio Sì
Rimuovere un servizio No

Metodi

Tipo di modifica Compatibile con le versioni precedenti
Aggiungere un nuovo metodo Sì
Rimuovere un metodo No
Modificare il tipo di richiesta o risposta di un metodo No

Oggetti

Tipo di modifica Compatibile con le versioni precedenti
Aggiungi un campo obbligatorio No
Aggiungi un campo facoltativo Sì
Spostare un campo all'interno o all'esterno di un messaggio secondario No
Modificare un campo da obbligatorio a facoltativo Sì
Modificare un campo da facoltativo a obbligatorio No
Rimuovere una limitazione immutabile Sì
Aggiungi una limitazione immutabile No

Enumerazioni

Tipo di modifica Compatibile con le versioni precedenti
Aggiungi un valore enum Sì
Rimuovere un valore enum No

Comportamento dei campi obsoleto

Campi sostitutivi

Per i campi che hanno un valore sostitutivo, entrambi i campi verranno compilati, se possibile. Durante l'aggiornamento, è possibile impostare entrambi i campi. L'inclusione di entrambi i campi in una richiesta di aggiornamento genera un errore INVALID_ARGUMENT.

Considera lo schema seguente:

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

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

Una risposta di lettura compila entrambi i campi con valori equivalenti:

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

Le richieste di aggiornamento possono impostare uno dei due valori. Se includi entrambi i campi, INVALID_ARGUMENT errore:

costMicros 

// Update payload
{
  "costMicros": 1500000
}

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

costo 

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

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

Entrambi 

// 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."
          }
        ]
      }
    ]
  }
}

Funzionalità ritirate

Se una funzionalità di un prodotto non è più disponibile, i campi corrispondenti verranno contrassegnati come deprecato e può restituire un valore predefinito semanticamente appropriato. Gli aggiornamenti possono essere ignorati.

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