Операции над массивом объектов

На вход всех методов, изменяющих данные, подается массив объектов, для которых требуется выполнить операцию.

Элементам входного массива соответствуют элементы выходного массива, следующие в том же порядке. Каждый элемент входного массива содержит:

  • в случае успешного выполнения операции — идентификатор созданного/измененного/удаленного объекта;
  • в случае если операция выполнена с какими-либо особенностями — идентификатор объекта и массив Warnings;
  • в случае если операция не выполнена вследствие ошибки — массив Errors (и, возможно, массив Warnings); идентификатор объекта не возвращается.

Ошибка при выполнении операции с одним из объектов не влияет на успешность выполнения операции с остальными объектами. Исключение: отсутствие обязательного параметра для одного из объектов приравнивается к неверному формату запроса и вызывает ошибку обработки всего запроса (а не выполнения отдельной операции).

Массивы Errors и Warnings содержат одну или несколько структур ExceptionNotification:

Параметр Тип Описание
Структура ExceptionNotification
Code int Числовой код ошибки или предупреждения.
Message string Текст сообщения об ошибке или предупреждения.
Details string Подробное описание ошибки или предупреждения.

Коды и описания ошибок и предупреждений перечислены в разделе Ошибки и предупреждения.

Как обрабатывать ошибки

  • Наличие массива ошибок Errors в ответе означает, что операция не выполнена.

  • Приложение не должно пытаться повторить операцию, которая завершилась ошибкой.

  • Приложение должно протоколировать ошибки. Рекомендуется также отправлять ошибки на почту или в систему мониторинга.

  • Необходимо анализировать ошибки и вносить изменения в приложение, чтобы предотвратить повторение ошибок.

Обратите внимание, что за ошибку выполнения операции списывается увеличенное количество баллов по сравнению с успешной операцией.

Пример ошибки

Во входном массиве два объявления, которые требуется добавить. Первая операция добавления выполнена успешно, возвращен идентификатор объявления. Вторая операция завершилась ошибкой.

Запрос
{
  "method": "add",
  "params": {
    "Ads": [{ 
      "AdGroupId": 1234567,
      "TextAd": {
        "Text": "Слоны всех пород. Сертифицированный питoмник",
        "Title": "Купи слона!",
        "Href": "http://exotic-farm.com/elefants",
        "Mobile": "NO"
      }
    },
    { 
      "AdGroupId": 1234567,
      "TextAd": {
        "Text": "Носороги с доставкой. Весенняя распродажа",
        "Title": "Купи носорога!",
        "Mobile": "NO"
      }
    }]
  }
} 
Ответ
{
  "result": {
    "AddResults": [{
      "Id": 7654321
    },
    {
      "Errors": [{
        "Code": 6000,
        "Message": "Неконсистентное состояние объекта",
        "Details": "В объявлении должна быть указана или визитка или основная ссылка"
      }]
    }]
  }
}

Как обрабатывать предупреждения

  • Наличие массива предупреждений Warnings и идентификатора объекта в ответе означает, что операция выполнена успешно. Приложение может продолжать работу.

  • Приложение должно протоколировать предупреждения. Рекомендуется также отправлять предупреждения на почту или в систему мониторинга.

  • Необходимо анализировать предупреждения и вносить изменения в приложение, чтобы предотвратить повторение предупреждений.

Пример предупреждения

Во входном массиве два объявления, которые требуется остановить. Для первой операции остановки выдано предупреждение, поскольку объявление уже было остановлено ранее.

Запрос
{
  "method": "suspend",
  "params": { 
    "SelectionCriteria": {
      "Ids": [7654300, 7654321]
    }
  } 
}
Ответ
{
  "result": {
    "SuspendResults": [{
      "Id": 7654300,
      "Warnings": [{
        "Code": 10200,
        "Message": "Объявление уже остановлено"
      }]
    },
    {
      "Id": 7654321
    }]
  }
}

Дубликаты id

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

Если в одном вызове метода suspend, resume, moderate, archive, unarchive содержится несколько объектов с одинаковым идентификатором, операция выполняется, но для повторяющихся идентификаторов возвращается предупреждение.