Von der Content API for Shopping zur Merchant API migrieren

In diesem Leitfaden wird die Migration von der Content API for Shopping zur Merchant API für die Verwaltung von Geschäftsdaten beschrieben.

In diesem Leitfaden erfahren Sie, wie Sie Ihre bestehende Content API for Shopping-Implementierung zur Merchant API migrieren. Weitere Informationen zur Merchant API und ihren Unter-APIs finden Sie unter Merchant API-Design.

Jetzt starten

Wenn Sie die Merchant API verwenden möchten, ändern Sie Ihre Anfrage-URLs in das folgende Format:

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

Wenn Sie die Merchant API verwenden möchten, müssen Sie Ihr Merchant Center-Konto und Ihr Google Cloud-Projekt mit der Methode „Entwicklerregistrierung“ verknüpfen:

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

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

Weitere Informationen finden Sie in der Kurzanleitung und in der Referenz zur Merchant API.

Verbesserungen gegenüber der Content API for Shopping

Mit der Merchant API können Sie Workflows im Merchant Center automatisieren und optimieren. Außerdem bietet sie erweiterte Funktionen im Vergleich zur Content API for Shopping.

Gängige Anwendungsfälle:

  • Automatisierte Kontoverwaltung
  • Automatisierte Produktverwaltung
  • Automatisierte Inventarverwaltung
  • Benutzerdefinierte Berichte

Wichtige Bereiche mit Verbesserungspotenzial:

Änderungen

  • Die maximale pageSize wurde von 250 auf 1.000 Zeilen pro API-Aufruf erhöht.
  • Eine Verzögerung, die nach dem Erstellen von DataSources beim Einfügen von Produkten, Angeboten, Rezensionen und Händlerrezensionen auftrat, wurde behoben.
  • Einführung einer aktualisierten Definition für clickPotentialRank in der Tabelle productView unter der Reporting-Sub-API:
    • Das Ranking der Produkte basierend auf clickPotential wird auf Werte zwischen 1 und 1.000 normalisiert.
  • Mit dem AccountIdAlias in der Ressource AccountRelationship lassen sich komplexe Kontostrukturen besser verwalten. Marktplätze verwenden beispielsweise einen benutzerdefinierten Alias anstelle der internen ID des Händlers, z. B. die Konto-ID.

gRPC-Unterstützung

Die Merchant API unterstützt gRPC und REST. Sie können gRPC für die Merchant API und REST für die Content API for Shopping gleichzeitig verwenden.

Für die Clientbibliotheken der Merchant API ist gRPC erforderlich.

Weitere Informationen finden Sie unter gRPC – Übersicht.

Kompatibilität

In diesem Leitfaden werden allgemeine Änderungen beschrieben, die für die gesamte Merchant API gelten.

Die Merchant API ist so konzipiert, dass sie zusammen mit den vorhandenen Funktionen der Content API for Shopping verwendet werden kann.

Sie können die Merchant Inventories API beispielsweise zusammen mit Ihrer vorhandenen Content API for Shopping v2.1-Implementierung (products) verwenden. Sie können die Content API for Shopping verwenden, um ein neues lokales Produkt hochzuladen (das Sie in einem lokalen Geschäft verkaufen), und dann die Merchant Inventories API-Ressource LocalInventory verwenden, um Informationen zu diesem Produkt im Geschäft zu verwalten.

Strukturelle Verbesserungen gegenüber der Content API

Die Merchant API bietet im Vergleich zur Content API folgende Vorteile:

Sehen wir uns diese Änderungen genauer an.

Versionsverwaltung und Sub-APIs

Die Merchant API führt die Konzepte der Versionsverwaltung und der Sub-APIs ein. Das modulare Design verbessert die Nutzerfreundlichkeit, da Sie sich auf die benötigten Unter-APIs konzentrieren können und zukünftige Migrationen zu neueren Versionen einfacher sind. Die Versionsverwaltung wird auf Ihre Anfrage-URLs angewendet. Die Strategie ähnelt der Google Ads API.

