Obsługa wersji

Interfejs API Ad Managera ma zarówno wersje główne, jak i wersje zgodne wstecznie, które zastępują bieżącą wersję główną.

Usługi, metody i pola mogą zostać w dowolnym momencie oznaczone jako wycofane w ramach wersji głównej (np. v1), ale będą obsługiwane do czasu wycofania tej wersji głównej.

Wersje główne

Wersja główna to wersja, w której wprowadzono zmiany w interfejsie API powodujące niezgodność wsteczną. Takie wersje będą miały nazwy i różne punkty końcowe interfejsu API. Poprzednie wersje główne są obsługiwane przez okres migracji.

Interfejs API Ad Managera nie ma regularnego harmonogramu publikowania wersji głównych. Nowe wersje główne będą publikowane tylko w razie potrzeby.

Wersje zastępujące

Zmiany zgodne wstecznie, w tym nowe funkcje i poprawki błędów, są publikowane w bieżącej wersji głównej interfejsu API. Klienci muszą obsługiwać nieznane pola w odpowiedziach interfejsu API.

Zgodność wsteczna

Zgodność wsteczna jest zachowywana w przypadku zmian w ramach wersji głównej. Zgodność jest definiowana jako:

  1. Zgodność kodu źródłowego: kod napisany w poprzedniej wersji jest kompilowany w nowszej wersji i działa prawidłowo z nowszą wersją biblioteki klienta.

  2. Zgodność z protokołem: kod napisany w poprzedniej wersji prawidłowo komunikuje się z nowszym serwerem. Innymi słowy, zgodne są nie tylko dane wejściowe i wyjściowe, ale też oczekiwania dotyczące serializacji i deserializacji.

  3. Zgodność semantyczna: kod napisany w poprzedniej wersji nadal otrzymuje to, czego oczekiwałby większość rozsądnych deweloperów.

W tabelach poniżej wymieniono rodzaje zmian w interfejsie API oraz informacje o tym, czy są one zgodne wstecznie.

Usługi

Rodzaj zmiany Zgodność wsteczna
Dodaj nową usługę Tak
Usuń usługę Nie

Metody

Rodzaj zmiany Zgodność wsteczna
Dodaj nową metodę Tak
Usuń metodę Nie
Zmień typ żądania lub odpowiedzi metody Nie

Obiekty

Rodzaj zmiany Zgodność wsteczna
Dodaj pole wymagane Nie
Dodaj pole opcjonalne Tak
Przeniesienie pola do lub z podwiadomości Nie
Zmiana pola z wymaganego na opcjonalne Tak
Zmiana pola z opcjonalnego na wymagane Nie
Usuń ograniczenie niezmienne Tak
Dodaj ograniczenie niezmienne Nie

Wyliczenia

Rodzaj zmiany Zgodność wsteczna
Dodaj wartość typu wyliczeniowego Tak
Usuń wartość typu wyliczeniowego Nie

Działanie wycofanych pól

Pola zastępcze

W przypadku pól, które mają pole zastępcze, oba pola zostaną wypełnione, jeśli będzie to możliwe. Podczas aktualizacji można ustawić dowolne pole. Uwzględnienie obu pól w żądaniu aktualizacji powoduje błąd INVALID_ARGUMENT.

Przyjrzyj się temu schematowi:

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

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

Odpowiedź odczytu wypełnia oba pola równoważnymi wartościami:

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

Żądania aktualizacji mogą ustawiać dowolną wartość. Uwzględnienie obu pól powoduje błąd INVALID_ARGUMENT:

costMicros 

// Update payload
{
  "costMicros": 1500000
}

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

cost 

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

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

Obie opcje 

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

Funkcje wycofane

Jeśli funkcja produktu zostanie wycofana, odpowiednie pola zostaną oznaczone jako wycofane i mogą zwracać semantycznie odpowiednią wartość domyślną. Aktualizacje mogą być ignorowane.

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