Руководтсво администратора/разработчика

Документация

Проектирование персональных страниц

Запросы


Обзор

Запросы - это объекты, в которых настраивается параметры и критерии запросов данных к API системы, параметры сортировки, пагенация и т.д.

Для внешнего получения данных запроса можно его вызвать, использую GET-запрос по адресу:

http(s)://домен/псевдоним/gui/query/идентификтор_запроса
  • идентификтор_запроса - это id-запроса (именуется пользователем) или его uid (формируется автоматически при создании)
Например: 
http://buildbox.app/buildbox/gui/query/test_message

При разработки проектов с использованием Buildbox Studio созданных объект запроса выбирается в "Блоке" страницы.


Создание запроса

Ключевой момент работы с данными - создание и настройка объекта запроса

Запрос - это объект, который необходимо создать в шаблона "Запросы", для этого нажмите на шаблона и нажмите кнопку создания объекта.

Стоит учитывать тот факт, что для каждого создаваемого проекта существуют системные запросы (пункт основного меню "Сервисные" - "Запросы (системные)" и запросы для каждого приложения, разрабатываемого в рамках данного проекта (пункты меню "Приложения" - "ваш_проект" - "Запросы"

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

При создании запроса необходимо настроить следущие параметры:

 


Создание фильтров

Для получения данных необходимо создать минимум один фильтр и указать его в "Схема фильтро"

Фильтр - это отдельный подзапрос на получение данных.

Для создания фильтра необходимо нажать кнопку "+" создания в списке фильтров внутреннего запроса.

В открывшейся форме заполните следущие параметры:

  • Название (обязательно)
  • Описание
  • Идентификатор (обязательно) - необходим для указания фильтра в "Схеме фильтров"
  • К запросу - связь фильтра с данным запросом (выбираеся автоматически)
  • Выбирать - выбор типов выбираемых объектов (Объекты/Поля/Шаблоны) (по-умолчанию - Объекты).
    Существует три типа объектов, в основном пользователь работает с Объектами, но сам Шаблон и Поля на форме шаблона тоже являются объектами, которые в исключительных случаях требуется получить из базы данных.


Условия поиска

При создании фильтров

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

Критериев поиска всего 5:

Стоит отметить, что каждое поле объекта имеет все 5 критерием.

Например, если вы выбрали в селекте (выподающее меню) объект, связанный с данным, то значение данного поля будет содержать в качестве src - идентификтор связанного объекта, value - заголовок объекта, element - id выбранного поля.

  • Направление связи - параметр указывающий, какой тип связи учитывать. Мы можем учитывать Входящими связи (другие объекты ссылаются на объект) и Исходящие связи - связи объектов шаблона, которые ссылаются на другие объекты.

 

Логические операторы

Для поля "

Правила оформления запроса:

  1. Если оператор не используется (по-умолчанию он равен "="), то кавычки можно опустить.

Перечень поддерживаемых операторов:

  • = - равно значению (по-умолчанию, если ничего не указано)
    Пример: = 'булочка с изюмом'
  • > - если значения больше текущего
  • < - если значения меньше текущего
  • >= - если значения больше или равно текущему
  • <= если значения меньше или равно текущему
  • IN - если значения находится в заданном списке
    Пример: IN 'сделано','отмечено'
  • NOT - если значение поля value не равно заданному
  • NULL или ISNULL - если значение поля vale не пустое
  • LIKE - поиск по шаблону (синтаксис схож с SQL) (см.ниже)

LIKE используются два подстановочных знака:

  • % - Знак процента представляет нулевой, один или несколько символов
  • _ - Подчеркнутый символ представляет собой один символ

Например: LIKE 'Т%' - выбирает объекты, если значение в поле value начинается с «Т»

Выражение Описание
LIKE 'text%' Находит любые значения, начинающиеся с "text"
LIKE '%text' Находит любые значения, заканчивающиеся на "text"
LIKE '%text%' Находит любые значения, которые имеют «text» в любой позиции
LIKE '_text%' Находит любые значения, которые имеют «text» во второй позиции
LIKE 'text_%_%' Находит любые значения, начинающиеся с «text» и длиной не менее 3 символов
LIKE 'text%data' Находит любые значения, начинающиеся с «text» и заканчивающиеся на «data»


Логические операции с фильтрами

Запрос может содержать несколько фильтров (источников данных), которые в дальнейшем могут быть скоминированны между собой.

Результатом выполнения каждого фильтра является массив идентификторов объектов, которые могут быть подвержены логическим операциям (объединения, пересечения), а также запуска другого запроса.

  • AND - находит пересечение множеств полученных объектов
  • OR - производит сложение полученных множество (если один объект попадае в результаты двух фильтров, то в результирующем массиве он указываетс один раз)
  • RUN - вызов другого запроса, в качестве дополнительного фильтра внутри запроса.

Например:

AND filter1, filter2

где:

  • AND - логическая операция
  • filter1, filter2 - названия фильтров


Ответ запроса

Данные, полученные в теле ответа запроса имеют стандартизованный формат, если запрос "внутренний" (был сформирован внутри Buildbox и получал данные из базы данных), то формат ответа имеет из себя следующий вид:

{
    "data": {}, - ту массив данных для внутреннего запроса и объекты без заданной структуры для внешнего
    "res": null,
    "status": {
        "description": "описание запроса",
        "status": (200 - все ОК, другие статусы говорят об ошибке),
        "error": "описание ошибки",
        "code": "код ошибки"
    },
    "metrics": {. - блок метрик выполнения запроса
        "result_size": 0, - общее количество объектов в результате
        "result_count": 0, - количество объектов в данной выдаче (мы можем получать не все данные, а и часть)
        "result_offset": 0, - сдвиг относительно начала выборки
        "result_limit": 0,  - лимит на страницу
        "result_page": 0, - текущая страница
        "time_execution": "",  - время выполнения запроса
        "time_query": "" - время получения данных из базы
    }
}

Если запрос был внешний (обращались к стороннему сервису, или был получен пустой ответ, то ответ запросы будет содержать тело полученного ответа без определенного формата, а следовательно его надо будет разбирать на стороне пользователя.