Миграция с v1beta на v1

Это руководство поможет вам перейти с версии Merchant API v1beta на v1 , первую версию, доступную для общего использования. Версия v1 содержит ряд обновлений и изменений, которые могут потребовать обновления кода. Эти изменения призваны упростить API и улучшить управление вашей учетной записью Merchant Center.

Ключевые отличия

Вот наиболее важные изменения, о которых следует помнить при переходе с v1beta на v1 :

• Одноразовая регистрация как минимум одного разработчика API для использования Merchant API: Вам потребуется вызвать метод registerGcp (только один раз для каждого проекта Google Cloud, используемого для аутентификации), чтобы указать свои контактные данные, что позволит вам использовать API и получать обновления и объявления, связанные с Merchant API. Вы не сможете использовать API версий v1 или v1alpha пока этот шаг не будет выполнен. Инструкции см. в разделе «Регистрация разработчика» .

• Кодировка названия продукта : поля ProductInput.name и Product.name поддерживают кодировку base64url без дополнения (RFC 4648, раздел 5) . Следуйте этим рекомендациям:

  • Перед кодированием строка должна соответствовать формату contentLanguage~feedLabel~offerId .

  • Кодировка обязательна , если название вашего товара содержит символы, используемые API продавца или зарезервированные в URL-адресе символы, такие как:

    % . + / : ~ , ( * ! ) & ? = @ # $
    

  • Если название вашего продукта соответствует формату contentLanguage~feedLabel~offerId и не содержит символов, используемых Merchant API или зарезервированных в URL-адресе символов, вы можете использовать обычный формат без кодирования.

  • Для обеспечения согласованного и корректного анализа мы рекомендуем использовать кодировку base64url без дополнения для всех названий товаров.

• Удаление налоговой информации на уровне продукта: taxes и taxCategory .

• Product.attributes переименовано : Поле Product.attributes переименовано в Product.productAttributes .

• Удаление информации о налогах на уровне продукта: поля taxes и taxCategory были удалены из объекта Product.productAttributes . Дополнительную информацию о налогах см. в справочной статье Google Merchant Center .

• Изменения в поле GTIN: Поле gtin в объекте Product.productAttributes переименовано в gtins , чтобы лучше отразить возможность хранения нескольких значений. Поле gtin в объекте OrderTrackingSignals.lineItemDetails теперь является array и также переименовано в gtins .

• Удаление поля «Канал»: Поле channel удалено из товаров, полей ввода данных о товарах и источников данных. Введено новое логическое поле legacyLocal , позволяющее четко обозначать товары, продаваемые исключительно в физических магазинах. Примечание: Поле legacyLocal является вспомогательным полем, призванным облегчить миграцию, и в конечном итоге будет устарело, как только методы онлайн- и локального маркетинга станут полностью ориентированы на единый источник данных о товарах. Дополнительную информацию см. в таблице в следующем разделе.

• Новые поля для региональных и локальных характеристик запасов :

  • Все поля объекта RegionalInventory кроме name , account и region , теперь заключены в новый объект под названием regionalInventoryAttributes . Например, атрибут RegionalInventory.price теперь находится в объекте RegionalInventory.regionalInventoryAttributes.price .
  • Все поля LocalInventory кроме name , account и storeCode , теперь заключены в новый объект под названием localInventoryAttributes . Например, атрибут LocalInventory.price теперь находится в объекте LocalInventory.localInventoryAttributes.price .

• Удаление поля customAttributes из региональных и локальных инвентарных списков: Поле customAttributes было удалено из ресурсов RegionalInventory и LocalInventory .

• Улучшено создание учетных записей: из запроса CreateAndConfigureAccountRequest удалено избыточное поле users . Используйте поле "Единственный user для связывания первоначального пользователя с новой учетной записью.

• Некоторые типы атрибутов были изменены со строк на перечисления: некоторые поля в ресурсах Product и Inventory с определенным коротким списком значений были изменены со string типа на тип enum для улучшения проверки данных (например, поле Product.ProductAttributes.condition теперь является enum ).

• Метод обновления политики возврата в режиме онлайн удален: метод onlineReturnPolicy.update удален в v1 Вместо него создавайте политику возврата в режиме онлайн, используя метод onlineReturnPolicy.create .

Как осуществить миграцию

Выпуск v1beta API для продавцов планируется завершить 28 февраля 2026 года. Более подробную информацию о графике прекращения поддержки см. в руководстве по версионированию API для продавцов .

• Первым шагом при миграции является одноразовая регистрация разработчика (см. раздел «Регистрация разработчика »). Перед началом работы любых методов v1 необходимо вызвать метод registerGcp для каждого проекта Google Cloud, используемого для аутентификации.

• Независимо от способа вызова API (с помощью REST, gRPC или клиентских библиотек ), миграция может осуществляться поэтапно. Это означает, что вы можете обновлять и мигрировать свой код по одному API за раз (например, перенести API Products на v1 , сохранив API Accounts на v1beta ), не обновляя всю интеграцию сразу.

Подробные изменения полей

В этой таблице представлено подробное сравнение полей, изменившихся между версиями v1beta и v1 .