Разработка

Index API

описание работы АПИ

Index API

Описание API

https://indshop-pg-02.corp.rarus-cloud.ru/swagger/index.html#/
https://indshop-pg-03.corp.rarus-cloud.ru/docs#

Описание Индекс АПИ (index.rarus-spp.ru)

https://gitlab.rarus.ru/dr-1C-retail/index.service/-/blob/master/docs/api_index_description.md

https://gitlab.rarus.ru/dr-1C-retail/index.service/-/blob/master/docs/api_index_description.pdf

Пример запроса получения индекса

Пример запроса

{
    "query": [
        {
            "id": 1,
            "start_date": "2023-12-01",
            "end_date": "2023-12-06",
            "periodicity": "week",
            "entity": {
                "type": "template",
                "body": "0174b575-8ee0-4b87-be95-8c0864809317"
            }
        },
        {
            "id": 2,
            "start_date": "2023-12-01",
            "end_date": "2023-12-06",
            "periodicity": "week",
            "entity": {
                "type": "template",
                "body": "28954f97-9573-4747-bd7d-ba8cf909dcd8"
            }
        },
        {
            "id": 3,
            "start_date": "2023-12-01",
            "end_date": "2023-12-06",
            "periodicity": "week",
            "entity": {
                "type": "objects",
                "body": [
                    "4aadc65c-eea6-41f4-a199-a38a61d85300",
                    "198bdb10-e709-4ab4-9a56-3298376fb886",
                    "a06363f6-414d-44dd-89e1-fd3e264612b9"
                ]
            }
        }
    ]
}

start_date - всегда включая
end_date - всегда включая

Пример ответа

{
    "error": false,
    "message": "ok",
    "data": [
        {
            "id": 1,
            "start_date": "2023-08-28",
            "end_date": "2023-09-03",
            "value": 6.66,
            "discription": "35 неделя 2023"
        },
        {
            "id": 1,
            "start_date": "2023-09-04",
            "end_date": "2023-09-10",
            "value": 6.66,
            "discription": "36 неделя 2023"
        },
        {
            "id": 1,
            "start_date": "2023-09-11",
            "end_date": "2023-09-12",
            "value": 6.66,
            "discription": "37 неделя 2023"
        },
        {
            "id": 2,
            "start_date": "2023-08-28",
            "end_date": "2023-09-03",
            "value": 6.66,
            "discription": "35 неделя 2023"
        },
        {
            "id": 2,
            "start_date": "2023-09-04",
            "end_date": "2023-09-10",
            "value": 6.66,
            "discription": "36 неделя 2023"
        },
        {
            "id": 2,
            "start_date": "2023-09-11",
            "end_date": "2023-09-12",
            "value": 6.66,
            "discription": "37 неделя 2023"
        },
        {
            "id": 3,
            "start_date": "2023-08-28",
            "end_date": "2023-09-03",
            "value": 6.66,
            "discription": "35 неделя 2023"
        },
        {
            "id": 3,
            "start_date": "2023-09-04",
            "end_date": "2023-09-10",
            "value": 6.66,
            "discription": "36 неделя 2023"
        },
        {
            "id": 3,
            "start_date": "2023-09-11",
            "end_date": "2023-09-12",
            "value": 6.66,
            "discription": "37 неделя 2023"
        }
    ]
}

day_start, day_end - календарный период периодичности

discription - опиcание периода:

 

 

Утилита миграции данных из внешних источников

Утилита миграции данных из внешних источников

Запросы к ClickHouse

Запрос на получение метрик по объектам:

SELECT 
	sum(count) as count,
	multiIf(portal_id in &ПереходыВыходы AND metric_type == 'out', 'in', portal_id in &ПереходыВыходы AND metric_type == 'in', 'out', toString(metric_type)) as metric_type,
	toStartOfDay(toDateTime(timestamp, &ЧасовойПояс)) as timestampDay
FROM
	metrics_by_portals FINAL 
WHERE
	portal_id in  &ПереходыВсе
	AND toDateTime(timestamp, &ЧасовойПояс) BETWEEN toDateTime(&ДатаНачалаОтбора, &ЧасовойПояс) AND toDateTime(&ДатаОкончанияОтбора, &ЧасовойПояс)
	AND HOUR(toDateTime(timestamp, &ЧасовойПояс)) IN &МассивЧасовРаботы
	AND multiIf(HOUR(toDateTime(timestamp, &ЧасовойПояс)) = &ЧасНачалаРаботы, MINUTE(toDateTime(timestamp, &ЧасовойПояс)) >= &МинутаНачалаРаботы, HOUR(toDateTime(timestamp, &ЧасовойПояс)) = &ЧасОкончанияРаботы, MINUTE(toDateTime(timestamp, &ЧасовойПояс)) < &МинутаОкончанияРаботы, MINUTE(toDateTime(timestamp, &ЧасовойПояс)) >= 0)
GROUP BY
(
	metric_type,
	timestampDay
)
HAVING metric_type = 'in' 
SETTINGS optimize_move_to_prewhere_if_final = 1

где, 

Отбор по времени работы объекта использовать только в случае если объект не круглосуточный. 

 

Пример заполненного запроса:

SELECT 
	sum(count) as count,
	multiIf(portal_id in ('074d4fdd-6b5d-417b-a9b3-ee84b52b2252') AND metric_type == 'out', 'in', portal_id in ('4ad9d597-f21d-45dc-880a-72926630edea') AND metric_type == 'in', 'out', toString(metric_type)) as metric_type,
	toStartOfDay(toDateTime(timestamp, 'Asia/Yekaterinburg')) as timestampDay
