search_items

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

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

Запрос не проверяет, существуют ли значения itemsType, propName, propType и sortType. Неизвестное значение не вызывает ошибку. Например, если itemsType содержит неизвестный тип элемента или ни у одного найденного элемента нет свойства, указанного в propName, массив items пустой. Неизвестное значение propType обрабатывается как property.

Значения флагов зависят от типа элемента. Значения до 0x80 у большинства типов совпадают, но начиная с 0x100 одно и то же число выбирает разные данные. Например, 0x100 (256) для avl_unit возвращает расширенные свойства, а для avl_resource — водителей. Флаг, который не относится к запрошенному типу, игнорируется без ошибки, и в ответе просто не будет соответствующих данных.

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

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

Чтобы получить список типов оборудования, используйте core/get_hw_types.

Свойства элементов (параметры 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_value — имя и значение произвольного поля элемента, разделены :;
• rel_profilefield_name_value — имя и значение поля характеристики объекта, разделены :;
• rel_adminfield_name_value — имя и значение административного поля элемента, разделены :.

Произвольные и административные поля есть у объектов, групп объектов, пользователей и ресурсов. Характеристики есть только у объектов.

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

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

• property — свойство;
• list — список;
• propitemname — имя подэлемента (например, геозона является подэлементом ресурса);
• creatortree — цепочка создателей (в результате поиска такого типа возвращается список элементов, в цепочке создателей которых есть пользователь, указанный в параметре propValueMask);
• accounttree — цепочка учетных записей (в результате поиска такого типа возвращается список элементов, в цепочке учетных записей которых есть учетная запись, указанная в параметре propValueMask);
• customfield — произвольные поля;
• profilefield — характеристики объекта;
• adminfield — административные поля;
• servicename — услуги.

Если параметр propType не указан или имеет неизвестное значение, используется property.

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

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

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

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

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

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

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

По умолчанию для параметра propName работает логика И. В примере выше система находит все учетные записи (rel_is_account равно 1), у которых есть произвольное поле с именем или значением qwe.

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

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

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

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

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

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

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

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

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

{
  "searchSpec": {              /* условия поиска */
    "itemsType": "<text>",     /* тип элементов */
    "propName": "<text>",      /* имя свойства */
    "propValueMask": "<text>", /* маска значения */
    "sortType": "<text>",      /* свойство для сортировки */
    "propType": "<text>",      /* тип свойства */
    "or_logic": "<text>"       /* флаг логики ИЛИ: "0" или "1" */
  },

  "dataFlags": <uint>,         /* примененные флаги */
  "totalItemsCount": <uint>,   /* количество найденных элементов */
  "indexFrom": <uint>,         /* начальный индекс */
  "indexTo": <uint>,           /* конечный индекс */

  "items": [
    { ... }                    /* найденные элементы */
  ]
}

Значение indexTo равно значению to из запроса, ограниченному индексом последнего найденного элемента. Если в запросе to равен 0 или ничего не найдено, indexTo равен 0.

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

Коды ошибок: