Оглавление |
---|
Для того, чтобы разобраться в том, как выполняется поиск товаров и какие настройки поиска можно сделать, необходимо изучить информацию, предложенную ниже.
Товарный провайдер
Товарный провайдер — это сервис (или площадка) для торговли. Именно от товарного провайдера поступает информация о товарах (названия, настройки, конфигурации и тд) и товарных категориях в OT API и потом, с помощью ключа, транслируется на сайт владельца ключа.
На данный момент доступны для подключения Taobao (включая Tmall), Yahoo.co.jp, 1688.com .Доступные для подключения товарные провайдеры.
...
Получить список доступных провайдеров и некоторую информацию о них можно методом GetProviderInfoList.
Таобао и Tmall
Поиск по Таобао может осуществляться по разным направлениям. Направление напрямую зависит от задач сайта, на котором устанавливается ключ.
Название | Идентификатор | Как работает |
---|---|---|
Специальный поиск | Extended | Может искать товары только в указанной категории товаров (например, если ищут «туфли» в женской обуви, то искать будет только там, результаты из детской обуви показаны не будут) |
Tmall поиск | Official | В результатах поиска только товары Tmall |
.
...
Содержит в себе 2 провайдера:
- Обычная продажа товаров.
- Аукционные товары.
Каждый провайдер имеет один поиск.
Свой каталог
С помощью дополнительного модуля «Товары на складе» появится провайдер «Склад», для которого можно создать и заполнить свой каталог товаров.
Подробнее о модуле и его подключении: http://key.otcommerce.com/ru/service-payments-rates
Способы и условия поиска
У каждого товарного провайдера есть свой набор условий поиска. Этот набор можно варьировать под цели сайта. Получить список доступных способов поиска и полную информацию о том, что они поддерживают, можно методом GetProviderSearchMethodInfoList.
Сам поиск можно выполнить двумя методами: SearchItemsFrame и BatchSearchItemsFrame. По работе они полностью идентичны, только с помощью второго метода можно получить различную дополнительную информацию сразу за один запрос, помимо самого поиска. Возможная дополнительная информация будет описана далее.
Условия самого поиска также идентичны, передаются в параметр xmlParameters, и представлены структурой SearchItemsParameters (данная структура находится, например, в методе BatchSearchItemsFrame под полем "xmlParameters"). Посмотреть её содержимое можно кликнув по "Структура". Как и все структурные параметры, он имеет формат xml. xmlParameters в (Batch)SearchItemsFrame обязателен, так как он определяет, что собственно ищем. Примеры будут описаны далее.
Что называется условиями поиска
- Основные критерии поиска: поисковая фраза, категория, продавец, бренд.
- Дополнительные критерии поиска: фильтры по характеристикам, фильтр по новизне товара, и фильтры по разным иным качествам товара
- Сортировка выдачи поиска
Что из этого доступно, что нет, или какие доступны варианты, можно узнать из информации о способах поиска.
Получение информации о способах поиска
- Можно получить сразу все возможные способы поиска, методом GetProviderSearchMethodInfoList
- Можно получить подходящие способы поиска по заданным параметрам, методом GetAvailableProviderSearchMethodInfoListForSearchParameters
- Можно получить сразу вместе с поиском товаров методом BatchSearchItemsFrame, если указать дополнительный блок AvailableSearchMethods.
Что именно можно узнать в информации о способе поиска, и на какие условия поиска оно влияет, можно увидеть в таблице ниже. Например, для условия поиска OrderBy (сортировка товаров) можно узнать возможные значения из поля AvailableSorts в информации о способе поиска, эти параметры в таблице находятся в одной строке.
Сопоставление условий и возможностей поиска
В следующей таблице представлено сравнительное описание условий поиска, как они представлены в структуре параметров, и как они представлены в описании способов поиска.
Параметр | Условия поиска | Информация о способе поиска | ||||
---|---|---|---|---|---|---|
Название параметра | Пример значения | Описание параметра | Название параметра | Пример значения | Описание параметра | |
Провайдер | Provider | Taobao | Если в условиях поиска не указан провайдер явно, он будет определен по другим условиям (например, категории). Если ни одно условие не определяет провайдера, поиск будет произведен в провайдере по умолчанию. Если разные условия поиска ведут к различным провайдерам, то такой поиск невозможен и приведет к ошибке. | Provider | Taobao | Идентификатор провайдера |
Способ поиска | SearchMethod | Official | Если не указано, используется определенный в настройках способ поиска по умолчанию. | SearchMethod | Official | Название способа поиска |
DisplayName | Фирменные товары (Tmall) |
Условие поиска
Параметр для описания способа поиска
Название способа поиска (Тип используемого поискового метода)
Тип StringНазвание способа поиска (на нужном языке)
Отображаемое название способа поиска (на нужном языке) |
Особенности выбранного способа поиска
Flags | Список особенностей способа поиска |
Количество выводимых товаров на одну страницу (влияет на скорость загрузки страницы и работу скорости поиска)
Ограничения на число товаров | UseOptimalFrameSize | true/false | Признак использования оптимального размера фрейма вместо переданного. Если данное условие передано в значении true, то параметр frameSize игнорируется, и будет использовано OptimalFrameSize из выбранного способа поиска. | |||
OptimalFrameSize | 40 |
Оптимальное число запрашиваемых товаров (размер страницы) |
Максимальное число запрашиваемых товаров (размер страницы)
Тип Int32Максимальное число товаров, до которых может выдать способ поиска
Тип Int32. Если использовать страницы данного размера, это обеспечивает максимальную возможную скорость работы поиска, т.к. оно соответствует размерам страниц у провайдера. | |||||
MaximumFrameSize | 200 | Максимальное число товаров, которое можно получить за 1 запрос. Может работать значительно медленнее, чем при использовании оптимального числа. | |||
MaximumItemsCount | 4000 | Число товаров, до которого в принципе можно получить по одним и тем же условиям поиска. Чтобы получать больше товаров, надо менять и уточнять условия поиска. | |||
Сортировка товаров | OrderBy | Price:Asc | Если не указано, или указанное значение не входит в число допустимых, будет использована определенная в настройках сортировка по умолчанию. |
AvailableSorts | Список допустимых сортировок в способе поиска |
Тип провайдера Nullable<ItemProviderType>
Тип ItemProviderTypeНазвание товара
Поддерживает ли способ поиска продавца (VendorId в параметрах поиска)
Тип Boolean
Поддерживает ли способ поиска местонахождение продавца (VendorAreaId в параметрах поиска)
Тип BooleanПоддерживает ли способ поиска бренды (BrandId в параметрах поиска)
Тип Boolean. | ||||||
Категория | CategoryId | 16 | Идентификатор категории, в которой искать товары. | Category | true/false | Поддерживается ли поиск по категории |
Название товара | ItemTitle | платье | Поисковая строка по названию товара. Если в поисковой строке указаны только идентификатор (артикул) товара или ссылка на страницу на сайте провайдера, то будет найден и выдан именно этот единственный товар (или пусто, если таковой товар отсутствует). | Text | true/false | Поддерживается ли поиск по тексту |
LanguageOfQuery | ru | Язык поисковой строки по названию товара. Если не указан, считается равным языку выдачи товаров. Если не равен языку провайдера, то производится автоперевод на язык провайдера. | ||||
Продавец | VendorId | Идентификатор продавца | Vendor | true/false | Поддерживается ли поиск по продавцу | |
VendorName | Имя продавца | |||||
Местонахождение продавца | VendorAreaId | Идентификатор местонахождения продавца (зоны) | VendorLocation | true/false | Поддерживает ли способ поиска местонахождение продавца | |
Рейтинг продавца | VendorRatingRange | true/false | Поддерживает ли способ поиска фильтр по рейтингу продавца | |||
MinVendorRating | 5 | Минимальное значение рейтинга продавца | MinVendorRating | 1 | Минимальное значение рейтинга продавца | |
MaxVendorRating | 15 | Максимальное значение рейтинга продавца | MaxVendorRating | 20 | Максимальное значение рейтинга продавца ВАЖНО! Максимальное значение рейтинга у разных провайдеров разное. Его можно найти в доступных поисковых методах провайдера. | |
Бренд | BrandId | Идентификатор искомой торговой марки | Brand | true/false | Поддерживает ли способ поиска бренды | |
BrandPropertyValueId | Идентификатор значения искомой торговой марки (устаревший параметр, используйте BrandId) | |||||
Цена | MinPrice | 10 | Минимальная цена | PriceRange | true/false |
Поддерживает ли способ поиска фильтр по цене товара |
MaxPrice | 1000 | Максимальная цена | ||||
CurrencyCode | CNY | Код валюты, в которой указан диапазон цен. | ||||
Объем продаж | MinVolume | 100 | Минимальный объем продаж | VolumeRange | true/false | Поддерживает ли способ поиска фильтр по объему продаж |
Поддерживает ли способ поиска фильтр по рейтингу продавца (MinVendorRating и MaxVendorRating в параметрах поиска)
Тип BooleanМинимальное значение рейтинга продавца
Тип Int32Максимальное значение рейтинга продавца
Тип Int32MaxVolume | 500 | Максимальный объем продаж | ||||
VolumeRangeLogic | None / Range / OnlyMin / OnlyMax | Логика работы условий по объему продаж: диапазон, только минимум, только максимум. | ||||
Минимальная партия | MinFirstLot | 5 | Минимальный размер первой партии товара | FirstLotRange | true/false | Поддерживает ли способ поиска фильтр по минимальной партии |
MaxFirstLot | 10 | Максимальный размер первой партии товара | ||||
Состояние |
товара (новый, б/у, неиспользованый) | StuffStatus | New / Unused / Second | Состояние товара | StuffStatus | true/false | Поддерживает ли способ поиска фильтр по состоянию товара |
Характеристики товара (цвет, модель и тд) | Configurators | Список поисковых свойств, представленных структурой. | Configurators | true/false | Поддерживает ли способ поиска характеристики товара |
. | ||||
MultipleConfiguratorLogic | None / All / And | Логика работы способа поиска по нескольким значениям одной характеристики. Использование в поиске нескольких значений одной характеристики. (например, можно вывести только красное, красное И зеленое, красное ИЛИ зеленое) | ||
Особенности товара | Features | Список искомых специальных фильтров | Features |
Список специальных фильтров, поддерживаемых способом |
Список специальных фильтров, поддерживаемых способом поиска (Features в параметрах поиска)
Тип ProviderSearchFeatureInfo[]Использование в поиске нескольких значений одной характеристики
(например, можно вывести только красное, красное И зеленое, красное ИЛИ зеленое)
Логика работы способа поиска по нескольким значениям одной характеристики
Тип SearchMethodConfiguratorLogicИдентификатор категории, в которой искать товары
Тип StringИмя продавца
Тип StringИдентификатор продавца
Тип StringИдентификатор местонахождения продавца (зоны)
Тип StringПоисковая строка по названию товара
Тип StringЯзык поисковой строки по названию товара
Тип StringМинимальная цена
Тип Nullable<Decimal> : DecimalМаксимальная цена
Тип Nullable<Decimal> : DecimalМинимальный объем продаж
Тип Nullable<Int64> : Int64Максимальный объем продаж
Тип Nullable<Int64> : Int64Минимальный рейтинг продавца
Тип Nullable<Int32> : Int32Максимальный рейтинг продавца
Тип Nullable<Int32> : Int32Идентификатор искомой торговой марки
Тип StringИдентификатор значения искомой торговой марки (устаревший параметр, используйте BrandId)
Тип StringСписок поисковых свойств, представленных структурой
Тип OtapiValuedConfigurator[]Параметры сортировки
Тип StringРежим выдачи результатов поиска
Тип Nullable<SearchOutputMode> : SearchOutputModeРежим выдачи категорий в результатах поиска
Тип Nullable<SearchCategoryMode> : SearchCategoryModeПризнак выбора только оригинальных товаров
Тип Nullable<Boolean> : BooleanПризнак выбора только товаров из Tmall
Тип Nullable<Boolean> : BooleanСостояние товара
Тип Nullable<OtapiStuffStatus> : OtapiStuffStatusСписок искомых фич товара
Тип OtapiSearchFeature[]Признак очистки заголовков товаров
Тип Nullable<Boolean> : BooleanПризнак использования оптимального размера фрейма вместо переданного
Тип Nullable<Boolean> : BooleanПоиск по всем товарным провайдерам
Кроме того, если у вас к ключу подключено сразу несколько товарных провайдеров, есть вариант поиска сразу для всех товарных провайдеров и всех возможных условиях поиска. Для этого необходимо воспользоваться специальным поиском по OT API. Описание метода: BatchSearchItemsFrame
Что получаем еще вместе с поиском товара
поиска | ||||||
Поиск по фото | ImageUrl | Адрес изображения для поиска товаров | Module | Image | Параметры поиска по фото допустимы только в способе поиска, в котором свойство Module равно Image | |
ImageFileId | Файловый идентификатор изображения для поиска товаров Используется, если искомое изображение сперва было загружено через OTAPI. | |||||
Управление выдачей | OutputMode | Full / TotalCount / Provider | Режим выдачи результатов поиска. По умолчанию делается обычный поиск, с выдачей товаров и всего сопутствующего. Другие варианты:
| |||
CategoryMode | Nothing / External / InternalLeaf / CurrentLevel | Режим выдачи категорий в результатах поиска. В результатах поиска помимо товаров есть еще, хоть и не всегда, список категорий, в которых находятся найденные товары. Обычно они называются уточняющими категориями. Есть несколько вариантов обработки и выдачи данного списка.
| ||||
Устаревшие условия | IsTmall | true/false | Признак выбора только товаров из Tmall |
Примеры параметров с условиями поиска и запросов поиска
Пример | Значение xmlParameters | Тестовый запрос | Комментарий | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
20 товаров провайдера Таобао |
| Пример в документации | Метод не выполнится без одного из обязательных параметров (CategoryId, VendorName, VendorId, ItemTitle, BrandId, Configurators), поэтому из GetProviderInfo берём RootCategoryId и передаём его в CategoryId (для поиска в корневой категории провайдера). Изменить количество искомых товаров (и другие параметры) можно перейдя по ссылке Пример в документации | |||||||||||
20 товаров провайдера Алибаба1688 путём конкретного способа поиска |
| Пример в документации | По умолчанию, способ поиска выбирается автоматически (на основе настроек ключа и параметров поиска). Иногда его нужно указывать явно, как, например, при поиске по отзывам. | |||||||||||
Поиск футболок с оптимальным для системы числом запрашиваемых товаров (размер страницы) |
| Пример в документации | Подробнее про поиск с оптимальным для системы числом запрашиваемых товаров (размер страницы) можно найти в пункте "Ограничения на число товаров" В frameSize передаём любое число больше 0. | |||||||||||
Сортировка 20 товаров Таобао по убыванию цены |
| Пример в документации | Подробнее про возможные способы сортировки. | |||||||||||
20 товаров провайдера Таобао отсортированные по кол-ву отзывов по убыванию |
| Пример в документации | Только при наличии модуля «Отзывы». | |||||||||||
Поиск футболок по убыванию количества продаж |
| Пример в документации | Подробнее про возможные способы сортировки. | |||||||||||
Поиск по внутренней категории otc-4 |
| Пример в документации | ||||||||||||
Поиск по категории 50000671 провайдера Taobao |
| Пример в документации | ||||||||||||
Поиск по категории с Alibaba1688 |
| Пример в документации | ||||||||||||
Поиск первых 100 товаров по запросу «красная футболка» |
| Пример в документации | ||||||||||||
Поиск на оригинальном языке: 红色T恤 |
| Пример в документации | ||||||||||||
Поиск на русском языке — «красная футболка» |
| Пример в документации | ||||||||||||
Поиск на английском языке — Red T-shirt |
| Пример в документации | ||||||||||||
Поиск по английскому слову (без перевода на китайский): 3D Vision |
| Пример в документации | ||||||||||||
Поиск по артикулу: 583346884671 |
| Пример в документации | ||||||||||||
Поиск по ссылке с Alibaba1688 |
| Пример в документации | ||||||||||||
Поиск по продавцу: maxmartin玛玛绨旗舰店 |
| Пример в документации | Значение для параметра VendorId (идентификатор продавца) можно найти, например, в данных любого товара. | |||||||||||
Поиск футболки по рейтингу продавца не меньше 19 Важно: Максимальное значение рейтинга продавца у разных провайдеров разное. Его можно найти в доступных поисковых методах провайдера. |
| Пример в документации | В данном конкретном примере единственный провайдер Таобао и максимальный рейтинг продавца у этого провайдера 20 | |||||||||||
Поиск по названию бренда: vero moda |
| Пример в документации |
| |||||||||||
Поиск футболок с ограниченной стоимостью: от 10 до 40 юаней |
| Пример в документации | В выборку попадают товары со скидочной ценой (PromotionPrice). Валюта (если не передана в явном виде) берётся из витрины (первая валюта) и конвертируется. | |||||||||||
Поиск футболки с ценой в долларах (эквивалент) не выше 3 |
| Пример в документации | Код валюты (CurrencyCode) берём в GetCurrencyInstanceList или в GetInstanceCurrencyInfoList | |||||||||||
Поиск футболки с минимальным объёмом продаж 50 штук |
| Пример в документации | ||||||||||||
Поиск футболки с минимальной партией заказа от 5 штук |
| Пример в документации | Только для Alibaba1688 | |||||||||||
Поиск футболки с максимальной партией заказа 1 штука (аналог заказа в розницу) |
| Пример в документации | ||||||||||||
Поиск только новых футболок |
| Пример в документации | На данный момент работает 2 состояния: новый и б/у. New: Новый | |||||||||||
Поиск по характеристике: футболка размера XL, красного цвета |
| Пример в документации |
<ItemAttribute Pid="20509" Vid="28317"> (для размера XL) <ItemAttribute Pid="1627207" Vid="13535612018"> (для цвета “красный”)
| |||||||||||
Поиск футболок со скидкой |
| Пример в документации | Список возможных особенностей (фич) можно взять из пункта №2 в документации. | |||||||||||
Поиск футболок в наличии |
| Пример в документации | ||||||||||||
Поиск футболок в Tмall |
| Пример в документации | ||||||||||||
Поиск товаров в категории "платья" с отзывами после покупки |
| Пример в документации | Только при наличии модуля «Отзывы». | |||||||||||
Поиск по изображению |
| Пример в документации | Можно искать по URL-у изображения или по закачанному через апи: подробности поиска по фото. |
Описание результатов поиска
Результаты поиска представлены структурой OtapiItemSearchResult, ниже описание её полей.
Параметр | Описание |
---|---|
Items | Список найденных товаров с указанием полного числа товаров |
Categories | Список категорий, в которых есть искомые товары (уточняющие товары) |
Brands | Список брендов, в которых встречаются товары (уточняющие бренды) |
TranslatedItemTitle | Текст, по которому реально искались товары (переведенный на язык провайдера) |
Provider | Товарный провайдер, в котором был произведен поиск |
SearchMethod | Способ поиска, которым был произведен поиск |
CurrentSort | Реальная текущая сортировка |
CurrentFrameSize | Реальный текущий размер фрейма (страницы) |
MaximumPageCount | Максимальное число страниц в поиске |
IsFoundByItemId | Если true, то в результатах поиска содержится 1 товар, который был найден по артикулу или ссылке |
Дополнительные блоки информации в BatchSearchItemsFrame
Используя метод BatchSearchItemsFrame, можно получить дополнительную информацию за тот же один запрос к OTAPI. Список дополнительных блоков передается в параметре blockList, через запятую. Результатом является BatchItemSearchResult, который включает в себя обычный OtapiItemSearchResult, а также все свойства для дополнительной информации.
Название блока | Описание |
---|---|
SubCategories | сразу получить подкатегории, если поиск был по категории |
SearchProperties | сразу получить фильтры по характеристикам/свойствам |
RootPath | сразу получить путь к корню, если поиск был по категории |
Vendor | сразу получить информацию о продавце, если поиск был по продавцу |
Brand | сразу получить информацию о бренде, если поиск был по бренду |
Category | сразу получить информацию о категории, если поиск был по категории |
HintCategories | сразу получить подходящие по названию категории, если поиск был по тексту |
AvailableSearchMethods | сразу получить список подходящих под данные параметры способов поиска, и всю информацию по ним |
...