Справочный центр Wialon
Wialon для разработчиков Руководство пользователя Документация API core batch

batch

Для выполнения нескольких методов в одном запросе используйте метод core/batch.

Конечная точка

Запрос можно отправить в одной из двух форм. В первой форме параметр params содержит массив методов:

Copied!
svc=core/batch&params=[
  {
    "svc": "<text>",
    "params": {}
  }
]

Во второй форме параметр params содержит объект, что также позволяет использовать параметр flags:

Copied!
svc=core/batch&params={
  "params": [{
    "svc": "<text>",
    "params": {}
  }],
  "flags": <uint>
}

Параметры

Параметры svc и params указываются для каждого метода массива. Параметр flags указывается для запроса в целом.

Название Описание
svc Название метода, который нужно выполнить, например core/search_items.
params Параметры метода.
flags Битовая маска, которая может включать следующие флаги:
  • 0x01 (1) — остановить выполнение запроса, если один из методов возвращает ошибку;
  • 0x02 (2) — применить ограничения на количество методов и размер ответа. Подробнее см. в разделе Ограничения. В Wialon Local этот флаг недоступен.
Укажите 0, чтобы выполнить все методы без этих ограничений. Параметр доступен только во второй форме запроса. Если не указать его в этой форме, запрос вернет ошибку 4.

Ответ

Если запрос выполнен успешно, результат возвращается в следующем формате:

Copied!
[
  { /* Объект с данными, если ошибок нет. */
    ...
  },
  { /* Код ошибки, если произошла ошибка. */
    "error": <int>
  },
  ...
]

Каждый элемент массива — это результат соответствующего метода без дополнительной обертки. Если метод возвращает ошибку, его элемент содержит код ошибки этого метода.

Если параметр flags включает флаг 0x01 (1) и один из методов возвращает ошибку, все следующие за ним методы возвращают код ошибки 10.

Ограничения

Если параметр flags включает флаг 0x02 (2), к запросу применяются следующие ограничения. В таблице указаны значения по умолчанию; на сервере могут использоваться другие значения.

Ограничение Значение по умолчанию Результат при превышении ограничения
Количество методов в запросе 100 Методы не выполняются, и запрос возвращает ошибку 4.
Размер результата одного метода 1 МБ Элемент этого метода содержит {"error":6,"reason":"BATCH_SINGLE_RESPONSE_TOO_LARGE"}.
Размер всего ответа 10 МБ Элемент метода, результат которого превышает ограничение, содержит {"error":6,"reason":"BATCH_RESPONSE_TOO_LARGE"}.

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

Коды ошибок

Сам запрос может вернуть следующие коды ошибок:

Код Описание
4 Неверные входные параметры. Это происходит в одном из следующих случаев:
  • запрос не соответствует ни одной из двух форм, например во второй форме не указан параметр flags. В этом случае в ответе нет поля reason;
  • один из элементов массива не является корректным методом. В этом случае поле reason содержит BATCH_INVALID_INTERNAL_REQUEST index=<i>, где <i> — это позиция данного элемента в массиве, начиная с 0;
  • параметр flags включает флаг 0x02 (2), и запрос содержит больше методов, чем разрешено. В этом случае поле reason содержит BATCH_MAX_INTERNAL_REQUESTS_EXCEEDED count=<n> max=<max>, где <n> — это количество методов в запросе, а <max> — ограничение.
6 Возвращаемый результат слишком большой. Это происходит в одном из следующих случаев:
  • параметр flags не включает флаг 0x02 (2), и ответ не может быть сформирован из-за своего размера. В этом случае поле reason содержит Large response;
  • параметр flags включает флаг 0x02 (2), и сформированный ответ превышает ограничение на размер всего ответа. В этом случае поле reason содержит BATCH_RESPONSE_TOO_LARGE size=<size> max=<max>, где <size> — это размер ответа в байтах, а <max> — ограничение.

Отдельный метод может вернуть собственный код ошибки в своем элементе массива. Кроме кодов самого метода, возможны следующие коды:

Код Описание
2 Неверное название метода в параметре svc.
6 Результат слишком большой. Этот код возможен, только если параметр flags включает флаг 0x02 (2). Подробнее см. в разделе Ограничения.
10 Метод не выполнен. Это происходит в одном из следующих случаев:
  • один из предыдущих методов вернул ошибку, и параметр flags включает флаг 0x01 (1);
  • запрос превысил ограничение по времени, установленное на сервере.

Примеры

Во всех примерах ниже отправляются одни и те же два метода: первый обращается к элементу с ID 1004, к которому у пользователя нет прав доступа, а второй получает свойства ресурса с ID 1003. Добавьте в каждый запрос параметр sid с идентификатором вашей сессии.

Выполнение всех методов несмотря на ошибку

В первой форме параметр params содержит только массив методов, поэтому параметр flags указать негде. Выполняются все методы.

Copied!
svc=core/batch&params=[
  {
    "svc": "core/search_item",
    "params": {
      "id": 1004,
      "flags": 1
    }
  },
  {
    "svc": "core/search_item",
    "params": {
      "id": 1003,
      "flags": 1
    }
  }
]

Вторая форма дает тот же результат, если значение параметра flags равно 0.

Copied!
svc=core/batch&params={
  "params": [
    {
      "svc": "core/search_item",
      "params": {
        "id": 1004,
        "flags": 1
      }
    },
    {
      "svc": "core/search_item",
      "params": {
        "id": 1003,
        "flags": 1
      }
    }
  ],
  "flags": 0
}

Ответ:

Copied!
[
  {
    "error": 7
  },
  {
    "item": {
      "nm": "Resource",
      "cls": 3,
      "id": 1003,
      "mu": 0,
      "uacl": 19826928009763
    },
    "flags": 1
  }
]

Ошибка первого метода не влияет на второй.

Остановка запроса после первой ошибки

Чтобы остановить выполнение после первой ошибки, используйте вторую форму запроса и укажите флаг 0x01 (1). Методы те же, но теперь второй из них не выполняется и возвращает ошибку 10.

Copied!
svc=core/batch&params={
  "params": [
    {
      "svc": "core/search_item",
      "params": {
        "id": 1004,
        "flags": 1
      }
    },
    {
      "svc": "core/search_item",
      "params": {
        "id": 1003,
        "flags": 1
      }
    }
  ],
  "flags": 1
}

Ответ:

Copied!
[
  {
    "error": 7
  },
  {
    "error": 10
  }
]

Если вы заметили ошибку в тексте, пожалуйста, выделите её и нажмите Ctrl+Enter.