Публичный Web API

При работе с API получения списка элементов приложения можно задавать условия поиска, по которым элементы будут фильтроваться.

Добавление фильтрации выполняется путем вставки конструкции filter.

Пример:

{
    "filter": {
    }
}

Есть три вида операций:

Табличная операция — позволяет формировать набор условий для фильтрации, в котором для каждого типа полей доступны свои преднастроенные варианты условий;
Операции условий — позволяют формировать отдельные условия, в которых для значений полей разных типов можно задавать различные критерии;
Логические операции — позволяют комбинировать, объединять, вкладывать, обращать условия.

Табличная операция

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

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

Добавление фильтра выполняется путем вставки конструкции tf:

{
    "filter": {
        "tf": {
            "title": "белый",
            "description":"цвет с кодом"
        }
    }
}

Строка

Для строковых полей указывается строка, для которой ожидается вхождение в поле элемента приложения. Регистр значения не имеет.

Пример:

{
    "filter": {
        "tf": {
            "__name": "Мой объект"
        }
    }
}

Число

Для числовых полей указывается промежуток, в который должно входить искомое значение.

Пример:

{
    "filter": {
        "tf": {
            "weight": {
                "min": 10,
                "max": 100
            }
        }
    }
}

Если необходимо найти точное число, то оба параметра выставляются равными искомому значению:

{
    "filter": {
        "tf": {
            "weight": {
                "min": 100,
                "max": 100
            }
        }
    }
}

Если необходимо найти значение больше или меньше определенного числа, то указывается один из параметров, а для второго выставляется null:

{
    "filter": {
        "tf": {
            "weight": {
                "min": 1,
                "max": null
            }
        }
    }
}

Дата/время

Для полей дат указывается промежуток. При этом следует учитывать, что:

Время указывается во временной зоне +00;
В случае если настройки поля менялись с даты на время или наоборот, то ранее внесенные данные могут не соответствовать ожидаемым для фильтра. Перед использованием фильтра в этом случае следует предварительно проанализировать хранимые данные.

Пример:

{
    "filter": {
        "tf": {
            "__createdAt": {
                "min": "2023-04-11T00:00:00Z",
                "max": "2023-04-12T00:00:00Z"
            }
        }
    }
}

Если необходимо найти дату раньше или позже заданной, то указывается один из параметров, а для второго выставляется null:

{
    "filter": {
        "tf": {
            "__createdAt": {
                "min": "2023-04-11T00:00:00Z",
                "max": null
            }
        }
    }
}

Не рекомендуется использовать вариант написания без указания времени. В зависимости от настроек системы и вариантов хранения данных результат поиска может отличаться.

Пример, как делать не стоит:

{
    "filter": {
        "tf": {
            "__createdAt": {
                "min": "2023-04-01",
                "max": "2023-04-17"
            }
        }
    }
}

Выбор «да/нет»

Для полей типа Выбор «да/нет» указывается значение true или false.

Пример:

{
    "filter": {
        "tf": {
            "opened": true
        }
    }
}

Номер телефона

Для полей типа Номер телефона указывается строка, для которой ожидается вхождение в поле элемента приложения. Наличие разделительных символов в телефонном номере значения не имеет.

Пример:

{
    "filter": {
        "tf": {
            "phone": "7-999-11"
        }
    }
}

Электронная почта

Для полей типа Электронная почта указывается строка, для которой ожидается вхождение в поле элемента приложения. Регистр значения не имеет.

Пример:

{
    "filter": {
        "tf": {
            "email": "admin@admin.com"
        }
    }
}

Ф.И.О.

Для полей типа Ф.И.О. указывается строка, для которой ожидается вхождение в имя, фамилию или отчество, указанные в элементе приложения. Регистр значения не имеет.

Пример:

{
    "filter": {
        "tf": {
            "fio": "иван"
        }
    }
}

Статус

Для поля типа Статус указывается массив с номерами статусов.

Пример:

{
    "filter": {
        "tf": {
            "__status": [2,3]
        }
    }
}

Пользователи

Для полей типа Пользователи указывается UUID искомого пользователя.

Пример:

{
    "filter": {
        "tf": {
            "user": "47cfc3d3-279d-441e-a245-a27adaac81e8"
        }
    }
}

Для множественного поля типа Пользователи также необходимо указать только одного искомого пользователя:

{
    "filter": {
        "tf": {
            "users": "47cfc3d3-279d-441e-a245-a27adaac81e8"
        }
    }
}

Приложение

Для поиска по полю типа Приложение необходимо указать UUID элемента приложения.

Пример:

{
    "filter": {
        "tf": {
            "myApp":  {
                "id":"7730e64b-551b-4eda-bb49-b0120e9712eb",
            }
        }
    }
}

Произвольное приложение

Для поиска по полю типа Произвольное приложение необходимо указать UUID элемента, код приложения и код раздела.

Пример:

{
    "filter": {
        "tf": {
            "myRandomApp":  {
                "id":"7730e64b-551b-4eda-bb49-b0120e9712eb",
                "code":"myApplication",
                "namespace":"myNamespace",
                "inTrash":false
            }
        }
    }
}

Категория

Для поиска по полю типа Категория необходимо указать код элемента перечисления.

Пример:

{
    "filter": {
        "tf": {
            "errStatus":"blocker"
        }
    }
}

Операции условий

Задаются двумя параметрами:

Наименование поля — задается конструкцией field;
Условие — для одинарного условия задается конструкцией const, для множественного — конструкцией list. Если в операции нужно задать условие, описывающее отсутствие, то указывается null.

Пример одинарного условия:

{
    "eq": [
        {"field": "weight"},
        {"const": 5}
    ]
}

Пример множественного условия:

{
    "in": [
        {"field": "values"},
        {"list": [1,4]}
    ]
}

Пример пустого условия:

{
    "eq": [
        {"field": "title"},
        null
    ]
}

Формат записи условия зависит от типа поля, по которому ведется фильтрация.

Форматы условий для типов данных

Строка

Для строковых полей указывается строка в кавычках.

Пример:

{
    "filter": {
        "eq": [
            {"field": "stringField"},
            {"const": "MyStringValue"}
        ]
    }
}

Число

Для числового типа данных условие указывается в виде числа.

Пример для целого числа:

{
    "filter": {
        "neq": [
            {"field": "intField"},
            {"const": 14}
        ]
    }
}

Пример для дробного числа:

{
    "filter": {
        "neq": [
            {"field": "floatField"},
            {"const": 12.05}
        ]
    }
}

Деньги

Для типа данных Деньги условие указывается в виде числа, представляющего собой значение в минимальных единицах измерения валюты. Так, например, для суммы 54 рубля 45 копеек значение в фильтре будет 5445.

Пример:

{
    "filter": {
        "neq": [
            {"field": "moneyField"},
            {"const": 5445}
        ]
    }
}

Дата/время

Для полей c датами или временем значение указывается в кавычках. При этом следует учитывать, что:

Время указывается во временной зоне +00;
В случае если настройки поля менялись с даты на время или наоборот, то ранее внесенные данные могут не соответствовать ожидаемым для фильтра. Перед использованием фильтра в этом случае следует предварительно проанализировать хранимые данные.

Пример:

{
    "filter": {
        "eq": [ 
            {"field": "dateTimeField"},
            {"const": "2023-04-17T04:54:39Z"}
        ]
    }
}

Выбор «да/нет»

Для полей Выбор «да/нет» значение в условии может быть true или false.

Пример:

{
    "filter": {
        "eq": [ 
            {"field": "boolField"},
            {"const": true}
        ]
    }
}

Номер телефона

Для полей типа Номер телефона указывается строка. Наличие разделительных символов в телефонном номере значения не имеет.

Пример:

{
    "filter": {
       "eq": [
            {"field": "phoneField"},
            { "const": "+71234566780"}
        ]
    }
}

Электронная почта

Для полей типа Электронная почта указывается строка.

Пример:

{
    "filter": {
        "eq": [ 
            {"field": "emailFiled"},
            {"const": "example@example.example"}
        ]
    }
}

Ф.И.О.

Для полей типа Ф.И.О. указывается строка. Данные в полях этого типа хранятся в особом формате, поэтому количество допустимых операций ограничено. Рекомендуется использовать операцию like.

