Справочный центр Wialon

search_items

Функция search_items используется для поиска элементов по определенным свойствам.

Copied!
svc = core/search_items
params = {
  "spec": {
    "itemsType": "<text>",
    "propName": "<text>",
    "propValueMask": "<text>",
    "sortType": "<text>",
    "propType": "<text>",
    "or_logic": <bool>
  },
  "force": <uint>,
  "flags": <long>,
  "from": <uint>,
  "to": <uint>
}

Параметры

Название Описание
spec Условия поиска.
itemsType Тип элементов (см. список ниже).
propName Имя свойства, по значению которого будет поиск (см. список возможных свойств ниже). Можно использовать символ |.
propValueMask Маска значения свойства. Можно использовать следующие символы: * | , > < =.
sortType Имя свойства, используемого для сортировки.
propType Тип свойства (см. список ниже).
or_logic Флаг логики ИЛИ для параметра propName (см. Поиск по нескольким свойствам).
force В зависимости от значения:
  • 0 — если такой поиск уже был, вернуть результат;
  • 1 — выполнить новый поиск.
flags Флаги со свойствами для возвращаемого результата. Значение этого параметра зависит от типа элемента. Форматы данных всех типов элементов и их флаги описаны в разделе format.
from Индекс первого возвращаемого элемента. Для нового поиска укажите 0.
to Индекс последнего возвращаемого элемента. Если указано 0, возвращаются все элементы, начиная с индекса, указанного в параметре from.

Типы элементов

Типы элементов (параметр itemsType):

  • avl_hw — тип оборудования;
  • avl_resource — ресурс;
  • avl_retranslator — ретранслятор;
  • avl_unit — объект;
  • avl_unit_group — группа объектов;
  • user — пользователь;
  • avl_route — маршрут.

Свойства элементов

Свойства элементов (параметры propName и sortType):

  • sys_name — имя элемента;
  • sys_id — ID элемента;
  • sys_unique_id — уникальный ID объекта (IMEI);
  • sys_phone_number — телефонный номер объекта;
  • sys_phone_number2 — второй телефонный номер объекта;
  • sys_user_creator — ID создателя;
  • rel_user_creator_name — имя создателя;
  • sys_billing_account_guid — ID учетной записи;
  • rel_billing_account_name — имя учетной записи;
  • rel_billing_parent_account_name — имя родительской учётной записи;
  • rel_billing_plan_name — имя тарифного плана;
  • sys_comm_state — состояние оборудования (1 — подключено, 0 — отключено);
  • rel_hw_type_name — имя оборудования;
  • rel_hw_type_id — ID оборудования;
  • sys_account_balance — баланс учётной записи;
  • sys_account_days — количество дней для учётной записи;
  • sys_account_enable_parent — права дилера (1 — есть, 0 — нет);
  • sys_account_disabled — учетная запись заблокирована (1 — да, 0 — нет);
  • rel_account_disabled_mod_time — время последнего изменения свойства sys_account_disabled, время UNIX;
  • rel_account_units_usage — количество объектов в учетной записи;
  • rel_last_msg_date — время последнего сообщения, время UNIX;
  • rel_is_account — является ли ресурс учетной записью (1 — да, 0 — нет);
  • login_date — время последнего входа в систему, время UNIX;
  • retranslator_enabled — состояние ретранслятора ( 1 — запущен, 0 — остановлен);
  • rel_creation_time — время создания;
  • rel_group_unit_count — количество объектов в группе;
  • rel_customfield_name — имя произвольного поля объекта;
  • rel_customfield_value — значение произвольного поля объекта;
  • rel_profilefield_name — имя характеристики объекта;
  • rel_profilefield_value — значение поля характеристики объекта;
  • rel_adminfield_name — имя административного поля объекта;
  • rel_adminfield_value — значение административного поля объекта;
  • rel_customfield_name — имя и значение произвольного поля объекта, разделены “:”;
  • rel_profilefield_name — имя и значение поля характеристики объекта, разделены “:”;
  • rel_adminfield_name — имя и значение административного поля объекта, разделены “:”.

Другие значения этого параметра описаны в таблице ниже.

Тип свойства

Типы свойств (параметр propType):

  • property — свойство;

  • list — список;

  • propitemname — имя подэлемента (например, геозона является подэлементом ресурса);

  • creatortree — цепочка создателей (в результате поиска такого типа возвращается список элементов, в цепочке создателей которых есть пользователь, указанный в параметре propValueMask);

  • accounttree — цепочка учетных записей (в результате поиска такого типа возвращается список элементов, в цепочке учетных записей которых есть учетная запись, указанная в параметре propValueMask);

  • customfield — произвольные поля;

  • profilefield — характеристики объекта;

  • adminfield — административные поля;

  • servicename — услуги.

Подэлементы

