Руководство пользователя
Для система интеллектуального диалогового поиска товаров AnyQuery Discovery Platform 4.0
1. Назначение документа
Настоящее руководство пользователя содержит сведения, необходимые для использования сервисов AnyQuery Discovery Platform 4.0 заказчиками и интеграторами. Документ описывает порядок применения autocomplete-service для формирования поисковых подсказок и результатов поиска на сайте заказчика, а также требования к предоставлению входных данных для feed-loader, обеспечивающего загрузку и обновление каталожной информации.
2. Общие сведения о сервисе
AnyQuery применяется для построения поисковых подсказок и поисковой выдачи на сайтах электронной коммерции. Со стороны заказчика основное взаимодействие осуществляется с autocomplete-service, который предоставляет публичные методы /autocomplete и /search. Эти методы используются для интеграции поисковой строки, формирования выпадающих подсказок, отображения страницы результатов поиска, применения фильтров и показа исправлений пользовательского запроса. Сервис может быть встроен в контур заказчика несколькими способами: как надстройка над существующим поисковым решением на базе Elasticsearch или Apache Solr, как независимая поисковая API, либо как гибридная интеграция, при которой AnyQuery отвечает за поисковые подсказки, а страница выдачи остается в зоне ответственности команды заказчика. Выбор способа интеграции определяется архитектурой сайта, зрелостью внутреннего поискового контура и требуемым объемом данных, передаваемых в AnyQuery.
3. Порядок взаимодействия заказчика с сервисом
Для начала работы заказчику предоставляются идентификатор проекта apiKey и значения стратегии ранжирования, используемые в запросах к /search. Интеграция рекомендуется к выполнению сначала на тестовой среде заказчика с последующим совместным тестированием со стороны AnyQuery и команды заказчика. При использовании API заказчик реализует вызов методов из собственного frontend-, backend- или BFF-контура и обрабатывает ответы сервиса в интерфейсе сайта или мобильного приложения.
С точки зрения пользовательского сценария на сайте работа строится следующим образом. При вводе текста в поисковую строку клиентское приложение обращается к методу /autocomplete и получает список поисковых подсказок. После подтверждения запроса или выбора подсказки выполняется обращение к методу /search, который возвращает ранжированный список товаров, коррекцию поисковой фразы, а при необходимости также фасеты и выбранные фильтры. Полученный ответ используется для отрисовки страницы поиска в соответствии с интерфейсом заказчика.
4. Использование autocomplete-service
4.1. Метод /autocomplete
Метод /autocomplete предназначен для формирования поисковых подсказок по мере ввода текста пользователем. Ответ метода используется в выпадающем списке под поисковой строкой и может содержать товары, категории, бренды, популярные поисковые формулировки и иные элементы навигации в зависимости от конфигурации проекта
Для система интеллектуального диалогового поиска товаров AnyQuery Discovery Platform 4.0
1. Назначение документа
Настоящее руководство пользователя содержит сведения, необходимые для использования сервисов AnyQuery Discovery Platform 4.0 заказчиками и интеграторами. Документ описывает порядок применения autocomplete-service для формирования поисковых подсказок и результатов поиска на сайте заказчика, а также требования к предоставлению входных данных для feed-loader, обеспечивающего загрузку и обновление каталожной информации.
2. Общие сведения о сервисе
AnyQuery применяется для построения поисковых подсказок и поисковой выдачи на сайтах электронной коммерции. Со стороны заказчика основное взаимодействие осуществляется с autocomplete-service, который предоставляет публичные методы /autocomplete и /search. Эти методы используются для интеграции поисковой строки, формирования выпадающих подсказок, отображения страницы результатов поиска, применения фильтров и показа исправлений пользовательского запроса. Сервис может быть встроен в контур заказчика несколькими способами: как надстройка над существующим поисковым решением на базе Elasticsearch или Apache Solr, как независимая поисковая API, либо как гибридная интеграция, при которой AnyQuery отвечает за поисковые подсказки, а страница выдачи остается в зоне ответственности команды заказчика. Выбор способа интеграции определяется архитектурой сайта, зрелостью внутреннего поискового контура и требуемым объемом данных, передаваемых в AnyQuery.
3. Порядок взаимодействия заказчика с сервисом
Для начала работы заказчику предоставляются идентификатор проекта apiKey и значения стратегии ранжирования, используемые в запросах к /search. Интеграция рекомендуется к выполнению сначала на тестовой среде заказчика с последующим совместным тестированием со стороны AnyQuery и команды заказчика. При использовании API заказчик реализует вызов методов из собственного frontend-, backend- или BFF-контура и обрабатывает ответы сервиса в интерфейсе сайта или мобильного приложения.
С точки зрения пользовательского сценария на сайте работа строится следующим образом. При вводе текста в поисковую строку клиентское приложение обращается к методу /autocomplete и получает список поисковых подсказок. После подтверждения запроса или выбора подсказки выполняется обращение к методу /search, который возвращает ранжированный список товаров, коррекцию поисковой фразы, а при необходимости также фасеты и выбранные фильтры. Полученный ответ используется для отрисовки страницы поиска в соответствии с интерфейсом заказчика.
4. Использование autocomplete-service
4.1. Метод /autocomplete
Метод /autocomplete предназначен для формирования поисковых подсказок по мере ввода текста пользователем. Ответ метода используется в выпадающем списке под поисковой строкой и может содержать товары, категории, бренды, популярные поисковые формулировки и иные элементы навигации в зависимости от конфигурации проекта
Параметр | Статус | Назначение |
apiKey | обязательный | Ключ проекта, по которому AnyQuery определяет контур заказчика и применяет настройки интеграции. |
st | обязательный | Пользовательская поисковая строка, по которой формируются подсказки. |
regionId | опциональный | Региональный контекст при использовании нескольких фидов или региональных источников. |
Дополнительные параметры | опциональные | Подключаются по согласованной конфигурации проекта, если требуется расширенное поведение подсказок. |
Интеграция /autocomplete должна предусматривать корректную обработку частично заполненного ответа. Отсутствие отдельных массивов в ответе не должно блокировать отрисовку страницы или поисковой строки; в этом случае интерфейс должен быть отображен без недоступного элемента. Для защиты пользовательского сценария рекомендуется применять троттлинг запросов к AUTOCOMPLETE на уровне 300 мс.
4.2. Метод /search
Метод /search используется для формирования страницы результатов поиска. Он поддерживает ранжирование, коррекцию запроса, пагинацию, фильтрацию, работу с фасетами, управление регионом и дополнительные режимы, влияющие на выдачу. Обязательными параметрами являются st, apiKey и strategy. Параметр strategy задает используемую стратегию ранжирования и предоставляется AnyQuery в рамках проекта.
Метод /search используется для формирования страницы результатов поиска. Он поддерживает ранжирование, коррекцию запроса, пагинацию, фильтрацию, работу с фасетами, управление регионом и дополнительные режимы, влияющие на выдачу. Обязательными параметрами являются st, apiKey и strategy. Параметр strategy задает используемую стратегию ранжирования и предоставляется AnyQuery в рамках проекта.
Параметр | Статус | Назначение |
st | обязательный | Пользовательский поисковый запрос. |
apiKey | обязательный | Ключ доступа, идентифицирующий проект заказчика. |
strategy | опциональный | Стратегия машинного ранжирования товаров в ответе API. |
size | опциональный | Размер выдачи; максимум 400, а при fullData=false допускается значение до 2000. |
offset | опциональный | Смещение для пагинации. |
withCorrection | опциональный | Возврат исправленного варианта поискового запроса. |
withFacets / treeFacets | опциональные | Возврат фильтров и выбор режима отображения фасетов. |
filter | опциональный | Фильтрация по категориям, брендам, цене и атрибутам фида |
sort | опциональный | Параметры сортировки результатов. |
regionId | опциональный | Региональный контекст; значение global используется как основной фид. |
withSku, fullData, showUnavailable, useCategoryPrediction, zeroQueries | опциональные | Дополнительные режимы формирования выдачи, применяемые по согласованной конфигурации интеграции. |
В ответе /search заказчик получает исходный запрос, его коррекцию, количество найденных товаров, признак zeroQueries, массив products, а при включении фасетной навигации также массивы facets и selectedFacets. В составе products могут передаваться идентификаторы товаров и групп, название, бренд, цена, score, категории, дополнительные атрибуты, ссылки на карточку и изображения. Формат ответа позволяет использовать AnyQuery как в сценарии независимой интеграции, так и в сценарии надстройки над существующей поисковой системой.
Для обращений к поисковой API рекомендуется устанавливать timeout ожидания ответа 2000 мс. При недоступности сервиса поисковый запрос должен обрабатываться стандартным поисковым механизмом сайта. Для метода sort.diginetica.net рекомендуется троттлинг 500 мс. Заказчику также необходимо соблюдать порядок выдачи, возвращенный AnyQuery, если сервис используется как источник ранжирования товаров.
4.3. Использование фильтров и фасетов
Фасеты используются для отображения фильтров на странице поиска. Они строятся на основе атрибутов продуктового фида и могут представлять категории, бренды, цену и иные свойства товаров. Каждый фасет содержит имя атрибута, тип данных, при необходимости единицу измерения и список значений для выбора. При формировании фильтрации требуется передавать корректные типы фильтров и значения в ожидаемом регистре; ошибочное имя типа фильтра или некорректное значение приводят к тому, что фильтрация не применяется либо не возвращает результатов.
5. Предоставление входных данных для feed-loader
Заказчик, как правило, не взаимодействует с feed-loader напрямую на уровне пользовательского интерфейса или служебных команд. Роль заказчика в данном процессе заключается в предоставлении ссылок на входные фиды в поддерживаемом формате. Feed-loader использует эти фиды для загрузки каталога, цен, доступности, контента и конфигурации фасетов, после чего соответствующие данные применяются в поиске и навигации на сайте.
Все входные файлы должны быть доступны по URL и корректно скачиваться из среды выполнения сервиса. Для XML и CSV требуется соблюдение корректной структуры данных. Ниже приведены поддерживаемые типы входных фидов и их назначение.
Для обращений к поисковой API рекомендуется устанавливать timeout ожидания ответа 2000 мс. При недоступности сервиса поисковый запрос должен обрабатываться стандартным поисковым механизмом сайта. Для метода sort.diginetica.net рекомендуется троттлинг 500 мс. Заказчику также необходимо соблюдать порядок выдачи, возвращенный AnyQuery, если сервис используется как источник ранжирования товаров.
4.3. Использование фильтров и фасетов
Фасеты используются для отображения фильтров на странице поиска. Они строятся на основе атрибутов продуктового фида и могут представлять категории, бренды, цену и иные свойства товаров. Каждый фасет содержит имя атрибута, тип данных, при необходимости единицу измерения и список значений для выбора. При формировании фильтрации требуется передавать корректные типы фильтров и значения в ожидаемом регистре; ошибочное имя типа фильтра или некорректное значение приводят к тому, что фильтрация не применяется либо не возвращает результатов.
5. Предоставление входных данных для feed-loader
Заказчик, как правило, не взаимодействует с feed-loader напрямую на уровне пользовательского интерфейса или служебных команд. Роль заказчика в данном процессе заключается в предоставлении ссылок на входные фиды в поддерживаемом формате. Feed-loader использует эти фиды для загрузки каталога, цен, доступности, контента и конфигурации фасетов, после чего соответствующие данные применяются в поиске и навигации на сайте.
Все входные файлы должны быть доступны по URL и корректно скачиваться из среды выполнения сервиса. Для XML и CSV требуется соблюдение корректной структуры данных. Ниже приведены поддерживаемые типы входных фидов и их назначение.
Тип фида | Формат | Назначение | Что предоставляет заказчик |
Master feed | JSON | Передача списка global и региональных источников для обновления метаданных. | URL на JSON-файл со списком feedUrls, где для каждого источника указаны url, externalId и title. |
YML feed | XML | Полная загрузка каталога товаров и категорий. | URL на основной каталог; при наличии регионов — также региональные фиды. |
Delta feed | CSV | Инкрементальное обновление цен, доступности и атрибутов без полного перезалива. | URL на CSV-файл изменений в согласованном формате. |
Content feed | XML | Загрузка контентных материалов для индексации и выдачи. | URL на XML-файл с элементами article. |
Facets feed | CSV | Передача конфигурации фасетов для категорий. | URL на CSV-файл с настройкой атрибутов и категорий. |
CHECK | по URL | Проверка качества фида и формирование отчета. | Ссылка на проверяемый фид и список email для получения отчета. |
Master feed используется в случаях, когда заказчику необходимо передать несколько источников, например основной global-фид и региональные фиды. Корневой объект такого JSON-файла должен содержать массив feedUrls. Для каждого элемента массива обязательны адрес фида, внешний идентификатор региона или источника и его название.
YML feed является основным форматом полной загрузки каталога. Базовая структура включает разделы categories и offers. Для корректной обработки оффер должен иметь идентификатор. Цена является обязательной для обработки региональной цены. Если в товаре отсутствует поле name, сервис может сформировать наименование из typePrefix, vendor и model. При этом товары с пустыми name и url отфильтровываются. В случае наличия региональных данных используются дополнительные элементы region и regional feeds.
Delta feed применяется для обновления отдельных товарных характеристик без полной перезагрузки каталога. Для этого типа фида обязательны поля id и price; цена со значением 0 считается невалидной. Поля available, oldPrice и regionExternalId являются опциональными. Остальные колонки рассматриваются как атрибуты товара. Сервис поддерживает как CSV с заголовком, так и CSV без заголовка; разделители и позиции колонок согласуются в конфигурации интеграции.
Content feed предназначен для загрузки контентных материалов. Корневым элементом является content, внутри которого размещаются элементы article. Для каждой статьи обязательны идентификатор, название и URL. Content feed используется для индексации и возможного показа контентных сущностей в поисковых сценариях. Для каждого сайта ожидается ровно один content feed.
Facets feed представляет собой CSV-файл для настройки фасетов по категориям. Обязательными колонками являются attribute и categoryId. Дополнительно могут передаваться порядок отображения, тип фасета и единица измерения. Поддерживаются как полный, так и минимальный формат. Для каждого сайта ожидается ровно один facets feed.
Режим CHECK не требует отдельного уникального формата файла: в сервис передается URL на фид и список адресов электронной почты, на которые отправляется отчет по качеству. Данный сценарий используется для предварительной проверки данных перед запуском или обновлением интеграции.
При обработке входных данных применяются общие ограничения. Для CONTENT и FACETS ожидается один фид соответствующего типа на сайт. Для DELTA строки с невалидными обязательными полями отбрасываются. Для YML ошибки отдельных региональных фидов не блокируют общий процесс полностью: некорректные региональные данные могут быть частично пропущены, при этом обработка основного каталога продолжается.
6. Рекомендации по внедрению
При внедрении сервиса заказчику рекомендуется выполнить интеграцию сначала на тестовой среде, затем провести совместное тестирование с командой AnyQuery и только после этого переносить решение в продуктивную среду. На этапе интеграции следует обеспечить корректный трекинг пользовательских действий. Для плавного запуска возможно применение client.js со стороны AnyQuery, однако при интеграции через API полноценный трекинг в ряде сценариев должен быть реализован на стороне заказчика, особенно если требуется учет использования автоподсказок, построение аналитики или поддержка мобильных приложений.
При обработке ответов AnyQuery интерфейс сайта не должен блокироваться из-за отсутствия необязательных массивов данных. Если часть обогащений временно недоступна, страница должна быть отрисована без них. Аналогично, при недоступности AnyQuery должен использоваться фоллбек на штатный механизм поиска, если такой предусмотрен архитектурой решения заказчика.
7. Представление сервиса для конечного пользователя сайта
Для конечного посетителя сайта использование AnyQuery выглядит как улучшенный поиск. В процессе ввода текста в поисковую строку пользователь получает мгновенные подсказки, позволяющие уточнить запрос или сразу перейти к нужному товару, бренду либо категории. После запуска поиска пользователь видит страницу результатов с ранжированной выдачей товаров, возможным исправлением поисковой фразы, фильтрами, сортировкой и навигационными элементами. Таким образом, с точки зрения конечного пользователя сервис обеспечивает более точный, быстрый и удобный поиск по каталогу интернет-магазина.
YML feed является основным форматом полной загрузки каталога. Базовая структура включает разделы categories и offers. Для корректной обработки оффер должен иметь идентификатор. Цена является обязательной для обработки региональной цены. Если в товаре отсутствует поле name, сервис может сформировать наименование из typePrefix, vendor и model. При этом товары с пустыми name и url отфильтровываются. В случае наличия региональных данных используются дополнительные элементы region и regional feeds.
Delta feed применяется для обновления отдельных товарных характеристик без полной перезагрузки каталога. Для этого типа фида обязательны поля id и price; цена со значением 0 считается невалидной. Поля available, oldPrice и regionExternalId являются опциональными. Остальные колонки рассматриваются как атрибуты товара. Сервис поддерживает как CSV с заголовком, так и CSV без заголовка; разделители и позиции колонок согласуются в конфигурации интеграции.
Content feed предназначен для загрузки контентных материалов. Корневым элементом является content, внутри которого размещаются элементы article. Для каждой статьи обязательны идентификатор, название и URL. Content feed используется для индексации и возможного показа контентных сущностей в поисковых сценариях. Для каждого сайта ожидается ровно один content feed.
Facets feed представляет собой CSV-файл для настройки фасетов по категориям. Обязательными колонками являются attribute и categoryId. Дополнительно могут передаваться порядок отображения, тип фасета и единица измерения. Поддерживаются как полный, так и минимальный формат. Для каждого сайта ожидается ровно один facets feed.
Режим CHECK не требует отдельного уникального формата файла: в сервис передается URL на фид и список адресов электронной почты, на которые отправляется отчет по качеству. Данный сценарий используется для предварительной проверки данных перед запуском или обновлением интеграции.
При обработке входных данных применяются общие ограничения. Для CONTENT и FACETS ожидается один фид соответствующего типа на сайт. Для DELTA строки с невалидными обязательными полями отбрасываются. Для YML ошибки отдельных региональных фидов не блокируют общий процесс полностью: некорректные региональные данные могут быть частично пропущены, при этом обработка основного каталога продолжается.
6. Рекомендации по внедрению
При внедрении сервиса заказчику рекомендуется выполнить интеграцию сначала на тестовой среде, затем провести совместное тестирование с командой AnyQuery и только после этого переносить решение в продуктивную среду. На этапе интеграции следует обеспечить корректный трекинг пользовательских действий. Для плавного запуска возможно применение client.js со стороны AnyQuery, однако при интеграции через API полноценный трекинг в ряде сценариев должен быть реализован на стороне заказчика, особенно если требуется учет использования автоподсказок, построение аналитики или поддержка мобильных приложений.
При обработке ответов AnyQuery интерфейс сайта не должен блокироваться из-за отсутствия необязательных массивов данных. Если часть обогащений временно недоступна, страница должна быть отрисована без них. Аналогично, при недоступности AnyQuery должен использоваться фоллбек на штатный механизм поиска, если такой предусмотрен архитектурой решения заказчика.
7. Представление сервиса для конечного пользователя сайта
Для конечного посетителя сайта использование AnyQuery выглядит как улучшенный поиск. В процессе ввода текста в поисковую строку пользователь получает мгновенные подсказки, позволяющие уточнить запрос или сразу перейти к нужному товару, бренду либо категории. После запуска поиска пользователь видит страницу результатов с ранжированной выдачей товаров, возможным исправлением поисковой фразы, фильтрами, сортировкой и навигационными элементами. Таким образом, с точки зрения конечного пользователя сервис обеспечивает более точный, быстрый и удобный поиск по каталогу интернет-магазина.