В этом руководстве описывается процесс миграции с Content API для покупок на Merchant API для управления бизнес-данными.
Вы можете использовать это руководство для переноса существующей реализации Content API for Shopping в Merchant API . Подробнее о Merchant API и его подAPI см. в разделе «Проектирование Merchant API» .
Начать
Чтобы начать использовать API Merchant, измените URL-адреса запросов на следующий формат:
https://merchantapi.googleapis.com/{SUB_API}/{VERSION}/{RESOURCE_NAME}:{METHOD}…
Чтобы использовать API Merchant, необходимо связать свою учетную запись Merchant Center и свой проект Google Cloud, используя метод регистрации разработчика, как указано ниже:
POST https://merchantapi.googleapis.com/accounts/v1beta/accounts/{ACCOUNT_ID}/developerRegistration:registerGcp
{
developer_email:"example-email@example.com"
}
Более подробную информацию см. в кратком руководстве и справочнике API торговца.
Ознакомьтесь с последними обновлениями в Merchant API (бета).
Улучшения по сравнению с Content API для покупок
API Merchant позволяет автоматизировать и оптимизировать рабочие процессы в Merchant Center и предлагает расширенные возможности по сравнению с API Content for Shopping.
Основные варианты использования:
- Автоматизированное управление счетами
- Автоматизированное управление продуктами
- Автоматизированное управление запасами
- Пользовательская отчетность
Основные области улучшения:
- Суб-API с новыми функциями, включая:
- Отслеживание заказов поддерживает историю отслеживания бизнес-заказов, предоставляя клиентам точные и достоверные оценки доставки. Сигналы также позволяют создавать расширенные листинги с бесплатной и быстрой доставкой .
- Решение проблем обеспечивает доступ к диагностическому контенту и действиям по поддержке так же, как это доступно в пользовательском интерфейсе Merchant Center.
- Product Studio (ALPHA) использует genAI для генерации и оптимизации названий и описаний продуктов. Для запроса доступа необходимо подписать эту форму.
- Новые ресурсы в под-API «Учетные записи» .
-
OmnichannelSettings
управляет конфигурацией учетной записи для многоканального обслуживания, например, бесплатных местных объявлений (FLL) и рекламы местного инвентаря (LIA). -
LfpProviders
подключается к партнерам Local Feeds Partnership (LFP) для получения данных об инвентаризации. -
GbpAccounts
подключается к аккаунту Google Business Profile для получения данных о локальном магазине. -
OnlineReturnPolicy
предоставляет возможность создавать, удалять и обновлять ваши онлайн-политики.
- Новые методы для инвентаризации, данных о продуктах и других API, включая:
- Новый метод в под-API «Продукты» .
-
ProductsUpdate
позволяет обновлять отдельные продукты без необходимости предоставления всех полей, требуемых дляProductInput
.
- Возможность создания не только первичных источников данных, но и множественных источников данных, таких как:
- Вводит загрузку обзоров продуктов и обзоров продавцов
- С помощью API Merchant вы можете включить уведомления об изменениях данных аккаунта.
Что изменилось:
- Максимальный
pageSize
увеличился с 250 до 1000 строк на один вызов API. - Устранена задержка, существовавшая при добавлении товаров, рекламных акций, обзоров товаров и обзоров продавцов после создания
DataSources
.
Что нас ждет:
- Устаревание и будущее удаление поля канала для
DataSources
и продуктов. - Запуск обновленного определения
clickPotentialRank
в таблицеproductView
в подAPI Reporting : * Рейтинг продуктов на основеclickPotential
нормализован до значений от 1 до 1000.- Товары с низким
clickPotentialRank
по-прежнему имеют самый высокий кликабельный потенциал среди товаров продавца, соответствующих условиям поискового запроса. Это некритическое изменение, которое может быть внедрено 1 июля 2025 года.
- Товары с низким
-
AccountIdAlias
в ресурсеAccountRelationship
позволяет эффективнее управлять сложными структурами аккаунтов. Например, торговые площадки используют определяемый пользователем псевдоним вместо внутреннего идентификатора продавца, например, идентификатора аккаунта.
поддержка gRPC
API Merchant поддерживает gRPC и REST. Вы можете одновременно использовать gRPC для API Merchant и REST для API Content for Shopping.
Клиентские библиотеки API Merchant требуют gRPC.
Более подробную информацию см. в обзоре gRPC .
Совместимость
В этом руководстве описываются общие изменения, которые применяются ко всему API торговца.
API-интерфейс продавца разработан для работы вместе с существующими функциями API-интерфейса контента для покупок.
Например, вы можете использовать API Merchant Inventories вместе с существующей реализацией products
Content API for Shopping v2.1. Вы можете использовать Content API for Shopping для загрузки нового локального товара (который вы продаёте в местном магазине), а затем использовать ресурс LocalInventory
API Merchant Inventories для управления информацией об этом товаре в магазине.
Улучшения по сравнению с Content API
API торговца превосходит API контента в следующих областях:
- Суб-API с новыми функциями для вашей уникальной интеграции
- Новые методы для инвентаризации, данных о продуктах и других API
- Возможность создания не только первичных источников данных, но и множественных источников данных, таких как:
- Вводит загрузку обзоров продуктов и обзоров продавцов
- С помощью Merchant API вы можете включить уведомления об изменениях данных аккаунта.
- Вводит возможность фильтрации для ресурса «Учетные записи»
Рассмотрим эти изменения более подробно.
Версионирование и под-API
API Merchant представляет концепции управления версиями и под-API . Модульная структура упрощает использование, позволяя сосредоточиться на необходимых под-API и упростить будущие миграции на новые версии. Управление версиями будет применяться к URL-адресам ваших запросов. Стратегия аналогична работе с API Google Ads .
Более надежные запросы
Для URL-запросов Merchant API требуется больше параметров для вызова Merchant API. К ним относятся ресурс, версия, имя (идентификаторы) и метод (нестандартные методы). Подробнее об этом см. в разделе «Идентификаторы аккаунтов и продуктов и примеры» .
Принципы AIP для идентификаторов
В то время как Content API for Shopping использует идентификаторы для идентификации ресурсов (например, merchantId
, productId
), Merchant API использует идентификатор name
для соответствия AIP (см. Принципы улучшения API ).
Идентификатор {name}
включает идентификатор ресурса и его родителя (или потенциально нескольких родителей), так что {name}
равно accounts/{account}/products/{product}
Все вызовы чтения и записи возвращают поле name
в качестве идентификатора ресурса.
{name}
также включает идентификаторы коллекции accounts/
и products/
.
API Merchant использует {account}
для ссылки на идентификатор Merchant Center и {product}
для ссылки на идентификаторы продуктов.
Например, реализуйте метод getName()
для извлечения name
из ресурса и сохраните вывод как переменную вместо того, чтобы самостоятельно создавать name
из идентификаторов продавца и ресурса.
Вот пример того, как использовать поле name
в вызовах:
POST https://merchantapi.googleapis.com/inventories/v1beta/{PARENT}/regionalInventories:insert
В таблице показано, как изменяется запрос Content API for Shopping products.get
:
API контента для покупок | API торговца |
---|---|
GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} | GET https://merchantapi.googleapis.com/products/v1beta/{name} |
Более подробную информацию см. в разделе Изменения идентификатора .
В качестве другого примера, извлечение продукта с идентификатором online~en~US~1234
из Merchant Center ID 4321
с помощью Merchant API будет выглядеть следующим образом:
GET
https://merchantapi.googleapis.com/products/v1beta/accounts/4321/products/online~en~US~1234
где {name}
равно accounts/4321/products/online~en~US~1234
. Это новое поле имени возвращается как идентификатор ресурса для всех вызовов чтения и записи в API продавца.
В Content API for Shopping двоеточие (:) обозначает разделитель в названии товара, тогда как в Merchant API эту функцию выполняет тильда (~).
Например, идентификатор продукта в Content API для покупок:
channel:contentLanguage:feedLabel:offerId
.
в API Merchant Center становится следующим:
channel~contentLanguage~feedLabel~offerId
.
Родительские поля для дочерних ресурсов
В Merchant API все дочерние ресурсы имеют parent
поле. Вы можете использовать parent
поле, чтобы указать {name}
ресурса, в который нужно вставить дочерний ресурс, вместо того, чтобы передавать весь родительский ресурс. Вы также можете использовать parent
поле со list
Например, чтобы получить список локальных запасов для заданного товара, укажите name
товара в поле parent
метода list
. В этом случае данный product
будет parent
для возвращаемых ресурсов LocalInventory .
GET
https://merchantapi.googleapis.com/inventories/v1beta/{parent}/localInventories
Чтобы получить все локальные запасы для продукта online~en~US~1234'
и счета 4321
запрос будет выглядеть так:
GET
https://merchantapi.googleapis.com/inventories/v1beta/accounts/4321/products/online~en~US~1234/localInventories</code>
Родительский элемент — accounts/{account}/products/{product}
. Обратите внимание, что в этом случае у ресурса localInventories есть два родительских элемента, включённых в идентификатор имени ( accounts/
и products/
), поскольку счёт является родительским элементом ресурса product .
Общие перечисления
Использование общих перечислений обеспечивает большую согласованность.
Поле Destination.DestinationEnum
определяет области отображения ваших ресурсов. DestinationEnum
содержит список всех доступных значений для таргетинга на пункт назначения и унифицировано для всех под-API, например, для атрибутов рекламных акций .
Поле ReportingContext.ReportingContextEnum
представляет контекст, к которому относятся проблемы вашей учётной записи и продукта. Это поле используется во всех методах отчётности (например, для IssueSeverityPerReportingContext
).
Обратная совместимость
После начала использования Merchant API ваша существующая интеграция с Content API for Shopping продолжит работать без перебоев. Подробнее см. в разделе «Совместимость» .
После переноса ваших суб-API в Merchant API мы рекомендуем вам использовать для перенесенных суб-API только Merchant API.
Доступность удаленного вызова процедур (gRPC)
gRPC — новый рекомендуемый способ интеграции с API торговца.
К его преимуществам можно отнести следующее:
- Независимый от языка
- Опирается на буферы протокола
Использует HTTP/2 для предоставления высокопроизводительных масштабируемых решений ( справочник RPC )
Если вы используете наши клиентские библиотеки или примеры кода , gRPC является транспортным механизмом по умолчанию.
Более подробную информацию о gRPC можно найти в следующих источниках:
Индивидуальное дозирование становится встроенным дозированием
Пакетирование выполняется эффективнее при использовании асинхронных вызовов. Узнайте больше об использовании параллельных вызовов для пакетирования в Merchant API и о рефакторинге кода для одновременных запросов .
Чтобы ускорить миграцию, мы рекомендуем клиентские библиотеки .
API продавца не поддерживает метод customBatch
, представленный в API контента для покупок. См. раздел «Отправка нескольких запросов одновременно или асинхронное выполнение вызовов».
В следующем примере Java показано, как вставить входные данные о продукте.
import com.google.api.core.ApiFuture;
import com.google.api.core.ApiFutureCallback;
import com.google.api.core.ApiFutures;
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.shopping.merchant.products.v1beta.Attributes;
import com.google.shopping.merchant.products.v1beta.InsertProductInputRequest;
import com.google.shopping.merchant.products.v1beta.ProductInput;
import com.google.shopping.merchant.products.v1beta.ProductInputsServiceClient;
import com.google.shopping.merchant.products.v1beta.ProductInputsServiceSettings;
import com.google.shopping.merchant.products.v1beta.Shipping;
import com.google.shopping.type.Channel.ChannelEnum;
import com.google.shopping.type.Price;
import java.util.ArrayList;
import java.util.List;
import java.util.Random;
import java.util.stream.Collectors;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;
/** This class demonstrates how to insert a product input */
public class InsertProductInputAsyncSample {
private static String getParent(String accountId) {
return String.format("accounts/%s", accountId);
}
private static String generateRandomString() {
String characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
Random random = new Random();
StringBuilder sb = new StringBuilder(8);
for (int i = 0; i < 8; i++) {
sb.append(characters.charAt(random.nextInt(characters.length())));
}
return sb.toString();
}
private static ProductInput createRandomProduct() {
Price price = Price.newBuilder().setAmountMicros(33_450_000).setCurrencyCode("USD").build();
Shipping shipping =
Shipping.newBuilder().setPrice(price).setCountry("GB").setService("1st class post").build();
Shipping shipping2 =
Shipping.newBuilder().setPrice(price).setCountry("FR").setService("1st class post").build();
Attributes attributes =
Attributes.newBuilder()
.setTitle("A Tale of Two Cities")
.setDescription("A classic novel about the French Revolution")
.setLink("https://exampleWebsite.com/tale-of-two-cities.html")
.setImageLink("https://exampleWebsite.com/tale-of-two-cities.jpg")
.setAvailability("in stock")
.setCondition("new")
.setGoogleProductCategory("Media > Books")
.addGtin("9780007350896")
.addShipping(shipping)
.addShipping(shipping2)
.build();
return ProductInput.newBuilder()
.setChannel(ChannelEnum.ONLINE)
.setContentLanguage("en")
.setFeedLabel("CH")
.setOfferId(generateRandomString())
.setAttributes(attributes)
.build();
}
public static void asyncInsertProductInput(Config config, String dataSource) throws Exception {
// Obtains OAuth token based on the user's configuration.
GoogleCredentials credential = new Authenticator().authenticate();
// Creates service settings using the credentials retrieved above.
ProductInputsServiceSettings productInputsServiceSettings =
ProductInputsServiceSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credential))
.build();
// Creates parent to identify where to insert the product.
String parent = getParent(config.getAccountId().toString());
// Calls the API and catches and prints any network failures/errors.
try (ProductInputsServiceClient productInputsServiceClient =
ProductInputsServiceClient.create(productInputsServiceSettings)) {
// Creates five insert product input requests with random product IDs.
List<InsertProductInputRequest> requests = new ArrayList<>(5);
for (int i = 0; i < 5; i++) {
InsertProductInputRequest request =
InsertProductInputRequest.newBuilder()
.setParent(parent)
// You can only insert products into datasource types of Input "API", and of Type
// "Primary" or "Supplemental."
// This field takes the `name` field of the datasource.
.setDataSource(dataSource)
// If this product is already owned by another datasource, when re-inserting, the
// new datasource will take ownership of the product.
.setProductInput(createRandomProduct())
.build();
requests.add(request);
}
System.out.println("Sending insert product input requests");
List<ApiFuture<ProductInput>> futures =
requests.stream()
.map(
request ->
productInputsServiceClient.insertProductInputCallable().futureCall(request))
.collect(Collectors.toList());
// Creates callback to handle the responses when all are ready.
ApiFuture<List<ProductInput>> responses = ApiFutures.allAsList(futures);
ApiFutures.addCallback(
responses,
new ApiFutureCallback<List<ProductInput>>() {
@Override
public void onSuccess(List<ProductInput> results) {
System.out.println("Inserted products below");
System.out.println(results);
}
@Override
public void onFailure(Throwable throwable) {
System.out.println(throwable);
}
},
MoreExecutors.directExecutor());
} catch (Exception e) {
System.out.println(e);
}
}
public static void main(String[] args) throws Exception {
Config config = Config.load();
// Identifies the data source that will own the product input.
String dataSource = "accounts/" + config.getAccountId() + "/dataSources/{datasourceId}";
asyncInsertProductInput(config, dataSource);
}
}
Если вы используете customBatch
в Content API и вам нужна эта функция для Merchant API, сообщите нам в отзыве , почему.
Эксклюзивные функции
Будущие функции появятся только в Merchant API. (Будут некоторые исключения, такие как ежегодная спецификация фида за 2025 год .)
Эксклюзивные функции API Merchant включают:
- API отзывов. Используйте отзывы для создания и управления рейтингами товаров и магазинов. Подробнее см. в разделах «Отзывы продавцов» и «Отзывы о товарах» .
- Уведомления : зарегистрируйтесь, чтобы получать push-уведомления об изменениях в данных о продуктах вашей учетной записи.
Цена
Вот что изменилось для Price
в пакете Merchant Common:
API контента для покупок | API торговца | |
---|---|---|
Поле суммы | value:string | amountMicros:int64 |
Валютное поле | currency:string | currencyCode:string |
Сумма Price
теперь указывается в микро, где 1 миллион микро эквивалентен стандартной единице вашей валюты.
В API контента для покупок Price
представляла собой десятичное число в виде строки.
Имя поля суммы изменилось с value
на amountMicros
Название поля валюты изменено с currency
на currencyCode
. Формат по-прежнему соответствует ISO 4217 .
Последние обновления и объявления
Более подробную информацию об обновлениях см. в примечаниях к выпуску для каждого под-API. Более регулярные агрегированные обновления API Merchant можно найти в наших последних обновлениях .
Для получения более подробной информации и дополнительных сведений о Merchant API ознакомьтесь с обзором сайта для разработчиков и общим руководством по миграции.
Подробную информацию о Merchant API и его подAPI см. в разделе «Проектирование API Merchant» .