Выберите между фидами файлов и Merchant API

Вы можете загружать данные о товарах в Merchant Center с помощью фидов на основе файлов, Merchant API или обоих этих способов.

  • Фиды товаров на основе файлов. Загружайте файлы CSV, TSV или XML с помощью SFTP, Google Cloud Storage, Google Таблиц или загрузки по расписанию.
  • Merchant API. Отправляйте программные запросы непосредственно из серверной части для добавочных обновлений по мере изменения данных о товарах, а также периодически синхронизируйте весь каталог.

В этом руководстве мы сравним оба подхода, объясним, когда лучше использовать один из них, а когда – оба, и предоставим пошаговое руководство по переходу, если вы решите перенести некоторые или все свои товары из фидов файлов в API.

Выберите подход к источникам данных

Оцените изменчивость каталога, архитектуру серверной части и рабочие процессы, чтобы решить, что использовать: Merchant API, фиды файлов или гибридную настройку.

Когда использовать Merchant API

Используйте основной источник данных API, если:

  • Прямая программная интеграция. Вы предпочитаете вызывать API непосредственно из серверной части, а не создавать файлы и управлять конвейерами передачи файлов (например, SFTP или Google Cloud Storage).
  • Высокая волатильность цен и ассортимента. Цены на товары или уровень запасов часто меняются в течение дня.
  • Мгновенное обновление данных. Вы хотите, чтобы изменения в сведениях о товарах сразу же передавались в Google, а не ждали следующей загрузки файла по расписанию.
  • Дополнительные обновления каталога. Вы хотите добавлять, обновлять или удалять отдельные товары по мере их изменения, не загружая каждый раз весь каталог заново.
  • Частичное обновление атрибутов. Вы хотите обновить определенные поля товара (например, price или availability с помощью productInputs.patch), не отправляя повторно все данные о товаре.

Когда использовать фиды файлов

Используйте основной источник данных на основе файла, если:

  • Статический каталог. Данные о товарах меняются редко (например, раз в день или реже).
  • Бэкенд, поддерживающий только снимки, без отслеживания дельт. Ваш бэкенд экспортирует только полные снимки каталога и не может отслеживать изменения на уровне товаров или явные удаления товаров.
  • Рабочие процессы на основе таблиц. Команды, не связанные с разработкой, могут отбирать или переопределять данные о товарах непосредственно в Google Таблицах или CSV-файлах.
  • Простота в обслуживании. Вы предпочитаете запланированный экспорт файлов, при котором Merchant Center обрабатывает получение и обработку снимков, а не интеграцию API с регулированием запросов, обработкой повторных попыток и периодической синхронизацией всего каталога.

Когда использовать оба типа

Вы можете использовать фиды из файлов и Merchant API в одном аккаунте Merchant Center в следующих случаях:

  • Разделенные каталоги товаров. Вы используете Merchant API для товаров, информация о которых быстро меняется (например, для срочных распродаж или товаров с высокой оборачиваемостью), и фиды файлов для статических сегментов каталога или отдельных товарных линеек. Убедитесь, что каждый товар загружается только через один основной источник данных (см. раздел Параллельное использование и право собственности на основной источник данных).
  • Основной источник данных на базе API и дополнительные фиды на основе файлов. Вы управляете основными сведениями о товарах через основной источник данных на базе API, а другие команды или внешние партнеры предоставляют дополнительные атрибуты через дополнительные фиды на основе файлов (например, Google Таблицы или CSV-файлы), объединенные с правилами преобразования атрибутов, или наоборот.
  • Частичный или поэтапный переход. Вы переводите на API определенные рынки, категории или дочерние аккаунты, а остальной каталог оставляете в фидах файлов.

Если вы решите перенести некоторые или все товары из фидов файлов в Merchant API, следуйте пошаговому руководству по переносу.

Основные различия в архитектуре

Фиды на основе файлов и Merchant API на основе push-уведомлений по-разному обрабатывают данные о товарах и управляют ими.

