Микросервис recommendation

В статье описываются функции, логика работы, конфигурация и методы микросервиса recommendation.

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

Доступ к сервису предоставляется по запросу.

Логика работы

В работе микросервиса участвуют следующие сущности:

  • Рекомендация (Recommendation) - содержит данные рекомендации (ID, тип и время создании рекомендации; категория, к которой относится рекомендация; список рекомендованных товаров)
  • Событие (Tracking) - содержит данные события (ID события; ID категории; артикул товара; ID покупателя; действие, вызывающее событие; бренд и др.)

Аутентификация и авторизация

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

Service context path

/api/recommendation/

Настройки и параметры конфигурации

Параметры конфигурации указываются в Vault.

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

По умолчанию

{
  "env": {
    "JAVA_XMS": "XXm",
    "JAVA_XMX": "YYYm",

    "SPRING_DATA_MONGODB_DATABASE": "название_бд",
    "SPRING_DATA_MONGODB_PORT": "порт_бд",
    "SPRING_DATA_MONGODB_USERNAME": "юзернейм_для_бд"
  }
}
Copy-icon
Указываемые на каждом отдельном стенде

// пример взят с тестового стенда


{
  "env": {
    "SPRING_DATA_MONGODB_HOST": "хост_бд",
    "SPRING_DATA_MONGODB_PASSWORD": "пароль_для_бд",
    "SPRING_OAUTH_AUTHORITY": "домен_сервера_аутентификации",
    "SPRING_OAUTH_CLIENT_ID": "client_id"
  }
}
Copy-icon

Методы микросервиса Copy-icon

Работа с рекомендациями Copy-icon

  • Получение списка рекомендаций для конкретной категории - GET запрос, /v2/recommendations/categories/{categoryId}
Request parameters

categoryId - path-параметр: ID категории, для которой необходимо получить рекомендации
Copy-icon
Response sample

{
  "id": "73aa8a3b-0645-453d-b9e5-4b90468200fb",
  "categoryId": "cat1000111DC",
  "articleIds": [
    "1000456DC",
    "1000789DC",
    "1000497DC",
    "1000418DC",
    "1001513DC",
    "1000467DC",
    "1000442DC",
    "1000450DC",
    "1000808DC",
    "1000446DC"
  ],
  "type": "CATEGORY",
  "recommendationTimestamp": "2024-01-03T13:56:49"
}
Copy-icon
Response codes

200 - операция успешно выполнена, получен список рекомендация для категории

  • Получение списка рекомендаций для конкретной категории - GET запрос, /v1/recommendations/categories/{categoryId}
Request parameters

categoryId - path-параметр: ID категории, для которой необходимо получить рекомендации
Copy-icon
Response sample

{
  "id": "73aa8a3b-0645-453d-b9e5-4b90468200fb",
  "categoryId": "cat1000111DC",
  "articleIds": [
    "1000456DC",
    "1000789DC",
    "1000497DC",
    "1000418DC",
    "1001513DC",
    "1000467DC",
    "1000442DC",
    "1000450DC",
    "1000808DC",
    "1000446DC"
  ],
  "type": "CATEGORY",
  "recommendationTimestamp": "2024-01-03T13:56:49"
}
Copy-icon
Response codes

200 - операция успешно выполнена, получен список рекомендация для категории

  • Получение списка всех рекомендаций - GET запрос, /v1/recommendations
Request parameters

page - query-параметр: номер страницы
size - query-параметр: количество отображаемых на странице элементов
sort - query-параметр: сортировка элементов на странице
Copy-icon
Response sample

