Przejście z Content API for Shopping na Merchant API

Ten przewodnik wyjaśnia proces migracji z Content API for Shopping na Merchant API do zarządzania danymi firmowymi.

Z tego przewodnika dowiesz się, jak przenieść dotychczasową implementację Content API for Shopping do Merchant API. Więcej informacji o Merchant API i jego podrzędnych interfejsach API znajdziesz w artykule Projekt Merchant API.

Rozpocznij

Aby zacząć korzystać z interfejsu Merchant API, zmień adresy URL żądań na ten format:

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

Aby korzystać z interfejsu Merchant API, musisz połączyć konto Merchant Center z projektem Google Cloud, korzystając z metody rejestracji dewelopera w następujący sposób:

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

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

Więcej informacji znajdziesz w krótkim przewodniku i dokumentacji Merchant API.

Ulepszenia w porównaniu z Content API for Shopping

Interfejs Merchant API umożliwia automatyzację i usprawnienie procesów w Merchant Center oraz oferuje ulepszone funkcje w porównaniu z Content API for Shopping.

Najważniejsze przypadki użycia:

  • Automatyczne zarządzanie kontem
  • Automatyczne zarządzanie produktami
  • Zautomatyzowane zarządzanie asortymentem
  • Raportowanie niestandardowe

Główne obszary do poprawy:

Co się zmieniło

  • Maksymalna wartość pageSize została zwiększona z 250 do 1000 wierszy na wywołanie interfejsu API.
  • Naprawiliśmy opóźnienie, które występowało w przypadku dodawania produktów, promocji, opinii o produktach i opinii o sprzedawcy po utworzeniu DataSources.
  • Wprowadzenie zaktualizowanej definicji clickPotentialRank w tabeli productView w podrzędnym interfejsie API do raportowania:
    • Ranking produktów na podstawie danych clickPotential jest normalizowany do wartości od 1 do 1000.
  • Pole AccountIdAlias w zasobie AccountRelationship umożliwia lepsze zarządzanie złożonymi strukturami kont. Na przykład platformy handlowe używają aliasu zdefiniowanego przez użytkownika zamiast wewnętrznego identyfikatora sprzedawcy, takiego jak identyfikator konta.

Obsługa gRPC

Merchant API obsługuje gRPC i REST. Możesz jednocześnie używać gRPC w przypadku Merchant API i REST w przypadku Content API for Shopping.

Biblioteki klienta interfejsu Merchant API wymagają gRPC.

Więcej informacji znajdziesz w artykule Omówienie gRPC.

Zgodność

Ten przewodnik opisuje ogólne zmiany, które dotyczą całego interfejsu Merchant API.

Interfejs Merchant API został zaprojektowany tak, aby działał razem z istniejącymi funkcjami Content API for Shopping.

Możesz na przykład używać interfejsu Merchant Inventories API razem z obecną implementacją Content API for Shopping w wersji 2.1products. Możesz użyć Content API for Shopping, aby przesłać nowy produkt lokalny (który sprzedajesz w sklepie lokalnym), a następnie użyć zasobu LocalInventory interfejsu Merchant Inventories API, aby zarządzać informacjami o tym produkcie w sklepie.

Ulepszenia strukturalne w Content API

Interfejs Merchant API jest lepszy od Content API w tych obszarach:

Przyjrzyjmy się tym zmianom bardziej szczegółowo.

Obsługa wersji i podrzędne interfejsy API

Interfejs Merchant API wprowadza pojęcia wersjonowania i podrzędnych interfejsów API. Modułowa konstrukcja ułatwia korzystanie z niego, ponieważ pozwala skupić się na potrzebnych podrzędnych interfejsach API i ułatwia przyszłe migracje do nowszych wersji. Wersje będą stosowane w adresach URL żądań. Strategia jest podobna do interfejsu Google Ads API.

Bardziej rozbudowane żądania

Żądania adresów URL interfejsu Merchant API wymagają więcej parametrów do wywołania interfejsu Merchant API. Obejmuje to zasób, wersję, nazwę (identyfikatory) i metodę (metody niestandardowe). Więcej informacji znajdziesz w artykule Identyfikatory kont i produktów oraz w przykładach.

