search_items
Функция search_items
используется для поиска элементов по определенным свойствам.
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 | В зависимости от значения:
|
flags | Флаги со свойствами для возвращаемого результата. Значение этого параметра зависит от типа элемента. Форматы данных всех типов элементов и их флаги описаны в разделе Формат данных. |
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_unit |
unit_sensors |
Датчики. |
avl_unit |
unit_commands |
Команды. |
avl_unit |
service_intervals |
Интервалы техобслуживания. |
avl_resource |
drivers |
Водители |
avl_resource |
driver_groups |
Группы водителей. |
avl_resource |
jobs |
Задания. |
avl_resource |
notifications |
Уведомления. |
avl_resource |
trailers |
Прицепы. |
avl_resource |
trailer_groups |
Группы прицепов. |
avl_resource |
zones_library |
Геозоны. |
avl_resource |
reporttemplates |
Шаблоны отчетов. |
avl_resource |
orders |
Заявки. |
avl_route |
rounds |
Рейсы. |
avl_route |
route_schedules |
Расписания. |
avl_retranslator |
retranslator_units |
Ретранслируемые объекты. |
avl_unit user avl_resource |
custom_fields |
Произвольные поля. |
avl_unit user avl_resource |
admin_fields |
Административные поля. |
Типы сортировки
По умолчанию прямая сортировка работает следующим образом:
- любое имя разбивается на составляющие для сортировки (символы и числа);
- сначала сортируются числа, а затем символы;
- символ
-
считается дефисом и сортируется до символов и чисел (см. специальную сортировку); - в системе поддерживается сортировка чисел с точкой (3.12) и чисел с плавающей точкой (2e10; 5.1E-2).
Доступны следующие типа сортировки:
Сортировка | Описание |
---|---|
Прямая | Возвращаются значения, отсортированные по возрастанию:"sortType":"<item_property>" |
Обратная | Возвращаются значения, отсортированные по убыванию:"sortType":"!<item_property>" |
Комбинированная | Возвращаются значения, отсортированные по первому свойству, а в случае равенства значений — по второму свойству и т. д.:"sortType":"<property1>,!<property2>" |
Специальная | Согласно этому типу сортировки символ - считается обозначением отрицательного числа. По умолчанию символ “-” считается дефисом, а не минусом."sortType":"-<item_property>" |
Поиск по нескольким свойствам
Можно искать элементы по нескольким свойствам сразу. Например:
"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
"itemsType": "avl_unit",
"propName": "sys_name,sys_name",
"propValueMask": ">=32,<33.5"
В результате поиска будут перечислены все объекты, имена которых начинаются с чисел в диапазоне от 32 до 33.5.
Пример 2
"itemsType": "avl_resource",
"propName": "sys_account_balance,sys_account_balance",
"propValueMask": ">2,<=23"
В результате поиска будут перечислены все ресурсы и учетные записи, баланс которых больше 2, но меньше или равен 23.
Вы также можете использовать оператор =
, если значение поля начинается с >
или <
.
Пример 3
"itemsType":"avl_unit",
"propName":"sys_name",
"propValueMask":"=>123<,=<123>"
В результате поиска будут перечислены все доступные объекты с именами >123<
и <123>
.
Возвращаемый результат
{
"searchSpec": { /* условия поиска */
"itemsType": "<text>", /* тип элементов */
"propName": "<text>", /* имя свойства */
"propValueMask": "<text>", /* маска значения */
"sortType": "<text>", /* свойство для сортировки */
"propType": "<text>" /* тип свойства */
},
"dataFlags": <uint>, /* примененные флаги */
"totalItemsCount": <uint>, /* количество найденных элементов */
"indexFrom": <uint>, /* начальный индекс */
"indexTo": <uint>, /* конечный индекс */
"items": [
{ ... } /* найденные элементы */
]
}
Формат массива items
зависит от типа элемента. Все форматы описаны в разделе Формат данных.
Коды ошибок:
Код | Описание |
---|---|
4 | Неверные входные параметры. |