Obsługa wersji

Interfejs API REST Ad Managera ma zarówno wersje główne, zgodne wstecznie wersje lokalne do bieżącej wersji głównej.

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

Wersja główna to wersja niekompatybilna wstecznie Zmiany interfejsu API. Te wersje będą miały nazwy i będą mieć różne punkty końcowe interfejsu API. Poprzednie wersje główne są obsługiwane w okresie migracji.

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

Wersje lokalne

Publikowane są zgodne wstecznie zmiany, w tym nowe funkcje i poprawki błędów w bieżącej wersji Major API. Klienty muszą obsługiwać nieznane pola w odpowiedziach interfejsu API.

Zgodność wsteczna

Zgodność wsteczna jest zachowywana w przypadku zmian w 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. Inaczej mówiąc, dane wejściowe są nie tylko i danych wyjściowych, ale oczekiwania związane z serializacją i deserializacją kontynuuj.

  3. Zgodność semantyczna: kod napisany w porównaniu z poprzednią wersją jest kontynuowany i otrzymać to, czego oczekują najbardziej rozsądni deweloperzy.

W tabelach poniżej znajdziesz listę typów zmian interfejsu API oraz tego, czy są one brane pod uwagę zgodne wstecznie.

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 metody Nie
Zmienianie typu żądania lub odpowiedzi metody Nie

Obiekty

Typ zmiany Zgodność wsteczna
Dodaj pole wymagane Nie
Dodaj pole opcjonalne Tak
Przenoszenie pola do podwiadomości lub z niego Nie
Zmień wartość 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
Dodaj wartość wyliczeniową Tak
Usuwanie wartości wyliczeniowej Nie

Wycofane działanie pól

Pola zastępcze

W przypadku pól, które zawierają elementy zastępujące, w miarę możliwości oba pola zostaną wypełnione. Podczas aktualizowania można ustawić dowolne z tych pól. Uwzględnienie obu pól w aktualizacji zwraca błąd INVALID_ARGUMENT.

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

Żądania aktualizacji mogą ustawiać obie 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."
          }
        ]
      }
    ]
  }
}

Wycofane funkcje

Jeśli funkcja produktu zostanie wycofana, odpowiednie pola będą oznaczone jako został wycofany i może zwrócić odpowiednią semantycznie 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,
}