Концепция Фиды файлов Merchant API
Модель интеграции Офлайн-дамп файла. Вы экспортируете каталог в файл и передаете его с помощью SFTP, Google Cloud Storage, Google Таблиц или загрузки по расписанию. Прямая программная интеграция. Ваш сервер отправляет запросы напрямую в конечную точку API.
Детализация изменений Массовая обработка. Изменение одного элемента обычно требует повторной обработки всего файла. Детализированные транзакции. Вы можете вставлять, исправлять или удалять только те товары, которые изменились.
Время синхронизации Пакетная синхронизация. Изменения хранятся в серверной части до следующего запланированного цикла экспорта и передачи файлов. Немедленные или запланированные вызовы. Вы можете отправлять дополнительные изменения сразу по мере их возникновения, а также периодически выполнять полную синхронизацию.
Поведение при удалении Неявное (снимок). Каждый файл представляет собой полный снимок. Удаление строки из основного файла приводит к удалению товара. Явный. Понятие снимка отсутствует. Чтобы удалить товар, снятый с производства, вызовите productInputs.delete.
Представление ресурса Одно состояние. Строки файла представляют собой необработанные входные данные. Разделение необработанных и обработанных данных. API разделяет данные на ProductInput (необработанные входные данные) и Product (конечные обработанные данные).
Правила преобразования атрибутов (фидов) Применяется к столбцам исходного файла в интерфейсе Merchant Center. Поддерживается в интерфейсе Merchant Center. Обязательно, если вы объединяете данные API со сторонними дополнительными файлами. Необязательно для преобразований с одним источником, если они выполняются на вашем сервере.

Параллельное использование и право собственности на основной источник данных ("последнее обновление побеждает")

Хотя в одном аккаунте Merchant Center можно использовать и фиды, и API, мы настоятельно рекомендуем добавлять каждый товар только одним способом.

В Merchant Center действует модель "последнее обновление имеет приоритет". Основной источник данных (API или фид-файл), который передал самые последние сведения о товаре, получает право собственности на данные этого товара:

  • Если товар принадлежит источнику данных в виде файла, то, если вы не добавите товар в следующую загрузку файла, он будет удален из Merchant Center.
  • Если источником данных, к которому относится товар, является API, то удаление товара из файла не повлияет на его статус, поскольку файл больше не является источником данных, к которому относится товар. Чтобы удалить его, вызовите accounts.productInputs.delete.
  • Риск случайного возврата права собственности. Если обновленный фид из файла будет запущен после отправки данных через API и будет содержать товар, право собственности вернется к источнику данных из файла. Если вы не добавите товар в файл, он будет удален.

Чтобы избежать непредвиденного удаления или потери обновлений API, не выполняйте одновременные обновления одних и тех же товаров с помощью API и основных источников данных файлов.

Что необходимо для работы с API

Прежде чем начать работу с Merchant API, ознакомьтесь с важными особенностями его работы:

Гибкие источники данных (без языка и ярлыка)

В отличие от фидов в виде файлов, для которых нужно заранее задать ярлык целевого фида и язык, Merchant API позволяет создавать основные источники данных без указания feedLabel или contentLanguage.

  • Гибкая загрузка. Вы можете загружать товары с любым языком или ярлыком фида в один источник данных.
  • Простое управление. Вам не нужно создавать отдельные источники данных для каждого целевого рынка и управлять ими. Примечание. Подробнее о том, как выбрать стратегию работы с источниками данных, читайте в этой статье.

