Versionsverwaltung

Die Ad Manager REST API enthält sowohl Hauptversions-Releases als auch abwärtskompatible direkte Releases zur aktuellen Hauptversion.

Dienste, Methoden und Felder können jederzeit in einem Hauptversion (z. B. v1). Sie werden jedoch bis zu dieser Hauptversion unterstützt. wird eingestellt.

Releases von Hauptversionen

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

Für die Ad Manager REST 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 verarbeiten in API-Antworten.

Abwärtskompatibilität

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

  1. Quellkompatibilität: Code, der für eine vorherige Version geschrieben wurde, wird kompiliert. und erfolgreich mit einer neueren Version des Clientbibliothek.

  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, wird fortgesetzt um das zu erhalten, was die vernünftigsten Entwickler erwarten.

In den folgenden Tabellen sind die Arten von API-Änderungen aufgeführt und die möglichen Auswirkungen abwärtskompatibel.

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
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

Aufzählungen

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

Veraltetes Feldverhalten

Ersatzfelder

Bei Feldern mit einem Ersatz werden nach Möglichkeit beide Felder ausgefüllt. Beim Aktualisieren kann jedes Feld festgelegt werden. Beide Felder in eine Aktualisierung einbeziehen -Anfrage führt 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)
  }
}

Eine Leseantwort füllt beide Felder mit äquivalenten Werten:

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

Bei Aktualisierungsanfragen können beide Werte festgelegt werden. Das Einschließen beider Felder führt zu einer 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 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,
}