search_items

La función search_items se usa para encontrar objetos por propiedades determinadas.

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>
}

La solicitud no comprueba si existen los valores de itemsType, propName, propType y sortType. Un valor desconocido no provoca ningún error. Por ejemplo, si itemsType contiene un tipo de objeto desconocido o ningún objeto encontrado tiene la propiedad especificada en propName, la matriz items está vacía. Un valor desconocido de propType se procesa como property.

Los valores de los flags dependen del tipo de objeto. Los valores hasta 0x80 coinciden en la mayoría de los tipos, pero a partir de 0x100 un mismo número selecciona datos diferentes. Por ejemplo, 0x100 (256) devuelve las propiedades avanzadas para avl_unit y los conductores para avl_resource. Un flag que no corresponde al tipo solicitado se ignora sin error y la respuesta simplemente omite esos datos.

Tipos de objetos (parámetro itemsType):

• avl_resource: recurso;
• avl_retranslator: repetidor;
• avl_unit: unidad;
• avl_unit_group: grupo de unidades;
• user: usuario;
• avl_route: ruta.

Para obtener la lista de tipos de dispositivos, use core/get_hw_types.

Propiedades de objetos (parámetros propName y sortType):

• sys_name: nombre del objeto;
• sys_id: ID del objeto;
• sys_unique_id: ID único de la unidad (IMEI);
• sys_phone_number: número de teléfono de la unidad;
• sys_phone_number2: segundo número de teléfono de la unidad;
• sys_user_creator: ID del creador;
• rel_user_creator_name: nombre del creador;
• sys_billing_account_guid: ID de la cuenta;
• rel_billing_account_name: nombre de la cuenta;
• rel_billing_parent_account_name: nombre de la cuenta padre;
• rel_billing_plan_name: nombre del plan de facturación;
• sys_comm_state: estado del dispositivo (1: activado, 0: desactivado);
• rel_hw_type_name: nombre del dispositivo;
• rel_hw_type_id: ID del dispositivo;
• sys_account_balance: saldo de la cuenta;
• sys_account_days: días para la cuenta;
• sys_account_enable_parent: derechos de distribuidor (1: sí, 0: no);
• sys_account_disabled: cuenta bloqueada (1: sí, 0: no);
• rel_account_disabled_mod_time: hora de la última modificación de la propiedad sys_account_disabled, tiempo UNIX;
• rel_account_units_usage: cantidad de unidades en la cuenta;
• rel_last_msg_date: hora del último mensaje, tiempo UNIX;
• rel_is_account: si el recurso es una cuenta (1: sí, 0: no);
• login_date: última hora de inicio de sesión, tiempo UNIX;
• retranslator_enabled: estado del repetidor (1: iniciado, 0: parado);
• rel_creation_time: hora de creación;
• rel_group_unit_count: cantidad de unidades en el grupo;
• rel_customfield_name: nombre del campo personalizado del objeto;
• rel_customfield_value: valor del campo personalizado del objeto;
• rel_profilefield_name: nombre del campo de perfil de la unidad;
• rel_profilefield_value: valor del campo de perfil de la unidad;
• rel_adminfield_name: nombre del campo administrativo del objeto;
• rel_adminfield_value: valor del campo administrativo del objeto;
• rel_customfield_name_value: nombre y valor del campo personalizado del objeto, separados por :;
• rel_profilefield_name_value: nombre y valor del campo de perfil de la unidad, separados por :;
• rel_adminfield_name_value: nombre y valor del campo administrativo del objeto, separados por :.

Los campos personalizados y administrativos están disponibles para unidades, grupos de unidades, usuarios y recursos. Los campos de perfil solo están disponibles para unidades.

Otros valores de este parámetro se describen en la tabla a continuación.

Tipos de propiedades (parámetro propType):

• property: propiedad;
• list: lista;
• propitemname: nombre del objeto subordinado (por ejemplo, la geocerca es un objeto subordinado del recurso);
• creatortree: cadena de creadores (la búsqueda de este tipo devuelve la lista de objetos cuya cadena de creadores contiene el usuario especificado en el parámetro propValueMask);
• accounttree: cadena de cuentas (la búsqueda de este tipo devuelve la lista de objetos cuya cadena de cuentas contiene la cuenta especificada en el parámetro propValueMask);
• customfield: campos personalizados;
• profilefield: perfil de la unidad;
• adminfield: campos administrativos;
• servicename: servicios.

Si el parámetro propType no está especificado o tiene un valor desconocido, se usa property.

Si desea buscar objetos subordinados, establezca el valor propitemname para el parámetro propType. Los otros parámetros pueden tener los siguientes valores:

Por defecto, la ordenación directa funciona de la siguiente manera:

• cualquier nombre se divide en componentes para ordenación (caracteres y números);
• primero se ordenan los números y luego los caracteres;
• el carácter - se considera un guion y se ordena antes de números (vea la ordenación especial);
• el sistema admite la ordenación de números de punto (3.12) y números de punto flotante (2e10; 5.1E-2).

Están disponibles los siguientes tipos de ordenación:

Puede buscar objetos por varias propiedades a la vez. Por ejemplo:

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

La cantidad de propiedades en los parámetros propName, propType y propValueMask debe ser la misma, dado que se toman en cuenta juntos. El sistema no lo comprueba: si las cantidades son diferentes, no se devuelve ningún error, pero el resultado de la búsqueda puede ser diferente del esperado.

Por defecto, el parámetro propName funciona con la lógica Y. En el ejemplo anterior, el sistema encuentra todas las cuentas (rel_is_account es 1) que tienen un campo personalizado con el nombre o el valor qwe.

Para activar la lógica O para el parámetro propName, especifique "or_logic":1 en la solicitud.

En el parámetro propValueMask, puede usar los siguientes operadores de comparación: <, >, =, >=, <=. Si el campo de búsqueda es una cadena, solo se buscan números al principio del valor. Si el campo es numérico, se analiza todo el valor.

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

El resultado de la búsqueda muestra una lista de todos los objetos cuyos nombres comienzan con números entre 32 y 33.5.

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

El resultado de la búsqueda muestra una lista de todos los recursos y cuentas cuyo saldo es mayor que 2, pero menor o igual a 23.

También puede usar el operador = si el valor del campo comienza con > o <.

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

La búsqueda muestra una lista de todos los objetos disponibles con los nombres >123< y <123>.

{
  "searchSpec": {              /* condiciones de búsqueda */
    "itemsType": "<text>",     /* tipo de objetos */
    "propName": "<text>",      /* nombre de propiedad */
    "propValueMask": "<text>", /* máscara de valor de propiedad */
    "sortType": "<text>",      /* nombre de propiedad para ordenación */
    "propType": "<text>",      /* tipo de propiedad */
    "or_logic": "<text>"       /* flag de la lógica O: "0" o "1" */
  },
  "dataFlags": <uint>,         /* flags aplicados con propiedades */
  "totalItemsCount": <uint>,   /* cantidad de objetos encontrados */
  "indexFrom": <uint>,         /* índice inicial */
  "indexTo": <uint>,           /* índice final */
  "items": [ { ... } ]         /* objetos encontrados */
}

El valor indexTo es el valor to de la solicitud, limitado al índice del último objeto encontrado. Si en la solicitud to es 0 o no se encuentra ningún objeto, indexTo es 0.

El formato de la matriz items depende del tipo del objeto. Todos los formatos se describen en la sección Formato de datos.

Los códigos de errores posibles son: