Controllo delle versioni

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

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.

Release delle versioni principali

Una release principale è definita come una release con una versione incompatibile con le versioni precedenti modifiche all'API. Queste release verranno denominate e avranno endpoint API diversi. Le versioni principali precedenti sono supportate per un periodo di migrazione.

L'API REST di Ad Manager non ha una cadenza di rilascio regolare per le app principali. e versioni successive. Le nuove versioni principali verranno rilasciate solo quando 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à dell'origine: codice scritto sulla base di compilazioni di release precedenti a una release più recente ed è eseguita correttamente con una versione più recente libreria client.

  2. Compatibilità con i cavi: codice scritto rispetto a una release precedente comunica correttamente con un server più recente. In altre parole, non solo gli input e output compatibili, ma la serializzazione e la deserializzazione prevedono continuano a corrispondere.

  3. Compatibilità semantica: il codice scritto sulla base di una versione precedente continua ricevere ciò che gli sviluppatori più ragionevoli si aspetterebbero.

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

Servizi

Tipo di modifica Compatibile 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 di 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 restrizione immutabile Sì
Aggiungi una limitazione immutabile No

Enumerazioni

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

Comportamento dei campi obsoleto

Campi sostitutivi

Per i campi che hanno una sostituzione, entrambi i campi verranno compilati, se possibile. Durante l'aggiornamento, è possibile impostare entrambi i campi. Inclusione di entrambi i campi in un 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. 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à non più disponibili

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

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