Zasady AIP dotyczące identyfikatorów

Content API for Shopping używa identyfikatorów do identyfikowania zasobów (np. merchantId, productId), natomiast Merchant API używa identyfikatora name, aby zachować zgodność z AIP (patrz zasady ulepszania interfejsu API).

Identyfikator {name} obejmuje identyfikator zasobu i jego element nadrzędny (lub potencjalnie wiele elementów nadrzędnych), tak że {name} jest równe accounts/{account}/products/{product}

Wszystkie wywołania odczytu i zapisu zwracają pole name jako identyfikator zasobu.

{name} zawiera też identyfikatory kolekcji accounts/ i products/.

Interfejs Merchant API używa {account} do odwoływania się do identyfikatora w Merchant Center i {product} do odwoływania się do identyfikatorów produktów.

Możesz na przykład wdrożyć metodę getName(), aby pobrać name z zasobu i zapisać dane wyjściowe jako zmienną, zamiast samodzielnie tworzyć name na podstawie identyfikatorów sprzedawcy i zasobu.

Oto przykład użycia pola name w wywołaniach:

   POST https://merchantapi.googleapis.com/inventories/v1/{PARENT}/regionalInventories:insert

Tabela pokazuje, jak zmienia się żądanie products.get Content API for Shopping:

Content API for Shopping Merchant API
GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} GET https://merchantapi.googleapis.com/products/v1/{name}

Więcej informacji znajdziesz w artykule Zmiany dotyczące identyfikatorów.

Inny przykład: pobieranie produktu o identyfikatorze en~US~1234 z identyfikatora w Merchant Center 4321 za pomocą interfejsu Merchant API wyglądałoby tak:

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

gdzie {name} to accounts/4321/products/en~US~1234. To nowe pole nazwy jest zwracane jako identyfikator zasobu we wszystkich wywołaniach odczytu i zapisu w Merchant API.

W Content API for Shopping dwukropek (:) oznacza separator w nazwie produktu, natomiast w Merchant API tę funkcję pełni tylda (~). Identyfikator interfejsu Merchant API nie zawiera części channel.

Na przykład identyfikator produktu w Content API for Shopping:

channel:contentLanguage:feedLabel:offerId.

w interfejsie Merchant API będzie wyglądać tak:

contentLanguage~feedLabel~offerId.

Pola nadrzędne zasobów podrzędnych

W interfejsie Merchant API wszystkie zasoby podrzędne mają pole parent. Zamiast przekazywać cały zasób nadrzędny, możesz użyć pola parent, aby określić {name} zasobu, do którego chcesz wstawić zasób podrzędny. Możesz też użyć pola parent z list.

Aby na przykład wyświetlić lokalny asortyment danego produktu, podaj name produktu w polu parent metody list. W tym przypadku podany product to parent zwróconych zasobów LocalInventory.

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

Aby pobrać wszystkie lokalne asortymenty dla produktu en~US~1234 i konta 4321, żądanie będzie wyglądać tak:

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

Rodzic: accounts/{account}/products/{product}. Zwróć uwagę, że w tym przypadku zasób localInventories ma 2 elementy nadrzędne uwzględnione w identyfikatorze nazwy (accounts/ i products/), ponieważ konto jest elementem nadrzędnym zasobu produktu.

Typowe typy wyliczeniowe

Używanie typów wyliczeniowych zapewnia większą spójność.

Pole Destination.DestinationEnum określa platformy, na których mają być wyświetlane Twoje zasoby. DestinationEnum zawiera listę wszystkich dostępnych wartości kierowania na miejsce docelowe i jest ujednolicony we wszystkich podrzędnych interfejsach API, na przykład w przypadku atrybutów promocji.

Pole ReportingContext.ReportingContextEnum reprezentuje kontekst, którego dotyczą problemy z kontem i informacje o produkcie. To pole jest używane w różnych metodach raportowania (np. w IssueSeverityPerReportingContext).

Zgodność wsteczna

Gdy zaczniesz korzystać z Merchant API, Twoja dotychczasowa integracja z Content API for Shopping będzie nadal działać bez zakłóceń. Więcej informacji znajdziesz w artykule na temat zgodności.