{
  "content": [
    {
      "id": "53531c3a-7b10-4cce-8e55-f6809bb363fc",
      "categoryId": null,
      "articleIds": [
        "1000456DC",
        "1000789DC",
        "1000497DC",
        "1000418DC",
        "1000467DC",
        "1000808DC",
        "1000450DC",
        "1000442C",
        "1000446DC"
      ],
      "type": "PRODUCT",
      "recommendationTimestamp": "2023-12-25T11:25:11"
    },
    {
      "id": "2b010bc7-6ee7-4bd5-a121-1c0a0499f2cd",
      "categoryId": "cat1000111DC",
      "articleIds": [
        "1000456DC",
        "1000789DC",
        "1000497DC",
        "1000418DC",
        "1000467DC",
        "1000442DC",
        "1000450DC",
        "1000808DC",
        "1000446DC"
      ],
      "type": "CATEGORY",
      "recommendationTimestamp": "2023-12-25T11:25:11"
    },
    {
      "id": "98939981-3955-475f-8730-3d517f2240dd",
      "categoryId": "cat00003",
      "articleIds": [
        "1000009",
        "1000001",
        "1000006",
        "1000010",
        "1000002",
        "1000007"
      ],
      "type": null,
      "recommendationTimestamp": "2023-12-25T11:25:11"
    },
    {
      "id": "d18f8ba2-29df-48a3-a19b-f5d4a3823921",
      "categoryId": null,
      "articleIds": [
        "1000456DC",
        "1000789DC",
        "1000497DC",
        "1000418DC",
        "1001513DC",
        "1000467DC",
        "1000442DC",
        "1000450DC",
        "1000808DC",
        "1000446DC"
      ],
      "type": "PRODUCT",
      "recommendationTimestamp": "2024-01-03T13:56:49"
    },
    {
      "id": "73aa8a3b-0645-453d-b9e5-4b90468200fb",
      "categoryId": "cat1000111DC",
      "articleIds": [
        "1000456DC",
        "1000789DC",
        "1000497DC",
        "1000418DC",
        "1001513DC",
        "1000467DC",
        "1000442DC",
        "1000450DC",
        "1000808DC",
        "1000446DC"
      ],
      "type": "CATEGORY",
      "recommendationTimestamp": "2024-01-03T13:56:49"
    }
  ],
  "pageable": {
    "sort": {
      "unsorted": true,
      "sorted": false,
      "empty": true
    },
    "pageNumber": 0,
    "pageSize": 5,
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "last": false,
  "totalPages": 7,
  "totalElements": 33,
  "first": true,
  "numberOfElements": 5,
  "sort": {
    "unsorted": true,
    "sorted": false,
    "empty": true
  },
  "size": 5,
  "number": 0,
  "empty": false
}
Copy-icon
Response codes

200 - операция успешно выполнена, получен список рекомендаций

  • Получение рекомендации по ее ID - GET запрос, /v1/recommendations/{id}
Request parameters

id - path-параметр, обязательный: ID рекомендации
Copy-icon
Response sample

{
  "id": "73aa8a3b-0645-453d-b9e5-4b90468200fb",
  "categoryId": "cat1000111DC",
  "articleIds": [
    "1000456DC",
    "1000789DC",
    "1000497DC",
    "1000418DC",
    "1001513DC",
    "1000467DC",
    "1000442DC",
    "1000450DC",
    "1000808DC",
    "1000446DC"
  ],
  "type": "CATEGORY",
  "recommendationTimestamp": "2024-01-03T13:56:49"
}
Copy-icon
Response codes
  • 200 - операция успешно выполнена, получена рекомендация
  • 404 - ошибка, рекомендация с таким ID не найдена
  • Получение топ рекомендованных товаров - GET запрос, /v1/recommendations/products/top
Request parameters

Отсутствуют.

Response sample

{
  "id": "b5ccfc34-e2c0-4fc8-8fd4-69ef0681cfb0",
  "categoryId": null,
  "articleIds": [
    "1001428DC",
    "1001624DC",
    "1001479DC",
    "1001507DC",
    "1001505DC"
  ],
  "type": "PRODUCT",
  "recommendationTimestamp": "2024-02-21T14:26:39"
}
Copy-icon
Response codes

200 - операция успешно выполнена, получен топ рекомендованных товаров

  • Создание рекомендаций для категории - POST запрос, /v1recommendations/analyze
Request parameters

Отсутствуют.

Response sample

Отсутствует. В ответе приходит только код операции, например, 201.

Response codes

201 - операция успешно выполнена, созданы рекомендации для категории

Работа с событиями Copy-icon

  • Получение списка всех событий для построения рекомендаций - GET запрос, /v1/trackings
Request parameters

page - query-параметр: номер страницы
size - query-параметр: количество отображаемых на странице элементов
sort - query-параметр: сортировка элементов на странице
trackingFilter - query-параметр: фильтр событий (если ничего не указано, то будут возвращены все события)
trackingSelector - query-параметр: селектор событий (обязательно для заполнения, если указан trackingFilter)
Copy-icon
Response sample

{
  "content": [
    {
      "id": "13199559-ed31-4a24-9005-e4bff6880760",
      "categoryId": "cat1000118DC",
      "articleId": "1001624DC",
      "userId": "test@demo.digitalchief.ru",
      "searchTerm": null,
      "action": "click",
      "cartId": null,
      "orderId": null,
      "geoLocation": null,
      "actionTimestamp": "2024-01-03T13:55:36",
      "sessionId": null,
      "quantity": null,
      "brand": "DigitalChief"
    },
    {
      "id": "09414db9-0821-4ef8-9223-ecb961b22996",
      "categoryId": "cat1000087DC",
      "articleId": "1001479DC",
      "userId": "test@demo.digitalchief.ru",
      "searchTerm": null,
      "action": "click",
      "cartId": null,
      "orderId": null,
      "geoLocation": null,
      "actionTimestamp": "2024-01-03T13:57:48",
      "sessionId": null,
      "quantity": null,
      "brand": "DigitalChief"
    },
    {
      "id": "3ce4ea33-f011-4ccc-b67c-d53156fbc567",
      "categoryId": "cat1000207DC",
      "articleId": "1001505DC",
      "userId": "test@demo.digitalchief.ru",
      "searchTerm": null,
      "action": "click",
      "cartId": null,
      "orderId": null,
      "geoLocation": null,
      "actionTimestamp": "2024-01-03T13:58:14",
      "sessionId": null,
      "quantity": null,
      "brand": "DigitalChief"
    },
    {
      "id": "01c884fb-c5b1-426e-b326-139e8cc2ca41",
      "categoryId": "cat1000207DC",
      "articleId": "1001507DC",
      "userId": "test@demo.digitalchief.ru",
      "searchTerm": null,
      "action": "click",
      "cartId": null,
      "orderId": null,
      "geoLocation": null,
      "actionTimestamp": "2024-01-03T13:58:30",
      "sessionId": null,
      "quantity": null,
      "brand": "DigitalChief"
    },
    {
      "id": "6a8ff146-9501-4879-aa31-82b12fbdc089",
      "categoryId": "cat1000087DC",
      "articleId": "1001522DC",
      "userId": "test@demo.digitalchief.ru",
      "searchTerm": null,
      "action": "click",
      "cartId": null,
      "orderId": null,
      "geoLocation": null,
      "actionTimestamp": "2024-01-03T15:58:29",
      "sessionId": null,
      "quantity": null,
      "brand": "DigitalChief"
    }
  ],
  "pageable": {
    "sort": {
      "unsorted": true,
      "sorted": false,
      "empty": true
    },
    "pageNumber": 0,
    "pageSize": 10,
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "last": true,
  "totalPages": 1,
  "totalElements": 5,
  "first": true,
  "numberOfElements": 5,
  "sort": {
    "unsorted": true,
    "sorted": false,
    "empty": true
  },
  "size": 10,
  "number": 0,
  "empty": false
}
Copy-icon
Response codes

200 - операция успешно выполнена, получен список событий

  • Получение конкретного события по его ID - GET запрос, /v1/trackings/{id}
Request parameters

id - path-параметр, обязательный: ID события
Copy-icon
Response sample

{
  "id": "6a8ff146-9501-4879-aa31-82b12fbdc089",
  "categoryId": "cat1000087DC",
  "articleId": "1001522DC",
  "userId": "test@demo.digitalchief.ru",
  "searchTerm": null,
  "action": "click",
  "cartId": null,
  "orderId": null,
  "geoLocation": null,
  "actionTimestamp": "2024-01-03T15:58:29",
  "sessionId": null,
  "quantity": null,
  "brand": "DigitalChief"
}
Copy-icon
Response codes
  • 200 - операция успешно выполнена, получено событие
  • 404 - ошибка, событие с таким ID не найдено
  • Добавление события для построения рекомендаций - POST запрос, /v1/trackings
Request body sample

{
  "categoryId": "cat1000070DC",
  "articleId": "1000418DC",
  "userId": "207348732260279826",
  "action": "add_to_cart",
  "cartId": "4b7e6hjA-107b-476b-816a-51hh256a30d1",
  "geolocation": {
    "location": {
        "lat": 37.421875199999995,
        "lng": -122.0851173
    },
    "accuracy": 120
  },
  "timestamp": "2024-01-30T10:01:10",
  "sessionId": "1B5CABCD3HUY49PJDF346798A9GGK77E9",
  "brand": "Asus"
}
Copy-icon
Response sample

{
  "id": "3b8r9df8-574e-694b-153a-66uu178j80i8",
  "categoryId": "cat1000070DC",
  "articleId": "1000418DC",
  "userId": "207348732260279826",
  "action": "add_to_cart",
  "cartId": "4b7e6hjA-107b-476b-816a-51hh256a30d1",
  "geolocation": {
    "location": {
        "lat": 37.421875199999995,
        "lng": -122.0851173
    },
    "accuracy": 120
  },
  "timestamp": "2024-01-30T10:01:10",
  "sessionId": "1B5CABCD3HUY49PJDF346798A9GGK77E9",
  "brand": "Asus"
}
Copy-icon
Response codes

201 - операция успешно выполнена, событие добавлено