Versionsverwaltung

Die Ad Manager API bietet sowohl benannte Hauptversionen als auch abwärtskompatible In-Place-Releases für die aktuelle Hauptversion.

Dienste, Methoden und Felder können jederzeit innerhalb einer Hauptversion (z. B. v1) als veraltet markiert werden. Sie werden jedoch weiterhin unterstützt, bis diese Hauptversion eingestellt wird.

Releases von Hauptversionen

Ein Release einer Hauptversion ist ein Release mit nicht abwärtskompatiblen API-Änderungen. Diese Releases werden benannt und haben unterschiedliche API-Endpunkte. Frühere Hauptversionen werden für einen Migrationszeitraum unterstützt.

Für die Ad Manager API gibt es keinen regelmäßigen Release-Zyklus für Hauptversionen. Neue Hauptversionen werden nur bei Bedarf veröffentlicht.

In-Place-Releases

Abwärtskompatible Änderungen, einschließlich neuer Funktionen und Fehlerbehebungen, werden als In-Place-Release für die aktuelle Hauptversion der API veröffentlicht. Clients müssen unbekannte Felder in API-Antworten verarbeiten.

Abwärtskompatibilität

Die Abwärtskompatibilität bleibt für Änderungen innerhalb einer Hauptversion erhalten. Kompatibilität wird so definiert:

  1. Quellkompatibilität: Code, der für ein früheres Release geschrieben wurde, wird für ein neueres Release kompiliert und kann mit einer neueren Version der Clientbibliothek ausgeführt werden.

  2. Verbindungskompatibilität: Code, der für ein früheres Release geschrieben wurde, kommuniziert korrekt mit einem neueren Server. Mit anderen Worten: Nicht nur Ein- und Ausgaben sind kompatibel, sondern auch die Erwartungen an Serialisierung und Deserialisierung stimmen weiterhin überein.

  3. Semantische Kompatibilität: Code, der für eine frühere Version geschrieben wurde, liefert weiterhin das, was die meisten Entwickler erwarten würden.

In den folgenden Tabellen sind die Arten von API-Änderungen aufgeführt und es wird angegeben, ob sie als abwärtskompatibel gelten.

Dienste

Art der Änderung Abwärtskompatibel
Neuen Dienst hinzufügen Ja
Dienst entfernen Nein

Methoden

Art der Änderung Abwärtskompatibel
Neue Methode hinzufügen Ja
Methode entfernen Nein
Anfrage- oder Antworttyp einer Methode ändern Nein

Objekte

Art der Änderung Abwärtskompatibel
Pflichtfeld hinzufügen Nein
Optionales Feld hinzufügen Ja
Feld in eine Unterbotschaft verschieben oder daraus entfernen Nein
Feld von „erforderlich“ in „optional“ ändern Ja
Feld von „optional“ in „erforderlich“ ändern Nein
Unveränderliche Einschränkung entfernen Ja
Unveränderliche Einschränkung hinzufügen Nein

Enumerationen

Art der Änderung Abwärtskompatibel
Enum-Wert hinzufügen Ja
Enum-Wert entfernen Nein

Verhalten bei veralteten Feldern

Ersatzfelder

Für Felder, die einen Ersatz haben, werden nach Möglichkeit beide Felder ausgefüllt. Beim Aktualisieren kann eines der beiden Felder festgelegt werden. Wenn beide Felder in einer Aktualisierungsanfrage enthalten sind, wird ein INVALID_ARGUMENT-Fehler zurückgegeben.

Betrachten Sie das folgende Schema:

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

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

In einer Leseantwort werden beide Felder mit entsprechenden Werten ausgefüllt:

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

In Aktualisierungsanfragen kann einer der beiden Werte festgelegt werden. Wenn beide Felder enthalten sind, wird ein INVALID_ARGUMENT-Fehler zurückgegeben:

costMicros 

// Update payload
{
  "costMicros": 1500000
}

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

Kosten 

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

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

Beides 

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

Eingestellte Funktionen

Wenn eine Produktfunktion eingestellt wird, werden die entsprechenden Felder als veraltet markiert und geben möglicherweise einen semantisch geeigneten Standardwert zurück. Aktualisierungen können ignoriert werden.

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