Zuverlässigere Anfragen

Für Merchant API-URL-Anfragen sind weitere Parameter erforderlich, um die Merchant API aufzurufen. Dazu gehören die Ressource, die Version, der Name (IDs) und die Methode (nicht standardmäßige Methoden). Weitere Informationen finden Sie unter Konto- und Produktkennzeichnungen und Beispiele.

AIP-Grundsätze für Kennungen

Während die Content API for Shopping IDs zur Identifizierung von Ressourcen verwendet (z. B. merchantId, productId), verwendet die Merchant API eine name-Kennung, um sich an die AIP anzupassen (siehe API-Verbesserungsprinzipien).

Die {name}-ID enthält die Ressourcen-ID und das übergeordnete Element (oder möglicherweise mehrere übergeordnete Elemente), sodass {name} gleich accounts/{account}/products/{product} ist.

Bei allen Lese- und Schreibaufrufen wird das Feld name als Ressourcen-ID zurückgegeben.

{name} enthält auch die Sammlungs-IDs accounts/ und products/.

In der Merchant API wird {account} für eine Merchant Center-ID und {product} für Produktkennzeichnungen verwendet.

Implementieren Sie beispielsweise eine getName()-Methode, um die name aus einer Ressource abzurufen, und speichern Sie die Ausgabe als Variable, anstatt die name selbst aus den Händler- und Ressourcen-IDs zu erstellen.

Hier ein Beispiel für die Verwendung des Felds name in Ihren Aufrufen:

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

In der Tabelle sehen Sie, wie sich die Content API for Shopping-Anfrage products.get ändert:

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}

Weitere Informationen finden Sie unter Änderungen an Kennungen.

Ein weiteres Beispiel: Wenn Sie ein Produkt mit der Kennzeichnung en~US~1234 aus der Merchant Center-ID 4321 über die Merchant API abrufen möchten, sieht das so aus:

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

wobei {name} gleich accounts/4321/products/en~US~1234 ist. Dieses neue Namensfeld wird als Ressourcen-ID für alle Lese- und Schreibaufrufe in der Merchant API zurückgegeben.

In der Content API for Shopping wird ein Doppelpunkt (:) als Trennzeichen im Produktnamen verwendet, während in der Merchant API eine Tilde (~) diese Funktion erfüllt. Die Merchant API-ID enthält nicht den Teil channel.

Beispiel für eine Produkt-ID in der Content API for Shopping:

channel:contentLanguage:feedLabel:offerId.

in der Merchant API zu Folgendem:

contentLanguage~feedLabel~offerId.

Übergeordnete Felder für untergeordnete Ressourcen

In der Merchant API haben alle untergeordneten Ressourcen das Feld parent. Sie können das Feld parent verwenden, um die {name} der Ressource anzugeben, in die das untergeordnete Element eingefügt werden soll, anstatt die gesamte übergeordnete Ressource zu übergeben. Sie können das Feld parent auch mit list verwenden.

Wenn Sie beispielsweise lokales Inventar für ein bestimmtes Produkt auflisten möchten, geben Sie die name des Produkts im Feld parent für die Methode list an. In diesem Fall ist die angegebene product die parent der zurückgegebenen LocalInventory-Ressourcen.

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

Wenn Sie alle lokalen Inventare für das Produkt en~US~1234 und das Konto 4321 abrufen möchten, sieht die Anfrage so aus:

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

Das übergeordnete Element ist accounts/{account}/products/{product}. In diesem Fall hat die Ressource localInventories zwei übergeordnete Elemente, die in der Namenskennung enthalten sind (accounts/ und products/), da das Konto das übergeordnete Element der Produktressource ist.

Gängige Enums

Die Verwendung gängiger Enums sorgt für mehr Konsistenz.

