Миграция с Content API для покупок на Merchant API

В этом руководстве описывается процесс миграции с 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.

Основные варианты использования:

  • Автоматизированное управление счетами
  • Автоматизированное управление продуктами
  • Автоматизированное управление запасами
  • Пользовательская отчетность

Основные области улучшения:

Что изменилось:

  • Максимальный 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 и упростить будущие миграции на новые версии. Управление версиями будет применяться к 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 торговца.

К его преимуществам можно отнести следующее:

Индивидуальное дозирование становится встроенным дозированием

Пакетирование выполняется эффективнее при использовании асинхронных вызовов. Узнайте больше об использовании параллельных вызовов для пакетирования в 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);
  }
}
InsertProductInputAsyncSample.java

Если вы используете 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» .

Назад
Quickstart
Далее
Migrate from accountstatuses to Account Issues