Przejście z Content API for Shopping na Merchant API

W tym przewodniku znajdziesz informacje o procesie migracji z Content API for Shopping do Merchant API do zarządzania danymi firmy.

Z tego przewodnika dowiesz się, jak przeprowadzić migrację z dotychczasowej implementacji Content API for Shopping do Merchant API. Więcej informacji o Merchant API i jego interfejsach podrzędnych znajdziesz w artykule Projekt Merchant API.

Rozpocznij

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

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

Aby korzystać z Merchant API, musisz połączyć konto Merchant Center z projektem Google Cloud za pomocą metody rejestracji dewelopera w ten 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 przepływów pracy w Merchant Center oraz oferuje większe możliwości niż Content API for Shopping.

Kluczowe przypadki użycia:

  • Automatyczne zarządzanie kontami
  • Automatyczne zarządzanie produktami
  • Automatyczne zarządzanie asortymentem
  • Raportowanie niestandardowe

Główne obszary wymagające poprawy:

Co się zmieniło:

  • Maksymalna liczba pageSize wzrosła z 250 do 1000 wierszy na wywołanie interfejsu API.
  • Usunięto opóźnienie, które występowało w przypadku wstawiania produktów, promocji, opinii o produktach i opinii o sprzedawcach po utworzeniu DataSources.

Co będzie dalej:

  • Wprowadzenie zaktualizowanej definicji parametru clickPotentialRank w tabeli productView w sekcji Interfejs API do raportowania: * Ranking produktów na podstawie parametru clickPotential jest normalizowany do wartości z zakresu od 1 do 1000.
    • Produkty z niskim wskaźnikiem clickPotentialRank nadal mają największy potencjał kliknięć spośród produktów sprzedawcy, które spełniają warunki zapytania. Jest to zmiana, która nie powoduje przerwania działania usługi i może zostać wprowadzona 1 lipca 2025 r.
  • AccountIdAlias w zasobie AccountRelationship umożliwia lepsze zarządzanie złożonymi strukturami kont. Na przykład platformy handlowe używają zdefiniowanego przez użytkownika aliasu zamiast wewnętrznego identyfikatora sprzedawcy, takiego jak identyfikator konta.

Obsługa gRPC

Interfejs 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 Merchant API wymagają gRPC.

Więcej informacji znajdziesz w omówieniu gRPC.

Zgodność

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

Interfejs Merchant API został zaprojektowany tak, aby współpracować z dotychczasowymi funkcjami Content API for Shopping.

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

Ulepszenia w porównaniu z Content API

Merchant API jest lepszy od Content API w tych obszarach:

Przyjrzyjmy się tym zmianom bliżej.

Wersje i interfejsy API podrzędne

W interfejsie Merchant API wprowadzono koncepcje wersjonowania i interfejsów API. Modułowa konstrukcja ułatwia korzystanie z interfejsu API, ponieważ pozwala skupić się na potrzebnych interfejsach API i ułatwia przyszłe migracje do nowszych wersji. Wersjonowanie będzie stosowane w przypadku adresów URL żądań.Strategia jest podobna do interfejsu Google Ads API.

Bardziej złożone żądania

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

Zasady AIP dotyczące identyfikatorów

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

Identyfikator {name} zawiera 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 symbolu {account} do odwoływania się do identyfikatora Merchant Center, a symbolu {product} do odwoływania się do identyfikatorów produktów.

Na przykład zaimplementuj metodę getName(), aby pobrać name z zasobu, i zapisz wynik jako zmienną zamiast samodzielnie tworzyć name na podstawie identyfikatorów sprzedawcy i zasobu.

Oto przykład użycia pola name w połączeniach:

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

Tabela pokazuje, jak zmienia się żądanie do interfejsu Content API for Shoppingproducts.get:

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 sekcji Zmiany identyfikatorów.

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

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

gdzie {name} równa się 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 Merchant API wygląda tak:

contentLanguage~feedLabel~offerId.

Pola nadrzędne w przypadku zasobów podrzędnych

W 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, w polu list metody parent podaj name produktu. 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 powinno wyglądać tak:

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

Element nadrzędny to accounts/{account}/products/{product}. Pamiętaj, ż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 wyliczenia

Używanie wspólnych wyliczeń zapewnia większą spójność.

Pole Destination.DestinationEnum określa platformy, na których mają być wyświetlane zasoby. DestinationEnum zawiera wszystkie dostępne wartości kierowania na miejsce docelowe i jest ujednolicona w różnych interfejsach API, np. w przypadku atrybutów promocji.

Pole ReportingContext.ReportingContextEnum reprezentuje kontekst, do którego odnoszą się problemy z kontem i produktami. To pole jest używane w różnych metodach raportowania (np. w przypadku IssueSeverityPerReportingContext).

Zgodność wsteczna

Gdy zaczniesz korzystać z Merchant API, dotychczasowa integracja z Content API for Shopping będzie działać bez przerw. Więcej informacji znajdziesz w artykule Zgodność.

Po przeniesieniu interfejsów API do interfejsu Merchant API zalecamy korzystanie z niego tylko w przypadku przeniesionych interfejsów API.

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

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

Jego zalety to:

Niestandardowe przetwarzanie wsadowe staje się wbudowanym przetwarzaniem wsadowym

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

Aby przyspieszyć migrację, zalecamy korzystanie z 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.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

Jeśli używasz customBatch w Content API i potrzebujesz tej funkcji w Merchant API, w opinii podaj powód.

Wyjątkowe funkcje

Przyszłe funkcje będą dostępne tylko w interfejsie Merchant API. (Będzie kilka wyjątków, np. specyfikacja rocznego pliku danych z 2025 roku).

Funkcje dostępne tylko w Merchant API to:

  • Reviews API. Używaj opinii, aby wdrażać oceny produktów i sklepów oraz nimi zarządzać. Więcej informacji znajdziesz w artykułach Opinie o sprzedawcy i Opinie o produkcie.
  • Powiadomienia: możesz zarejestrować się, aby otrzymywać powiadomienia push o zmianach w danych o produktach na koncie.

Cena

Oto zmiany, które wprowadziliśmy w pakiecie Merchant Common w przypadku Price:

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

Kwota Price jest teraz rejestrowana w mikrojednostkach, gdzie 1 milion mikrojednostek odpowiada standardowej jednostce waluty.

W Content API for Shopping 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. Format nadal jest zgodny ze standardem ISO 4217.

Najnowsze aktualizacje i ogłoszenia

Szczegółowe informacje o aktualizacjach znajdziesz w informacjach o wersji dotyczących poszczególnych interfejsów API. Aby otrzymywać regularne zbiorcze aktualizacje Merchant API, zapoznaj się z naszymi najnowszymi aktualizacjami.

Więcej szczegółów i informacji o interfejsie Merchant API znajdziesz w omówieniu na naszej stronie dla deweloperów oraz w przewodniku po migracji.

Szczegółowe informacje o Merchant API i jego interfejsach API znajdziesz w artykule Projekt Merchant API.

Wstecz
Quickstart
Dalej
Migrate accountstatuses to Account Issues