Po przeniesieniu podrzędnych interfejsów API do Merchant API zalecamy używanie tylko Merchant API w przypadku przeniesionych podrzędnych interfejsów API.

Dostępność zdalnego wywołania procedury (gRPC)

gRPC to nowy zalecany sposób integracji z Merchant API.

Jego zalety to:

Niestandardowe grupowanie staje się wbudowanym grupowaniem

Grupowanie działa wydajniej, gdy używasz wywołań asynchronicznych. Dowiedz się więcej o używaniu wywołań równoległych do grupowania w interfejsie Merchant API oraz o tym, jak refaktoryzować kod pod kątem żądań równoczesnych.

Aby przyspieszyć migrację, zalecamy użycie bibliotek klienta.

Interfejs Merchant API nie obsługuje metody customBatch dostępnej w Content API for Shopping. Zamiast tego zapoznaj się z artykułem Wysyłanie wielu żądań jednocześnie lub wykonuj wywołania asynchronicznie.

.

Poniższy przykład w języku Java pokazuje, jak wstawić dane wejściowe produktu:

   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.api.gax.grpc.ChannelPoolSettings;
import com.google.api.gax.grpc.InstantiatingGrpcChannelProvider;
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 a channel provider. This provider manages a pool of gRPC channels
    // to enhance throughput for bulk operations. Each individual channel in the pool
    // can handle up to approximately 100 concurrent requests.
    //
    // Channel: A single connection pathway to the service.
    // Pool: A collection of multiple channels managed by this provider.
    //   Requests are distributed across the channels in the pool.
    //
    // We recommend estimating the number of concurrent requests you'll make, divide by 50 (50%
    // utilization of channel capacity), and set the pool size to that number.
    InstantiatingGrpcChannelProvider channelProvider =
        InstantiatingGrpcChannelProvider.newBuilder()
            .setChannelPoolSettings(ChannelPoolSettings.staticallySized(30))
            .build();

    // Creates service settings using the credentials retrieved above.
    ProductInputsServiceSettings productInputsServiceSettings =
        ProductInputsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .setTransportChannelProvider(channelProvider)
            .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);
  }
}

Jeśli używasz customBatch w Content API i potrzebujesz tej funkcji w Merchant API, poinformuj nas o tym w opinii.

Wyjątkowe funkcje

Przyszłe funkcje będą dostępne tylko w Merchant API. (Będzie kilka wyjątków, takich jak specyfikacja pliku danych na 2025 r.).

Funkcje dostępne wyłącznie w Merchant API obejmują:

  • Reviews API. Użyj opinii, aby wdrożyć oceny produktów i sklepu oraz nimi zarządzać. Więcej informacji znajdziesz w artykułach Opinie o sprzedawcy i Opinie o produktach.
  • Powiadomienia: zarejestruj się, aby otrzymywać powiadomienia push o zmianach na koncie i w danych o produktach.

Cena

Oto co się zmieniło w przypadku Price w pakiecie Merchant Common:

Content API for Shopping Merchant API
Pole kwoty value:string amountMicros:int64
Pole waluty currency:string currencyCode:string

Kwota Price jest teraz rejestrowana w mikrowalucie, gdzie 1 milion mikrowaluty odpowiada standardowej jednostce Twojej waluty.

W Content API for Shopping parametr Price był liczbą dziesiętną w postaci ciągu znaków.

Nazwa pola kwoty została zmieniona z value na amountMicros

Nazwa pola waluty została zmieniona z currency na currencyCode. Formatem nadal jest ISO 4217.

Najnowsze informacje i ogłoszenia

Bardziej szczegółowe informacje znajdziesz w informacjach o wersji poszczególnych podrzędnych interfejsów API. Aby otrzymywać bardziej regularne, zbiorcze aktualizacje Merchant API, zapoznaj się z najnowszymi aktualizacjami.

Aby dowiedzieć się więcej o Merchant API, zapoznaj się z omówieniem na naszej stronie dla deweloperów i ogólnym przewodnikiem po migracji.

Szczegółowe informacje o interfejsie Merchant API i jego podrzędnych interfejsach API znajdziesz w artykule Projekt interfejsu Merchant API.

Wstecz
Manage and transition Google Cloud projects
Dalej
Start your migration