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

API Ad Manager поддерживает как именованные основные версии, так и обратно совместимые версии, сохраняющие текущую основную версию.

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

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

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

API Ad Manager не имеет регулярного графика выпуска основных версий. Новые основные версии будут выпускаться только по мере необходимости.

Выпуски на месте

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

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

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

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

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

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

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

Услуги

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

Методы

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

Объекты

Тип изменения Обратная совместимость
Добавьте обязательное поле Нет
Добавить необязательное поле Да
Перемещение поля в подсообщение или из него. Нет
Изменить значение поля с обязательного на необязательное. Да
Change a field from optional to required Нет
Удалите неизменяемое ограничение Да
Добавить неизменяемое ограничение Нет

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

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

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

Заменяющие поля

Для полей, для которых предусмотрена замена, оба поля будут заполнены, если это возможно. При обновлении можно установить значение в любом из полей. Включение обоих полей в запрос на обновление приводит к ошибке 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 :

costMicros 

// 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,
}