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

В этом руководстве описывается процесс миграции с Content API для интернет-магазина на Merchant API для управления бизнес-данными.

Вы можете использовать это руководство для миграции существующей реализации Content API для покупок на Merchant API . Для получения дополнительной информации о Merchant API и его под-API см. раздел «Проектирование Merchant API» .

Начать

Для начала использования Merchant API измените URL-адреса запросов на следующий формат:

https://merchantapi.googleapis.com/{SUB_API}/{VERSION}/{RESOURCE_NAME}:{METHOD}…

Для использования Merchant API необходимо связать свою учетную запись Merchant Center и свой проект Google Cloud, используя метод регистрации разработчика, следующим образом:

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/developerRegistration:registerGcp

{
  developer_email:"example-email@example.com"
}

Для получения более подробной информации см. краткое руководство и справочник по API для продавцов.

Улучшения в Content API для покупок.

API для продавцов позволяет автоматизировать и оптимизировать рабочие процессы в Merchant Center и предлагает расширенные возможности по сравнению с Content API для покупок.

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

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

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

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

  • Максимальный pageSize увеличен с 250 до 1000 строк на один вызов API.
  • Исправлена ​​задержка, существовавшая при добавлении товаров, проведении рекламных акций, написании отзывов о товарах и отзывах продавцов после создания DataSources .

Что нас ждёт:

  • Введено обновленное определение для clickPotentialRank в таблице productView в рамках под-API «Отчетность» : * Ранжирование товаров на основе clickPotential нормализовано до значений от 1 до 1000.
    • Товары с низким clickPotentialRank по-прежнему обладают наибольшим потенциалом кликов среди товаров продавца, соответствующих условиям поискового запроса. Это изменение не является критическим и может быть введено в действие 1 июля 2025 года.
  • Параметр AccountIdAlias ​​в ресурсе AccountRelationship позволяет лучше управлять сложными структурами учетных записей. Например, торговые площадки используют определяемый пользователем псевдоним вместо внутреннего идентификатора продавца, такого как идентификатор учетной записи.

поддержка gRPC

API для продавцов поддерживает gRPC и REST. Вы можете одновременно использовать gRPC для API продавцов и REST для API контента в разделе «Покупки».

Для работы клиентских библиотек Merchant API требуется gRPC.

Для получения более подробной информации см. обзор gRPC .

Совместимость

В этом руководстве описаны общие изменения, которые применяются ко всему API для продавцов.

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

Например, вы можете использовать API для управления товарными запасами продавцов совместно с существующей реализацией API для products для покупок версии 2.1. Вы можете использовать API для контента для покупок, чтобы загрузить новый локальный товар (который вы продаете в местном магазине), а затем использовать ресурс LocalInventory API для управления информацией о товаре в магазине.

Улучшения в отношении Content API

API для продавцов превосходит Content API в следующих областях:

Рассмотрим эти изменения более подробно.

Версионирование и под-API

Merchant API вводит концепции версионирования и под-API . Его модульная структура повышает удобство использования, позволяя сосредоточиться на необходимых под-API и упрощая будущую миграцию на более новые версии. Версионирование будет применяться к вашим URL-адресам запросов. Стратегия аналогична работе Google Ads API .

Более надёжные запросы

Для запросов к API продавца по URL-адресу требуется больше параметров. К ним относятся ресурс, версия, имя (идентификаторы) и метод (нестандартные методы). Подробнее об этом см. в разделе «Идентификаторы учетных записей и продуктов и примеры» .

Принципы AIP для идентификаторов

В то время как Content API для покупок использует идентификаторы для идентификации ресурсов (например, merchantId , productId ), Merchant API использует name идентификатор для соответствия AIP (см. принципы улучшения API ).

Идентификатор {name} включает идентификатор ресурса и его родительский элемент (или, возможно, несколько родительских элементов), так что {name} равен accounts/{account}/products/{product}

Все вызовы чтения и записи возвращают поле name в качестве идентификатора ресурса.

{name} также включает идентификаторы коллекций accounts/ и products/ .

В Merchant API используется {account} для обозначения идентификатора Merchant Center и {product} для обозначения идентификаторов товаров.

Например, реализуйте метод getName() для получения name из ресурса и сохраняйте результат в переменной, вместо того чтобы самостоятельно формировать name из идентификаторов продавца и ресурса.

Вот пример того, как использовать поле name в ваших звонках:

   POST https://merchantapi.googleapis.com/inventories/v1/{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/v1/{name}

Для получения более подробной информации ознакомьтесь с разделом «Изменения идентификатора» .

В качестве еще одного примера, получение товара с идентификатором en~US~1234 из Merchant Center с ID 4321 с помощью Merchant API будет выглядеть следующим образом:

    GET
    https://merchantapi.googleapis.com/products/v1/accounts/4321/products/online~en~US~1234

