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

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

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

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

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

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

Параметр Тип Описание
Структура ExceptionNotification
Code int Числовой код ошибки или предупреждения.
Message string Текст сообщения об ошибке или предупреждения.
Details string Подробное описание ошибки или предупреждения.
Параметр Тип Описание
Структура 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 содержится несколько объектов с одинаковым идентификатором, операция выполняется, но для повторяющихся идентификаторов возвращается предупреждение.