Параметры тела запроса

Эта страница описывает общую структуру body только для тех REST API-методов MPSTATS, которые принимают параметры пагинации, сортировки и фильтрации в теле запроса. В основной документации такие методы будут явно помечены, а описание параметров будет продублировано ссылкой на эту страницу.

Оглавление

• Базовая структура тела запроса
• Базовая структура тела ответа
• Пагинация данных
• Сортировка данных
• Фильтрация данных
• Типы фильтров
• Методы со сравнением периодов

Базовая структура тела запроса

{
  "startRow": 1,
  "endRow": 100,
  "filterModel": {},
  "sortModel": []
}

Описание полей:

Поле	Тип	Описание
startRow	number	Номер строки начала получения данных
endRow	number	Номер строки конца получения данных
filterModel	object	Набор фильтров
sortModel	array	Модель сортировки

Ограничение:

• за один вызов запроса можно получить не более 5000 записей

Базовая структура тела ответа

{
  "startRow": 0,
  "endRow": 100,
  "filterModel": {},
  "sortModel": [],
  "total": 42,
  "data": [{ "...": "..." }]
}

Описание полей:

Поле	Тип	Описание
startRow	number	Номер строки начала получения данных
endRow	number	Номер строки конца получения данных
filterModel	object	Фильтры, переданные в запросе
sortModel	array	Сортировка, переданная в запросе
total	number	Общее количество строк без учета пагинации
data	array	Массив данных

Пагинация данных

Свойства, относящиеся к разбивке на страницы:

{
  startRow: number,
  endRow: number,
  ... // остальные параметры
}

Сортировка данных

Пример модели сортировки:

{
  "sortModel": [
    { "colId": "balance", "sort": "asc" },
    { "colId": "sales", "sort": "desc" }
  ]
}

Фильтрация данных

Текстовые фильтры

interface TextFilterModel {
  filterType: string; // всегда "text"
  type: string; // тип фильтра, например "equals"
  filter?: string;
}

Числовые фильтры

interface NumberFilterModel {
  filterType: string; // всегда "number"
  type: string; // тип фильтра, например "equals"
  filter?: number;
  filterTo?: number;
}

Фильтры по дате

interface DateFilterModel {
  filterType: string; // всегда "date"
  type: string; // тип фильтра, например "equals"
  filter?: string;
  filterTo?: string;
}

Для дат используется строковый формат YYYY-MM-DD, например 2019-05-24.

Примеры модели фильтра

Числовой фильтр с одним условием:

{
  "balance": {
    "filterType": "number",
    "type": "lessThan",
    "filter": 35
  }
}

Числовой фильтр с диапазоном:

{
  "balance": {
    "filterType": "number",
    "type": "inRange",
    "filter": 35,
    "filterTo": 40
  }
}

Если фильтр содержит два условия, используется комбинированная модель:

interface ICombinedSimpleModel<M> {
  filterType: string;
  operator: string; // "AND" или "OR"
  condition1: M;
  condition2: M;
}

Пример фильтра с двумя условиями:

{
  "balance": {
    "filterType": "number",
    "operator": "OR",
    "condition1": {
      "filterType": "number",
      "type": "equals",
      "filter": 18
    },
    "condition2": {
      "filterType": "number",
      "type": "equals",
      "filter": 19
    }
  }
}

Типы фильтров

Параметр	Значение	Поддерживаемые типы
Равно	equals	text, number, date
Не равно	notEqual	text, number, date
Содержит	contains	text
Не содержит	notContains	text
Начинается с	startsWith	text
Заканчивается	endsWith	text
Меньше, чем	lessThan	number, date
Меньше или равно	lessThanOrEqual	number
Больше чем	greaterThan	number, date
Больше или равно	greaterThanOrEqual	number
В диапазоне	inRange	number, date

Практический способ быстрее понять модель фильтрации и сортировки — посмотреть реальные тела запросов к серверу через инструменты разработчика в браузере.

Методы со сравнением периодов

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

Тело запроса

{
  "startRow": 0,
  "endRow": 100,
  "filterModel": {},
  "sortModel": [],
  "d11": "2023-10-18",
  "d12": "2023-10-19",
  "d21": "2023-10-19",
  "d22": "2023-10-20"
}

Описание дополнительных полей:

Поле	Тип	Описание
d11	string	Начальная дата первого периода
d12	string	Конечная дата первого периода
d21	string	Начальная дата второго периода
d22	string	Конечная дата второго периода

Тело ответа

{
  "data": [{ "...": "..." }, { "...": "..." }],
  "total": 12401,
  "pinnedBottom": {
    "sales_count_1": 125570,
    "sales_count_2": 119968,
    "revenue_1": 278206980,
    "revenue_2": 264340823,
    "sales_count_diff": -5602,
    "revenue_diff": -13866157
  }
}

Описание поля pinnedBottom:

Поле	Описание
sales_count_1	Количество продаж в первом периоде
sales_count_2	Количество продаж во втором периоде
revenue_1	Выручка в первом периоде
revenue_2	Выручка во втором периоде
sales_count_diff	Разница продаж между первым и вторым периодом
revenue_diff	Разница выручки между первым и вторым периодом