Стратегия синхронизации и квоты

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

  • Сочетайте добавочные обновления с периодической полной синхронизацией. Отправляйте запросы productInputs.insert или productInputs.patch, когда атрибуты товаров меняются в вашей системе. Если вы будете полагаться только на добавочные обновления, со временем данные могут рассинхронизироваться. Поэтому периодически выполняйте полную синхронизацию, чтобы согласовать каталог с источником достоверной информации (это также обновляет 30-дневный срок действия товара). Частота полной синхронизации зависит от размера каталога и доступной квоты API.
  • Не превышайте квоты API. Не вызывайте API для всех товаров сразу. Дополнительные изменения можно отправлять по мере их появления, но запросы на полную синхронизацию следует распределять равномерно в течение дня, чтобы не превышать квоты на вызовы методов в минуту и в день. Подробнее о квотах и ограничениях и о частом обновлении сведений о товарах…

Тестирование интеграции

Прежде чем переходить к рабочей среде, проверьте логику интеграции в безопасной среде.

Используйте тестовый аккаунт

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

  1. Создайте тестовый аккаунт. Настройте изолированный тестовый аккаунт, чтобы безопасно экспериментировать, не влияя на активные объявления или бесплатные предложения.
  2. Создание источника данных API. Попробуйте создать основной источник данных API.
  3. Тестирование правил преобразования атрибутов. Проверяйте преобразования данных и объединения дополнительных фидов.
  4. Проверьте полезную нагрузку и ключи продуктов. Отправьте образцы продуктов, чтобы проверить регистр SKU, кодировку и обработку ошибок.

Подробную информацию вы найдете в разделе Шаг 1. Создайте тестовые аккаунты и руководстве Тестовые аккаунты.

Проверьте соответствие ключа продукта

Убедитесь, что ключ товара в полезной нагрузке для алгоритмических продаж точно совпадает с идентификатором SKU в фиде. Google идентифицирует товары по следующим атрибутам:

  • offerId (в фидах файлов называется id, с учетом регистра)
  • contentLanguage (например, en)
  • feedLabel (например, US)

Специальные символы и кодировка

Если идентификаторы товаров содержат такие символы, как /, % или ~, используйте в вызовах API закодированный формат (кодировка base64url без заполнения). Подробнее: ProductInput.name.

Управление параллелизмом

При интеграции в реальном времени обновления могут поступать не по порядку из-за задержки в сети. Чтобы старые обновления не перезаписывали новые данные, используйте поле versionNumber в ресурсе ProductInput.

Пошаговое руководство по переносу

Если вы решите перенести некоторые или все товары из фидов в Merchant API, следуйте этому руководству, чтобы не потерять показы и историю показов.

1. Проведите пробный перенос в тестовом аккаунте

Прежде чем вносить изменения в рабочую версию, создайте тестовый аккаунт в изолированной среде с помощью метода accounts.createTestAccount (см. руководство Тестовые аккаунты). Тестовые аккаунты предоставляют изолированную среду, в которой предложения одобряются по умолчанию, подтверждение домена не требуется, а данные никогда не публикуются.

Используйте тестовый аккаунт, чтобы воспроизвести рабочую среду и отрепетировать перенос от начала до конца.

  1. Создайте копию фида товаров. Создайте основной источник данных (и дополнительные, если они есть) в тестовом аккаунте и загрузите образец файла фида товаров.
  2. Создайте тестовый источник данных API и правила. Создайте основной источник данных API и настройте необходимые правила преобразования атрибутов или объединения дополнительных фидов.
  3. Протестируйте передачу права собственности и сопоставление ключей. Отправьте запросы productInputs.insert для образцов товаров и убедитесь, что источник данных API принимает право собственности на существующие товары без создания дублирующихся товаров.
  4. Проверьте обновления и удаления. Протестируйте частичные обновления с помощью productInputs.patch и удаления с помощью productInputs.delete, а затем проверьте полученные ресурсы с помощью products.get.

2. Как создать источники данных API для рабочей версии

Прежде чем отправлять данные, создайте в аккаунте основной источник данных типа API.

Как создать основной источник данных API

Чтобы создать источник данных, который принимает отправку данных через API, отправьте запрос POST к конечной точке dataSources. Подробнее о том, как создать основной источник данных о товарах…

