Versionsverwaltung

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

Dienste, Methoden und Felder können innerhalb einer Hauptversion (z. B. Version 1) jederzeit als eingestellt gekennzeichnet werden. Sie werden jedoch bis zur Einstellung dieser Hauptversion unterstützt.

Hauptversionen

Eine Hauptversion wird als Release mit nicht abwärtskompatiblen API-Änderungen definiert. Diese Releases werden benannt und haben unterschiedliche API-Endpunkte. Vorherige Hauptversionen werden für einen Migrationszeitraum unterstützt.

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

Direkte Releases

Abwärtskompatible Änderungen, einschließlich neuer Funktionen und Fehlerkorrekturen die der aktuellen Haupt-API-Version entsprechen. Clients müssen unbekannte Felder in API-Antworten verarbeiten.

Abwärtskompatibilität

Die Abwärtskompatibilität wird für Änderungen innerhalb einer Hauptversion beibehalten. Kompatibilität ist definiert als:

  1. Quellkompatibilität: Code, der für eine vorherige Version geschrieben wurde, kann in einer neueren Version kompiliert und mit einer neueren Version der Clientbibliothek ausgeführt werden.

  2. Wire-Kompatibilität: Code, der aus einem früheren Release geschrieben wurde mit einem neueren Server korrekt kommuniziert. Mit anderen Worten, es sind nicht nur Eingaben und Ausgaben kompatibel, aber die Serialisierung und Deserialisierung weiter übereinstimmen.

  3. Semantische Kompatibilität: Code, der für eine vorherige Version geschrieben wurde, funktioniert weiterhin wie erwartet.

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

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 untergeordnete Nachricht oder aus einer untergeordneten Nachricht verschieben Nein
Ein Feld von „erforderlich“ in „optional“ ändern Ja
Ein Feld von „optional“ in „erforderlich“ ändern Nein
Unveränderliche Einschränkung entfernen Ja
Unveränderliche Einschränkung hinzufügen Nein

Aufzählungen

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

Verhalten eingestellter Felder

Ersatzfelder

Bei Feldern, für die es einen Ersatz gibt, werden, sofern möglich, beide Felder ausgefüllt. Bei der Aktualisierung kann jedes Feld festgelegt werden. Wenn Sie beide Felder in eine Aktualisierungsanfrage aufnehmen, führt dies zu einem INVALID_ARGUMENT-Fehler.

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 äquivalenten Werten ausgefüllt:

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

Bei Aktualisierungsanfragen kann entweder der eine oder der andere Wert festgelegt werden. Wenn Sie beide Felder angeben, führt das zu einem INVALID_ARGUMENT-Fehler:

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 wie folgt gekennzeichnet: veraltet und gibt möglicherweise einen semantisch geeigneten Standardwert zurück. Aktualisierungen ignoriert werden kann.

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