Для поиска подэлементов укажите значение propitemname в параметре propType. Другие параметры могут иметь следующие значения:

Элемент (параметр "itemsType")Подэлемент (параметры "propName" и "sortType")Описание
avl_unitunit_sensorsДатчики.
unit_commandsКоманды.
service_intervalsИнтервалы техобслуживания.
avl_resourcedriversВодители
driver_groupsГруппы водителей.
jobsЗадания.
notificationsУведомления.
trailersПрицепы.
trailer_groupsГруппы прицепов.
zones_libraryГеозоны.
reporttemplatesШаблоны отчетов.
ordersЗаявки.
avl_routeroundsРейсы.
route_schedulesРасписания.
avl_retranslatorretranslator_unitsРетранслируемые объекты.

avl_unit

user

avl_resource

custom_fieldsПроизвольные поля.
admin_fieldsАдминистративные поля.

Типы сортировки 

По умолчанию прямая сортировка работает следующим образом:

  • любое имя разбивается на составляющие для сортировки (символы и числа);
  • сначала сортируются числа, а затем символы;
  • символ “-” считается дефисом и сортируется до символов и чисел (см. специальную сортировку);
  • в системе поддерживается сортировка чисел с точкой (3.12) и чисел с плавающей точкой (2e10; 5.1E-2).

Доступны следующие типа сортировки:

СортировкаОписание
Прямая

Возвращаются значения, отсортированные по возрастанию:

"sortType":"<item_property>"
Обратная

Возвращаются значения, отсортированные по убыванию:

"sortType":"!<item_property>"
Комбинированная

Возвращаются значения, отсортированные по первому свойству, а в случае равенства значений — по второму свойству и т. д.:

"sortType":"<property1>,!<property2>"

Специальная

Согласно этому типу сортировки символ "-" считается обозначением отрицательного числа. По умолчанию символ "-" считается дефисом, а не минусом.

"sortType":"-<item_property>"

Поиск по нескольким свойствам

Можно искать элементы по нескольким свойствам сразу. Например:

Copied!
"itemsType":"avl_resource",
"propName":"rel_is_account,*",
"propValueMask":"1,qwe",
"sortType":"sys_name",
"propType":"property,customfield"

Количество свойств в параметрах propName, propType и propValueMask должно быть одинаковым, поскольку они учитываются вместе.

По умолчанию для параметра propName работает логика И. Это значит, что в результате поиска будут перечислены все учетные записи (rel_is_account:1), имена которых начинаются с “foo” (sys_name:"foo\*").

Чтобы включить логику ИЛИ для параметра propName, укажите ''or_logic'':1 в запросе.

Использование операторов сравнения в поиске

В параметре propValueMask можно использовать следующие операторы сравнения: <, >, =, >=, <=. Если поле для поиска строковое, то будет поиск чисел только в начале значения. Если поле числовое, анализируется все значение.

Пример 1:

Copied!
"itemsType": "avl_unit",
"propName": "sys_name,sys_name",
"propValueMask": ">=32,<33.5"

В результате поиска будут перечислены все объекты, имена которых начинаются с чисел в диапазоне от 32 до 33.5.

Пример 2:

Copied!
"itemsType": "avl_resource",
"propName": "sys_account_balance,sys_account_balance",
"propValueMask": ">2,<=23"

В результате поиска будут перечислены все ресурсы и учетные записи, баланс которых больше 2, но меньше или равен 23.

Вы также можете использовать оператор “=”, если значение поля начинается с “>” или “<”.

Пример 3:

Copied!
"itemsType":"avl_unit",
"propName":"sys_name",
"propValueMask":"=>123<,=<123>"

В результате поиска будут перечислены все доступные объекты с именами >123< и <123>.

Возвращаемый результат

Copied!
{
  "searchSpec": {                        /* условия поиска */
    "itemsType": "<text>",              /* тип элементов */
    "propName": "<text>",               /* имя свойства */
    "propValueMask": "<text>",          /* маска значения свойства */
    "sortType": "<text>",               /* имя свойства для сортировки */
    "propType": "<text>"                /* тип свойства */
  },
  "dataFlags": <uint>,                  /* примененные флаги со свойствами */
  "totalItemsCount": <uint>,            /* количество найденных элементов */
  "indexFrom": <uint>,                  /* начальный индекс */
  "indexTo": <uint>,                    /* конечный индекс */
  "items": [
    { ... }                             /* найденные элементы */
  ]
}

Формат массива items зависит от типа элемента. Все форматы описаны в разделе format.

Коды ошибок:

Код Описание
4 Неверные входные параметры.

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

Сообщить об ошибке

Ваше сообщение отправлено. Спасибо!

Произошла ошибка при отправке формы

Скачать файл PDF
Скачать документ Word

Смотрите также

  • delete_item Руководство пользователя
  • list_backups Руководство пользователя
  • read Руководство пользователя