3. Перенос правил для настраиваемых атрибутов

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

Способ переноса правил преобразования атрибутов зависит от их назначения:

  • Объединение данных из разных источников и дополнительные фиды от сторонних поставщиков. Если вы объединяете основные данные API с внешними дополнительными источниками данных (например, файлами сторонних поставщиков, таблицами ассортимента или фидами промоакций), вам необходимо заново создать правила преобразования атрибутов в интерфейсе Merchant Center и прикрепить их к новому источнику данных API. Предварительная обработка на стороне клиента не может заменить правила, которые объединяют данные из нескольких независимых источников.
  • Преобразование данных из одного источника. Для очистки данных, значений по умолчанию или форматирования строк в основном каталоге выберите один из следующих вариантов:
    • Преобразования на сервере (рекомендуется). Применяйте преобразования в собственной системе перед вызовом API. Это дает вам больше возможностей для программного управления, упрощает тестирование и отладку.
    • Правила преобразования атрибутов в Merchant Center. Если вы хотите, чтобы Merchant Center продолжал автоматически управлять правилами преобразования, создайте их заново для нового источника данных API в интерфейсе Merchant Center.

4. Как включить интеграцию API

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

  • Добавление и обновление товаров (смена владельца). Отправляйте запросы productInputs.insert и productInputs.patch из интегрированного приложения. Если вы добавите товар через API с тем же ключом (offerId, contentLanguage, feedLabel), что и у существующего товара из фида, источник данных API станет владельцем этого товара и сохранит его историю показа. Дополнительную информацию можно найти в статьях Как добавить товар и Как добавлять товары и управлять ими.

  • Удаляйте товары, снятые с производства. Настройте интеграцию так, чтобы при удалении товара из каталога вызывался метод productInputs.delete.

  • Развертывайте постепенно. Если у вас большой каталог, включайте интеграцию по одному дочернему аккаунту Merchant Center или источнику данных за раз.

  • Настройте параллельную обработку. Если вы отправляете много запросов, настройте клиент так, чтобы он мог обрабатывать параллельные запросы и управлять несколькими подключениями. Ознакомьтесь с руководством Рефакторинг кода для параллельных запросов.

5. Как приостановить обновление источника данных из файла

После активации интеграции API остановите обновление файлов до следующего запланированного запуска, чтобы источник данных файла не перезаписал обновления API.

  1. Прекратите загружать новые файлы в SFTP/FTP, Google Cloud Storage или Google Таблицы.
  2. В интерфейсе Merchant Center перейдите к источнику данных файла и приостановите загрузку по расписанию.
  3. Существующие товары, принадлежащие источнику данных файла, остаются активными в течение 30 дней, пока не будут добавлены через интеграцию API.

6. Дождитесь завершения переноса и проверьте его результаты

Дождитесь, пока все активные товары будут перенесены из источника данных в виде файла в источник данных API. Дополнительные обновления позволяют переносить товары по мере их изменения, а пошаговая синхронизация всего каталога с помощью обычной интеграции ускоряет перенос всего каталога (см. раздел Стратегия синхронизации и квоты).

В течение этого периода:

  1. Отслеживайте количество товаров в интерфейсе Merchant Center. Подождите, пока количество источников данных в файле не уменьшится до 0, а количество источников данных API не будет соответствовать вашему активному каталогу.
  2. Используйте products.get, чтобы проверить, правильно ли объединяются атрибуты и правила настраиваемых атрибутов.
  3. Отслеживайте частоту ошибок и производительность API с помощью инструмента Диагностика API в интерфейсе Merchant Center.

7. Как вывести из эксплуатации источник данных из файла

После завершения перехода и когда количество элементов фида в файле достигнет 0:

  1. Убедитесь, что изменения отражаются в режиме реального времени.
  2. Удалите устаревший источник данных в интерфейсе Merchant Center, чтобы предотвратить случайную перезапись данных API.
Назад
Migrate Local Inventory Ads settings