Пример:

{
    "filter": {
        "like": [ 
            {"field": "fioFiled"},
            {"const": "Петрович"}
        ]
    }
}

Статус

Для полей типа Статус указывается число, представляющее собой номер статуса.

Пример:

{
    "filter": {
       "in": [
            {"field": "__status"},
            { "list": [1,2]}
        ]
    }
}

Пользователи

Для полей типа Пользователи указывается строковое представление UUID пользователя в нижнем регистре в кавычках.

Пример:

{
    "filter": {
        "eq": [
            {"field": "__createdBy"},
            {"const": "95806fe5-f8e8-460c-b2be-ce607068726c"}
        ]
    }
}

Приложение

Для поля типа Приложение нужно указать строковое представление UUID элемента. Независимо от того, множественное поле или одиночное, данные хранятся в виде массива. Поэтому рекомендуется работать с такими полями через оператор link.

Пример:

{
    "filter": {
        "link": [
            {"field": "fieldApp"},
            {"list": ["f5506c2b-0504-4420-9490-11a4f4d7f49d"]}
        ]
    }
}

Категория

Для поля типа Категория нужно указать строковый код элемента перечисления.

Пример:

{
    "filter": {
        "eq": [
            {"field": "enumField"},
            {"const": "enumValue1"}
        ]
    }
}

Операции равенства и неравенства

Операция равенства позволяет задавать условие фильтрации, основанное на полном совпадении. Задается конструкцией eq.

Операция неравенства позволяет задавать условие фильтрации, обратное операции равенства. Задается конструкцией neq.

Пример условия с равенством для целого числа:

{
    "filter": {
        "eq": [
            {"field": "weight"},
            {"const": 5}
        ]
    }
}

Пример условия с равенством для поля, содержащего дату:

{
    "filter": {
        "eq": [
            {"field": "ttlEnd"},
            {"const": "2023-04-12T11:11:45.367Z"}
        ]
    }
}

Пример условия с неравенством для поля типа Выбор «да/нет»:

{
    "filter": {
        "neq": [
            {"field": "opened"},
            {"const": true}
        ]
    }
}

Пример для проверки на непустое значение поля enum типа Категория:

{
    "filter": {
         "neq": [
            {"field": "enum"},
            null
        ]
    }
}

Операции «Больше», «Больше или равно», «Меньше» и «Меньше или равно»

Операция «Больше» позволяет задавать условие фильтрации, основанное на поиске большего значения. Задается конструкцией gt.

Операция «Больше или равно» позволяет задавать условие фильтрации, основанное на поиске большего или равного значения. Задается конструкцией gte.

Операция «Меньше» позволяет задавать условие фильтрации, основанное на поиске меньшего значения. Задается конструкцией lt.

Операция «Меньше или равно» позволяет задавать условие фильтрации, основанное на поиске меньшего или равного значения. Задается конструкцией lte.

Пример поиска статуса, отличного от начального:

{
    "filter": {
        "gt": [
            {"field": "__status"},
            {"const": 1}
        ]
    }
}

Пример поиска даты, входящей в указанный промежуток:

{
    "filter": {
        "and": [
            {
                "gte": [
                    {"field": "ttlEnd"},
                    {"const": "2023-04-10T11:11:45.367Z"}
                ]
            },
            {
                "lte": [
                    {"field": "ttlEnd"},
                    {"const": "2023-04-12T11:11:45.367Z"}
                ]
            }
        ]
    }
}

Операция вхождения подстроки

Операция вхождения подстроки позволяет задавать условие фильтрации, основанное на частичном совпадении. Задается конструкцией like.

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

{
    "filter": {
        "like": [
            {"field": "__name"},
            {"const": "город"}
        ]
    }
}

Операции вхождения в множество и невхождения в множество

Операция вхождения в множество позволяет задавать условие фильтрации, при котором значение одиночного поля проверяется на вхождение в множество. Задается конструкцией in.

Операция невхождения в множество позволяет задавать условие фильтрации, при котором значение одиночного поля проверяется на невхождение в множество. Задается конструкцией not_in.

Пример поиска по вхождению значения поля в заданный список:

{
    "filter": {
        "in": [
            {"field": "weight"},
            { "list": [1, 11] }
        ]
    }
}

Пример поиска по невхождению поля типа Категория в заданный список:

{
    "filter": {
        "not_in": [
            {"field": "enum"},
            { "list": ["Number1", "Number3", "Number5"] }
        ]
    }
}

Операция «В связанной коллекции»

Операция «В связанной коллекции» позволяет задавать условие фильтрации, при котором значение множественного поля типа Приложение проверяется на наличие связи с определенным элементом. Задается конструкцией link. В качестве значения передается UUID элемента приложения.

Пример:

{
    "filter": {
        "link": [
            {"field": "fewApps"},
            { "list": ["f5506c2b-0504-4420-9490-11a4f4d7f49d", "e20379bc-2f80-4b63-9e77-fbb3fa50e362"] }
        ]
    }
}

Операция «Вхождение множества»

Операция «Вхождение множества» позволяет задавать условие фильтрации, при котором значение множественного поля проверяется на вхождение в множество, заданное в условии. Задается конструкцией all.

Пример поиска по вхождению значения поля в заранее определенный список пользователей:

{
    "filter": {
        "all": [
            {"field": "users"},
            { "list": ["95806fe5-f8e8-460c-b2be-ce607068726c", "f5506c2b-0504-4420-9490-11a4f4d7f49d"] }
        ]
    }
}

Логические операции

Логическая операция «И»

Логическая операция «И» позволяет соединять условия фильтрации. Результатом выборки будут элементы, удовлетворяющие всем условиям.

Задается конструкцией and.

Пример:

{
    "filter": {
        "and": [
            {
                "eq": [
                    {"field": "field1"},
                    {"const": "value1"}
                ]
            },
            {
                "eq": [
                    {"field": "field2"},
                    {"const": "value2"}
                ]
            }
        ]
    }
}

Логическая операция «ИЛИ»

Логическая операция «ИЛИ» позволяет соединять условия фильтрации. Результатом выборки будут элементы, удовлетворяющие одному из условий.

Задается конструкцией or.

Пример:

{
    "filter": {
        "or": [
            {
                "eq": [
                    {"field": "field1"},
                    {"const": "value1"}
                ]
            },
            {
                "eq": [
                    {"field": "field2"},
                    {"const": "value2"}
                ]
            }
        ]
    }
}

Логическая операция «НЕ»

Логическая операция «НЕ» позволяет инвертировать условие фильтрации. Результатом выборки будут элементы, не удовлетворяющие вложенным условиям.

Задается конструкцией not.

Пример:

{
    "filter": {
        "not": {
            "eq": [
                {"field": "field1"},
                {"const": "value1"}
            ]
        }
    }
}

Комбинация логических операций

При объявлении фильтрации можно использовать комбинацию операций:

{
    "filter": {
        "not": {
            "or": [
                {
                    "eq": [
                        {"field": "field1"},
                        {"const": "value1"}
                    ]
                },
                {
                    "and": [
                        {
                            "eq": [
                                {"field": "field2"},
                                {"const": "value2"}
                            ]
                        },
                        {
                            "eq": [
                               {"field": "field3"},
                               {"const": "value3"}
                            ]
                        }
                    ]
                }
            ]
        }
    }
}

Работа с фильтрами

Табличная операция

Строка

Число

Дата/время

Выбор «да/нет»

Номер телефона

Электронная почта

Ф.И.О.

Статус

Пользователи

Приложение

Произвольное приложение

Категория

Операции условий

Форматы условий для типов данных

Строка

Число

Деньги

Дата/время

Выбор «да/нет»

Номер телефона

Электронная почта

Ф.И.О.

Статус

Пользователи

Приложение

Категория

Операции равенства и неравенства

Операции «Больше», «Больше или равно», «Меньше» и «Меньше или равно»

Операция вхождения подстроки

Операции вхождения в множество и невхождения в множество

Операция «В связанной коллекции»

Операция «Вхождение множества»

Логические операции

Логическая операция «И»

Логическая операция «ИЛИ»

Логическая операция «НЕ»

Комбинация логических операций