где {name} равно accounts/4321/products/en~US~1234 . Это новое поле name возвращается в качестве идентификатора ресурса для всех вызовов чтения и записи в Merchant API.

В Content API для покупок двоеточие (:) обозначает разделитель в названии товара, тогда как в Merchant API эту функцию выполняет тильда (~). Идентификатор Merchant API не содержит части, channel .

Например, идентификатор товара в Content API для покупок:

channel:contentLanguage:feedLabel:offerId .

В API для продавцов это выглядит следующим образом:

contentLanguage~feedLabel~offerId .

Родительские поля для дочерних ресурсов

В Merchant API все дочерние ресурсы имеют поле parent . Вы можете использовать поле parent для указания {name} ресурса, в который нужно вставить дочерний ресурс, вместо передачи всего родительского ресурса. Вы также можете использовать поле parent со list

Например, чтобы вывести список локальных запасов для заданного товара, укажите name товара в поле parent " метода list . В этом случае заданный product является parent для возвращаемых ресурсов LocalInventory .

    GET
    https://merchantapi.googleapis.com/inventories/v1/{parent}/localInventories

Для получения всех локальных данных о наличии товара en~US~1234' и учетной записи 4321 запрос будет выглядеть следующим образом:

    GET
    https://merchantapi.googleapis.com/inventories/v1/accounts/4321/products/online~en~US~1234/localInventories</code>

Родительским ресурсом является accounts/{account}/products/{product} . Обратите внимание, что в данном случае ресурс localInventories имеет двух родителей, включенных в идентификатор имени ( accounts/ и products/ ), поскольку account является родительским ресурсом продукта.

Общие перечисления

Использование общих перечислений обеспечивает большую согласованность.

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

Поле ReportingContext.ReportingContextEnum представляет контекст, к которому относятся ваши проблемы с учетной записью и продуктом. Это поле используется во всех методах формирования отчетов (например, для IssueSeverityPerReportingContext ).

Обратная совместимость

При начале использования Merchant API существующая интеграция Content API for Shopping продолжит работать без перебоев. Для получения дополнительной информации см. раздел «Совместимость» .

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

Доступность удаленного вызова процедур (gRPC)

gRPC — это новый рекомендуемый способ интеграции с API продавцов.

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

Пользовательская пакетная обработка становится встроенной пакетной обработкой.

Пакетная обработка работает эффективнее при использовании асинхронных вызовов. Узнайте больше об использовании параллельных вызовов для пакетной обработки в Merchant API и о том, как рефакторизовать код для параллельных запросов .

Для ускорения миграции мы рекомендуем использовать клиентские библиотеки .

API для продавцов не поддерживает метод customBatch представленный в Content 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.v1.Availability;
import com.google.shopping.merchant.products.v1.Condition;
import com.google.shopping.merchant.products.v1.InsertProductInputRequest;
import com.google.shopping.merchant.products.v1.ProductAttributes;
import com.google.shopping.merchant.products.v1.ProductInput;
import com.google.shopping.merchant.products.v1.ProductInputsServiceClient;
import com.google.shopping.merchant.products.v1.ProductInputsServiceSettings;
import com.google.shopping.merchant.products.v1.Shipping;
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();

    ProductAttributes attributes =
        ProductAttributes.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(Availability.IN_STOCK)
            .setCondition(Condition.NEW)
            .setGoogleProductCategory("Media > Books")
            .addGtins("9780007350896")
            .addShipping(shipping)
            .addShipping(shipping2)
            .build();

    return ProductInput.newBuilder()
        .setContentLanguage("en")
        .setFeedLabel("CH")
        .setOfferId(generateRandomString())
        .setProductAttributes(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 год .)

В число функций, доступных исключительно через Merchant API, входят:

  • API для отзывов. Используйте отзывы для внедрения и управления рейтингами ваших товаров и магазина. Для получения дополнительной информации см. разделы «Отзывы продавцов» и «Отзывы о товарах» .
  • Уведомления : Подпишитесь на получение push-уведомлений об изменениях в данных о товарах в вашей учетной записи.

Цена

Вот что изменилось для Price в пакете Merchant Common:

API контента для покупок API для продавцов
Поле «Сумма» value:string amountMicros:int64
Поле «Валюта» currency:string currencyCode:string

Сумма Price теперь указывается в микросах, где 1 миллион микрос эквивалентен стандартной единице вашей валюты.

В Content API для покупок Price представляла собой десятичное число в виде строки.

Название поля amount изменилось с value на amountMicros

Название поля «Валюта» изменилось с currency на currencyCode . Формат по-прежнему соответствует стандарту ISO 4217 .

Последние обновления и объявления

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

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

Подробную информацию о Merchant API и его под-API см. в разделе «Дизайн Merchant API» .

Назад
MCP Server
Далее
Migrate accountstatuses to Account Issues