Von der Content API for Shopping zur Merchant API migrieren

In dieser Anleitung wird der Migrationsprozess von der Content API for Shopping zur Merchant API für die Verwaltung von Geschäftsdaten erläutert.

Sie können diese Anleitung verwenden, um Ihre vorhandene Content API for Shopping-Implementierung zur Merchant API zu migrieren. Weitere Informationen zu den Details der Merchant API und ihrer Sub-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 zur Entwicklerregistrierung verknüpfen. Gehen Sie dazu so vor:

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 Merchant API Referenz.

Verbesserungen gegenüber der Content API for Shopping

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

Gängige Anwendungsfälle:

  • Automatisierte Kontenverwaltung
  • Automatisierte Produktverwaltung
  • Automatisierte Inventarverwaltung
  • Benutzerdefinierte Berichte

Wichtige Verbesserungsbereiche:

Was hat sich geändert?

  • Der maximale Wert für pageSize wurde von 250 auf 1.000 Zeilen pro API-Aufruf erhöht.
  • Eine Verzögerung, die nach der Erstellung von DataSources beim Einfügen von Produkten, Angeboten, Produktrezensionen und Händlerrezensionen auftrat, wurde behoben.
  • Einführung einer aktualisierten Definition für clickPotentialRank in der productView Tabelle unter der Sub-API „Berichte“:
    • Das Ranking von Produkten basierend auf clickPotential wird auf Werte zwischen 1 und 1.000 normalisiert.
  • Mit AccountIdAlias in der AccountRelationship Ressource lassen sich komplexe Kontostrukturen besser verwalten. Auf Marktplätzen wird beispielsweise ein nutzerdefinierter Alias anstelle der internen Händler-ID verwendet, 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 dieser Anleitung werden allgemeine Änderungen beschrieben, die für die gesamte Merchant API gelten.

Die Merchant API ist so konzipiert, dass sie mit den vorhandenen Funktionen der Content API for Shopping zusammenarbeitet.

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

Verbesserungen gegenüber der Content API

Die Merchant API bietet folgende Verbesserungen gegenüber der Content API:

Sehen wir uns diese Änderungen genauer an.

Versionierung und Sub-APIs

Mit der Merchant API werden die Konzepte der Versionierung und der Sub-APIs eingeführt. Das modulare Design verbessert die Nutzerfreundlichkeit, da Sie sich auf die benötigten Sub-APIs konzentrieren können und zukünftige Migrationen zu neueren Versionen einfacher sind. Die Versionierung wird mit Ihren Anfrage-URLs angewendet. Die Strategie ist ähnlich der Google Ads API.

Robustere Anfragen

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

AIP-Grundsätze für Kennungen

Während in der Content API for Shopping IDs zur Identifizierung von Ressourcen verwendet werden (z. B. merchantId, productId), wird in der Merchant API eine name -Kennung verwendet, um den AIP-Grundsätzen zu entsprechen (siehe API-Verbesserungsgrundsätze).

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

Alle Lese- und Schreibaufrufe geben das Feld name als Ressourcen-ID zurück.

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

In der Merchant API wird {account} verwendet, um auf eine Merchant Center-ID zu verweisen, und {product}, um auf Produktkennungen zu verweisen.

Implementieren Sie beispielsweise eine getName()-Methode, um den name aus einer Ressource abzurufen, und speichern Sie die Ausgabe als Variable, anstatt den 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: So rufen Sie ein Produkt mit der Kennung en~US~1234 aus der Merchant Center-ID 4321 mit der Merchant API ab:

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

Dabei ist {name} gleich accounts/4321/products/en~US~1234. 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-Kennung enthält nicht den Teil channel.

Beispiel: Produkt-ID in der Content API for Shopping:

channel:contentLanguage:feedLabel:offerId.

In der Merchant API wird daraus:

contentLanguage~feedLabel~offerId.

Übergeordnete Felder für untergeordnete Ressourcen

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

Wenn Sie beispielsweise lokale Inventare für ein bestimmtes Produkt auflisten möchten, geben Sie den Produkt's name im parent Feld für die list Methode an. In diesem Fall ist das angegebene product die parent der 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/online~en~US~1234/localInventories</code>

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

Häufig verwendete Enums

Die Verwendung häufig verwendeter Enums sorgt für mehr Konsistenz.

Das Destination.DestinationEnum Feld gibt die Oberflächen an, auf denen Ihre Ressourcen angezeigt werden sollen. DestinationEnum listet alle verfügbaren Werte für das Targeting auf Oberflächen auf und ist für alle Sub-APIs einheitlich, z. B. für Angebots attribute.

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

Abwärtskompatibilität

Wenn Sie die Merchant API verwenden, funktioniert Ihre vorhandene Content API for Shopping-Integration 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 Remoteprozeduraufrufen (gRPC)

gRPC ist die neue empfohlene Methode zur Integration in die Merchant API.

Zu den Vorteilen gehören:

Benutzerdefiniertes Batching wird zu integriertem Batching

Batching ist effizienter, wenn Sie asynchrone Aufrufe verwenden. Weitere Informationen finden Sie unter Parallele Aufrufe für Batching in der Merchant API verwenden und wie Sie Code für gleichzeitige Anfragen umgestalten.

Wir empfehlen die Verwendung der Client bibliotheken, um die Migration zu beschleunigen.

Die Merchant API unterstützt die customBatch Methode der Content API for Shopping nicht. Informationen zu Alternativen finden Sie unter Mehrere Anfragen gleichzeitig senden oder Aufrufe asynchron ausführen.

Das folgende Java-Beispiel zeigt, 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.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().setPoolSize(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);
  }
}
InsertProductInputAsyncSample.java

Wenn Sie customBatch in der Content API verwenden und diese Funktion für die Merchant API benötigen, geben Sie uns in Ihrem Feedback den Grund dafür an.

Exklusive Funktionen

Zukünftige Funktionen werden nur in der Merchant API verfügbar sein. Es gibt einige Ausnahmen, z. B. die jährliche Feed-Spezifikation für 2025.

Zu den Funktionen, die nur in der Merchant API verfügbar sind, gehören:

  • Reviews API. Mit der Reviews API können Sie Ihre Produkt- und Shopbewertungen implementieren und verwalten. Weitere Informationen finden Sie unter Händler rezension und Produkt rezension.
  • Benachrichtigungen: Registrieren Sie sich, um Push-Benachrichtigungen für Änderungen an den Produktdaten eines Kontos 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
Feld „Währung“ currency:string currencyCode:string

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

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

Der Name des Felds „Betrag“ wurde von value zu amountMicros geändert.

Der Name des Felds „Währung“ wurde von currency zu currencyCode geändert. Das Format ist weiterhin ISO 4217.

Aktuelle Updates und Ankündigungen

Weitere detaillierte Updates finden Sie in den Versionshinweisen für die einzelnen Sub-APIs. Regelmäßige zusammengefasste Updates zur Merchant API finden Sie unter Aktuelle Updates.

Weitere Informationen und Details zur Merchant API finden Sie in unserer Übersicht auf der Entwicklerwebsite und in der allgemeinen Migrations anleitung.

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

Zurück
Design
Weiter
Migrate accountstatuses to Account Issues