Controllo delle versioni

L'API Ad Manager ha sia release di versioni principali denominate sia release in loco compatibili con le versioni precedenti della versione principale corrente.

Servizi, metodi e campi potrebbero essere contrassegnati come ritirati in qualsiasi momento all'interno di una versione principale (ad es. v1), tuttavia rimarranno supportati fino al ritiro della versione principale.

Versioni principali

Una release della versione principale è definita come una release con modifiche all'API incompatibili con le versioni precedenti. Queste release avranno nomi ed endpoint API diversi. Le versioni principali precedenti sono supportate per un periodo di migrazione.

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

Release in loco

Le modifiche compatibili con le versioni precedenti, tra cui nuove funzionalità e correzioni di bug, vengono rilasciate in loco nella versione principale corrente dell'API. I client devono gestire i campi sconosciuti nelle risposte 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 segue:

  1. Compatibilità dell'origine: il codice scritto in base a una release precedente viene compilato in base a una release più recente e viene eseguito correttamente con una versione più recente della libreria client.

  2. Compatibilità del cavo: il codice scritto per una release precedente comunica 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 continuano a corrispondere.

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

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

Servizi

Tipo di modifica Compatibile con le versioni precedenti
Aggiungere 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
Aggiungere un campo obbligatorio No
Aggiungere un campo facoltativo Sì
Spostamento di un campo all'interno o all'esterno di un sottomessaggio No
Modificare un campo da obbligatorio a facoltativo Sì
Modificare un campo da facoltativo a obbligatorio No
Rimuovere una limitazione immutabile Sì
Aggiungere una limitazione immutabile No

Enumerazioni

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

Comportamento dei campi ritirati

Campi di sostituzione

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

Considera il seguente schema:

{
  // 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. L'inclusione di entrambi i campi genera un errore INVALID_ARGUMENT:

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à del prodotto viene ritirata, i campi corrispondenti verranno contrassegnati come obsoleti e potrebbero 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,
}