Профили поиска и релизы

Профиль объединяет поля поиска, фасеты, фильтры и варианты сортировки. Клиент передаёт profile=storefront вместо необработанных query_by, facet_by и sort_by. Поисковый ключ можно привязать к профилю, запретив выбор другого.

Создание профиля

Откройте Консоль → Профили поиска, выберите коллекцию и создайте профиль. Настройте поля поиска, фасеты и именованные сортировки. Для фасетов в схеме должна быть включена фасетизация, для сортировки — её поддержка полем. Фиксированный фильтр всегда объединяется с фильтром посетителя.

Пример API с полным ключом предполагает коллекцию products с индексируемым строковым полем title:

curl -X POST 'https://api.aacsearch.com/v1/collections/products/search-profiles' \
  -H "X-NOVA-API-KEY: $NOVA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"name":"storefront","label":"Витрина","searchable_fields":["title"],"per_page_max":24}'

Имя — неизменяемый идентификатор. Полное обновление заменяет тело профиля, поэтому пропущенные поля возвращаются к значениям по умолчанию. Флаг is_default помогает интерфейсу выбрать профиль; API не применяет его автоматически.

Поиск с профилем

curl --get 'https://api.aacsearch.com/v1/collections/products/documents/search' \
  -H "X-NOVA-API-KEY: $NOVA_SEARCH_KEY" \
  --data-urlencode 'q=обувь' \
  --data-urlencode 'profile=storefront'

Не передавайте вместе с profile параметры, которыми он управляет. Для сортировки используйте sort=<id>. Фильтр посетителя может обращаться только к фасетным и разрешённым для фильтрации полям. Размер страницы ограничен per_page_max. Те же правила действуют для элементов multiSearch.

Виджет поддерживает атрибут profile. Браузерный endpoint GET /collections/{collectionName}/search-profiles/{profileName}/view возвращает подписи, ID сортировок и фасеты, но не выражения движка и не полную конфигурацию.

Публикация

До первой публикации сохранённые правки действуют со следующего запроса. Первая публикация включает режим релизов: дальнейшие правки изменяют только черновик до новой публикации.

publishSearchProfile (POST .../releases) — это API-вызов за шагами консоли выше. API-клиент сначала читает профиль и его revision, затем передаёт значение как expected_revision:

POST /collections/products/search-profiles/storefront/releases
Content-Type: application/json
X-NOVA-API-KEY: YOUR_FULL_KEY

{"expected_revision":1,"note":"Первая конфигурация витрины","change_class":"HOT"}

Значение 1 приведено только для примера — используйте только что прочитанную ревизию. Конкурентное изменение вернёт 409: перечитайте профиль и проверьте его перед повторением. Поддерживаются только HOT-релизы настроек запросов. WARM/COLD-операции с миграцией индекса отклоняются.

История и откат

listSearchProfileReleases (GET .../releases?limit=20) возвращает новые версии первыми. Если получен next_before_version, передайте его как before_version для следующей страницы.

activateSearchProfileRelease — активируйте предыдущую версию в консоли или запросом POST .../releases/{version}/activate с текущим expected_revision. Черновик сохранится. Повторная активация уже активной версии идемпотентна. При отсутствии или повреждении активного снимка поиск завершается ошибкой, не подменяя его черновиком.

Релиз сохраняет настройки профиля. Он не резервирует документы, не фиксирует содержимое внешней search_policy и не отменяет изменения схемы коллекции. См. проверку перед запуском и ошибки.