FROM
	metrics_by_portals FINAL 
WHERE
	portal_id in ('05b6bef9-5c34-41b4-ae8f-8e09869e3f12', '074d4fdd-6b5d-417b-a9b3-ee84b52b2252')
	AND toDateTime(timestamp, 'Asia/Yekaterinburg') BETWEEN toDateTime('2023-03-26 00:00:00', 'Asia/Yekaterinburg') AND toDateTime('2023-03-26 23:59:59', 'Asia/Yekaterinburg')
	AND HOUR(toDateTime(timestamp, 'Asia/Yekaterinburg')) IN (5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21)
	AND multiIf(HOUR(toDateTime(timestamp, 'Asia/Yekaterinburg')) = 5, MINUTE(toDateTime(timestamp, 'Asia/Yekaterinburg')) >= 0, HOUR(toDateTime(timestamp, 'Asia/Yekaterinburg')) = 21, MINUTE(toDateTime(timestamp, 'Asia/Yekaterinburg')) < 25, MINUTE(toDateTime(timestamp, 'Asia/Yekaterinburg')) >= 0)
GROUP BY
(
	metric_type,
	timestampDay
)
HAVING metric_type = 'in' 
SETTINGS optimize_move_to_prewhere_if_final = 1

 

Получение данных по объекту:

SELECT 
	object_id as object_id,
	name as name, 
	portal_id as portal_id, 
	direction as direction,
	working_hours.timezone,
	working_hours.start_time,
	working_hours.end_time,
	working_hours.around_the_clock 
FROM 
	objects
	LEFT ANY JOIN working_hours AS wh
	  ON working_hours.object_id = objects.object_id
 ORDER BY object_id

Пример результата запроса:

image-1696854188264.png

Утилита миграции данных из внешних источников

Описание

Настройки

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

ENV файл представляется собой текстовый файл, в котором описаны настройки в формате КЛЮЧ=ЗНАЧЕНИЕ. Каждая строка файла может содержать одну пару КЛЮЧ=ЗНАЧЕНИЕ. Для ENV файла допускается имя .env и win.env. Значение переменных из файла ENV имеют более высокий приоритет чем переменные среды.

Описание настроек

ниже описаны настройки, разбитые на группы

Настройки приложения
Настройки локальной базы приложения
Настройки расписаний запуска задач
Настройки для взаимодействия с index-сервисом
Настройки адаптера CLICKHOUSE
Настройки адаптера COUNTMAX

возможно задание нескольких экземпляров.

номер экземпляра задается необязательным окончанием _NUM,
где NUM - целое положительное число

например
SPPINDEX_COUNTMAX_HOST - задает адрес сервера для нулевого экземпляра адаптера
SPPINDEX_COUNTMAX_HOST_1 - задает адрес сервера для первого экземпляра адаптера

сортировка адаптеров осуществляется по номеру экземпляра
допускается пропуск номеров

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

Облако

Тестовый экземпляр утилиты миграции развернут в облаке. spp_agent_dev -> index-migration

Взаимодействие с index-сервисом

В зависимости от расписания заданного в SPPINDEX_CRON_UPLOAD запускается задача загрузки данных в index-сервис.

Загружаются только раннее не синхронизированные данные.

Последовательность действий итерации:

  1. Получение из локально кеша объектов по которым есть несихронизированные метрики
  2. Для каждого объекта из пункта 1 делается запрос http запрос в index-сервис для сохранения. В ответе получаем id объекта в базе сервиса
  3. Получение несинхронизированных метрик из локального кеша.
  4. Отправка данных из пункта 3 пачками в index-сервис
  5. При успешном запросе в п.4 помечаем метрики как синхронизированные

Описание API для взаимодействия с index-сервисом

Запрос сохранения объекта

POST: SPPINDEX_SERVICE_URL/control/clients/1/init_organization_object

{
    "external_id": OBJECT_ID
	"name": OBJECT_NAME
}

Ответ сервиса:

{
    "error": ERROR_FLAG,
    "message": MESSAGE,
    "id": REMOTE_OBJECT_ID
}
Запрос сохранения метрик

POST: SPPINDEX_SERVICE_URL/data/visits

[
  	...,
    {
  		"object_id": REMOTE_OBJECT_ID,
  		"day": DATE,
  		"visits": VISITS_COUNT
 	},
	...
]

Ответ сервиса:

{
    "error": ERROR_FLAG,
    "message": MESSAGE
}

 

 

Процесс загрузки объектов и их посещаемости из внешних систем

Процесс создания объектов из компоненты загрузки из внешних систем:

Для этого процесса необходимо чтобы в структуре бд была добавлена таблица соответствия внешнего id объекта и id объекта

  1. Отправляется запрос с админским токеном на создание объекта с полями:
    1. Наименование
    2. id во внешней системе
  2. Сервис создает объект, при этом:
    1. Создает запись в таблице соответствия id объекта с id объекта во внешней системе 
    2. Привязывает объект к клиенту с идентификатором 1 (такого клиента мы считаем служебным и на него по умолчанию создаются новые объекты)
  3. Сервис возвращает информацию об успешной записи объекта

Процесс загрузки посещаемости объектов из внешних систем:

  1. Компонента отправляет запрос с полями:
    1. id объекта во внешней системе
      1. данные посещаемости
  2. Сервис определяет во id объекта во внешней системе id объекта сервиса
  3. Сервис записывает посещаемость объекта в таблицу Visits