Im Feld Destination.DestinationEnum werden die Oberflächen angegeben, auf denen Ihre Ressourcen angezeigt werden sollen. DestinationEnum listet alle verfügbaren Werte für das Ziel-Targeting auf und ist über alle Sub-APIs hinweg einheitlich, z. B. für Angebotsattribute.

Das Feld ReportingContext.ReportingContextEnum stellt den Kontext dar, auf den sich Ihre Konto- und Produktprobleme beziehen. Dieses Feld wird in allen Berichterstellungsmethoden verwendet (z. B. für IssueSeverityPerReportingContext).

Abwärtskompatibilität

Wenn Sie die Merchant API verwenden, funktioniert Ihre bestehende Integration der Content API for Shopping weiterhin ohne Unterbrechung. Weitere Informationen finden Sie unter Kompatibilität.

Nachdem Sie Ihre Sub-APIs zur Merchant API migriert haben, empfehlen wir, nur die Merchant API für Ihre migrierten Sub-APIs zu verwenden.

Verfügbarkeit von Remote-Prozeduraufrufen (gRPC)

gRPC ist die neue empfohlene Methode zur Einbindung der Merchant API.

Zu den Vorteilen gehören:

Benutzerdefiniertes Batching wird zu integriertem Batching

Die Batchverarbeitung ist effizienter, wenn Sie asynchrone Aufrufe verwenden. Weitere Informationen zur Verwendung paralleler Aufrufe für die Batchverarbeitung in der Merchant API und zum Refaktorieren von Code für gleichzeitige Anfragen.

Wir empfehlen die Clientbibliotheken, um die Migration zu beschleunigen.

Die Merchant API unterstützt die Methode customBatch der Content API for Shopping nicht. Weitere Informationen finden Sie unter Mehrere Anfragen gleichzeitig senden. Sie können Ihre Aufrufe auch asynchron ausführen.

.

Im folgenden Java-Beispiel wird gezeigt, wie Sie eine Produkteingabe einfügen:

   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);
  }
}

Wenn Sie customBatch in der Content API verwenden und diese Funktion für die Merchant API benötigen, teilen Sie uns in Ihrem Feedback mit, warum.

Exklusive Funktionen

Zukünftige Funktionen werden nur in der Merchant API verfügbar sein. Es gibt einige Ausnahmen, z. B. die Feedspezifikationen für 2025.

Zu den exklusiven Funktionen der Merchant API gehören:

  • Reviews API. Mit Rezensionen können Sie Ihre Produkt- und Shopbewertungen implementieren und verwalten. Weitere Informationen finden Sie unter Verkäuferbewertungen und Rezensionen.
  • Benachrichtigungen: Registrieren Sie sich, um Push-Benachrichtigungen zu Änderungen an Konto- und Produktdaten zu erhalten.

Preis

Folgendes hat sich für Price im Merchant Common-Paket geändert:

Content API for Shopping Merchant API
Feld „Betrag“ value:string amountMicros:int64
Währungsfeld currency:string currencyCode:string

Der Betrag für Price wird jetzt in Mikros angegeben, wobei 1 Million Mikros der Standardeinheit Ihrer Währung entspricht.

In der Content API for Shopping war Price eine Dezimalzahl in Form eines Strings.

Der Name des Betragsfelds wurde von value in amountMicros geändert.

Der Name des Währungsfelds wurde von currency in currencyCode geändert. Das Format ist weiterhin ISO 4217.

Aktuelle Updates und Ankündigungen

Detailliertere Informationen finden Sie in den Versionshinweisen zu den einzelnen Sub-APIs. Regelmäßigere zusammengefasste Updates zur Merchant API finden Sie in unseren aktuellen Updates.

Weitere Informationen zur Merchant API finden Sie in der Übersicht auf unserer Entwicklerwebsite und in der Migrationsanleitung.

Weitere Informationen zur Merchant API und ihren Sub-APIs finden Sie unter Merchant API-Design.

Weiter
Start your migration