Управление версиями

В REST API Менеджера рекламы есть как именованные выпуски основной версии, так и выпуски, обратно совместимые с текущей основной версией.

Службы, методы и поля могут быть помечены как устаревшие в любой момент в основной версии (например, v1), однако они будут поддерживаться до тех пор, пока эта основная версия не будет прекращена.

Выпуски основных версий

Выпуск основной версии определяется как выпуск с обратно несовместимыми изменениями API. Эти выпуски будут называться и иметь разные конечные точки API. Предыдущие основные версии поддерживаются в течение периода миграции.

API REST Менеджера рекламы не имеет регулярной периодичности выпуска основных версий. Новые основные версии будут выпускаться только при необходимости.

Релизы на месте

Изменения обратной совместимости, включая новые функции и исправления ошибок, выпускаются прямо в текущей основной версии API. Клиенты должны обрабатывать неизвестные поля в ответах API.

Обратная совместимость

Обратная совместимость сохраняется для изменений в основной версии. Совместимость определяется как:

  1. Совместимость исходного кода: код, написанный для предыдущей версии, компилируется с более новой версией и успешно работает с более новой версией клиентской библиотеки.

  2. Совместимость по проводам: код, написанный для предыдущей версии, правильно взаимодействует с новым сервером. Другими словами, не только входные и выходные данные совместимы, но и ожидания сериализации и десериализации продолжают совпадать.

  3. Семантическая совместимость: код, написанный на основе предыдущей версии, продолжает получать то, что ожидают большинство разумных разработчиков.

В следующих таблицах перечислены типы изменений API и указано, считаются ли они обратно совместимыми.

Услуги

Тип изменения Обратная совместимость
Добавить новую услугу Да
Удалить услугу Нет

Методы

Тип изменения Обратная совместимость
Добавить новый метод Да
Удаление метода Нет
Изменение типа запроса или ответа метода Нет

Объекты

Тип изменения Обратная совместимость
Добавить обязательное поле Нет
Добавить необязательное поле Да
Перемещение поля в подсообщение или из него Нет
Изменение поля с обязательного на необязательное Да
Изменение поля с необязательного на обязательное Нет
Удалить неизменяемое ограничение Да
Добавьте неизменяемое ограничение Нет

Перечисления

Тип изменения Обратная совместимость
Добавить значение перечисления Да
Удаление значения перечисления Нет

Устаревшее поведение поля

Поля замены

Для полей, у которых есть замена, оба поля будут заполнены, если это возможно. При обновлении можно задать любое поле. Включение обоих полей в запрос на обновление приводит к ошибке INVALID_ARGUMENT .

Рассмотрим следующую схему:

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

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

Ответ на чтение заполняет оба поля эквивалентными значениями:

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

Запросы на обновление могут устанавливать любое значение. Включение обоих полей приводит к ошибке INVALID_ARGUMENT :

стоимостьМикросы 

// Update payload
{
  "costMicros": 1500000
}

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

расходы 

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

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

Оба 

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

Снятые с производства функции

Если функция продукта будет прекращена, соответствующие поля будут помечены как устаревшие и могут возвращать семантически подходящее значение по умолчанию. Обновления можно игнорировать.

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