Obsługa wersji

Interfejs Ad Manager API zawiera zarówno nazwane wersje główne, jak i wersje w miejscu, które są zgodne z poprzednimi wersjami.

Usługi, metody i pola mogą zostać oznaczone jako wycofane w dowolnym momencie w wersji głównej (np.v1). Będą one jednak obsługiwane do czasu została wycofana.

Wersje główne

Duża wersja to wersja z niezgodnymi wstecz zmianami w interfejsie API. Te wersje będą miały nazwy i różne punkty końcowe interfejsu API. Wcześniejsze główne wersje są obsługiwane w okresie migracji.

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

Wersje na miejscu

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

Zgodność wsteczna

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

  1. Zgodność źródła: kod napisany w porównaniu z poprzednią wersją to kompilacja w porównaniu z nowszą wersją programu z biblioteką klienta.

  2. Zgodność z wersją roboczą: kod napisany w porównaniu z poprzednią wersją komunikuje się prawidłowo z nowszym serwerem. Innymi słowy, dane wejściowe i wyjściowe są zgodne, a oczekiwania dotyczące serializacji i deserializacji są nadal takie same.

  3. Zgodność semantyczna: kod napisany w poprzedniej wersji nadal zachowuje oczekiwane przez większość rozsądnych programistów właściwości.

W tabeli poniżej wymieniono typy zmian w interfejsie API i wskazano, czy są one zgodne ze starszymi wersjami.

Usługi

Typ zmiany Zgodność wsteczna
Dodawanie nowej usługi Tak
Usuwanie usługi Nie

Metody

Typ zmiany Zgodność wsteczna
Dodaj nową metodę Tak
Usuwanie formy Nie
Zmienianie typu żądania lub odpowiedzi metody Nie

Obiekty

Typ zmiany Zgodność wsteczna
Dodawanie wymaganego pola Nie
Dodawanie pola opcjonalnego Tak
Przenoszenie pola do podwiadomości lub z niego Nie
Zmiana pola z wymaganego na opcjonalne Tak
Zmień wartość pola z opcjonalnego na wymagane Nie
Usuwanie stałego ograniczenia Tak
Dodaj stałe ograniczenie Nie

Wyliczenia

Typ zmiany Zgodność wsteczna
Dodawanie wartości typu wyliczeniowego Tak
Usuwanie wartości wyliczeniowej Nie

Zachowanie wycofanych pól

Pola zastępcze

W przypadku pól, które mają zastąpione wartości, oba pola zostaną wypełnione, jeśli to możliwe. Podczas aktualizacji możesz ustawić dowolne z tych pól. Podanie obu pól w prośbie o zaktualizowanie spowoduje błąd INVALID_ARGUMENT.

Rozważ ten schemat:

{
  // 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 odpowiednikami:

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

Prośby o aktualizację mogą zawierać dowolną z tych wartości. Uwzględnienie obu pól powoduje utworzenie INVALID_ARGUMENT błąd:

costMicros 

// Update payload
{
  "costMicros": 1500000
}

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

koszt 

// 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 przestarzałe i mogą zwracać semantycznie odpowiednią wartość domyślną. Aktualizacje można zignorować.

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