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 Unternehmensdaten beschrieben.

In diesem Leitfaden erfahren Sie, wie Sie Ihre vorhandene Content API for Shopping-Implementierung zur Merchant API migrieren. Weitere Informationen zu den Details der Merchant API und ihrer untergeordneten APIs finden Sie unter Merchant API-Design.

Jetzt starten

Wenn Sie die Merchant API verwenden möchten, ändern Sie die 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 Entwicklerregistrierungsmethode 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 im Schnellstartleitfaden und in der Merchant API-Referenz.

Vorteile gegenüber der Content API for Shopping

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

Wichtige Anwendungsfälle:

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

Wichtige Verbesserungsbereiche:

Was hat sich geändert?

  • Die maximale Anzahl von pageSize wurde von 250 auf 1.000 Zeilen pro API-Aufruf erhöht.
  • Eine Verzögerung beim Einfügen von Produkten, Angeboten, Produktrezensionen und Händlerrezensionen nach der Erstellung von DataSources wurde behoben.

Das erwartet Sie:

  • Einführung einer aktualisierten Definition für clickPotentialRank in der Tabelle productView unter der Reporting-Unter-API: * Das Ranking von Produkten basierend auf clickPotential wird auf Werte zwischen 1 und 1.000 normalisiert.
    • Produkte mit einem niedrigen clickPotentialRank haben unter den Produkten des Händlers, die die Bedingungen der Suchanfrage erfüllen, immer noch das höchste Klickpotenzial. Dies ist eine nicht abwärtskompatible Änderung, die am 1. Juli 2025 eingeführt werden könnte.
  • Mit dem AccountIdAlias in der Ressource AccountRelationship lassen sich komplexe Kontostrukturen besser verwalten. Marktplätze verwenden beispielsweise einen nutzerdefinierten Alias anstelle der internen ID des Händlers, z. B. der 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 für die Zusammenarbeit mit den vorhandenen Funktionen der Content API for Shopping konzipiert.

Sie können die Merchant Inventories API beispielsweise zusammen mit Ihrer vorhandenen Implementierung der Content API for Shopping v2.1 products verwenden. Sie können die Content API for Shopping verwenden, um ein neues lokales Produkt (das Sie in einem Ladengeschäft verkaufen) hochzuladen. Anschließend können Sie mit der Ressource LocalInventory der Merchant Inventories API die Informationen zum Produkt im Geschäft verwalten.

Vorteile gegenüber der Content API

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

Sehen Sie sich diese Änderungen genauer an.

Versionsverwaltung und untergeordnete APIs

In der Merchant API werden die Konzepte der Versionsverwaltung und der Unter-APIs eingeführt. Das modulare Design verbessert die Benutzerfreundlichkeit, da Sie sich auf die benötigten Unter-APIs konzentrieren können. Außerdem wird die Migration zu neueren Versionen erleichtert. Die Versionsverwaltung wird mit Ihren Anfrage-URLs angewendet.Die Strategie ähnelt 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-IDs und Beispiele.

AIP-Grundsätze für IDs

Während in der Content API for Shopping IDs zur Identifizierung von Ressourcen verwendet werden (z. B. merchantId, productId), wird in der Merchant API ein name-Identifier verwendet, um die API zu verbessern (siehe Grundsätze zur API-Verbesserung).

Der {name}-Identifier umfasst den Ressourcen-Identifier 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 Produkt-IDs 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 products.get-Anfrage der Content API for Shopping ä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 mit der Merchant API abrufen möchten, sieht das so aus:

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

Dabei entspricht {name} 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.

selbst aus der Händler- und der Ressourcen-ID.

In der Content API for Shopping steht ein Doppelpunkt (:) für ein Trennzeichen im Produktnamen, während in der Merchant API eine Tilde (~) diese Funktion übernimmt. Die Merchant API-Kennung enthält nicht den Teil channel.

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

channel:contentLanguage:feedLabel:offerId.

in der Merchant API:

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 das angegebene product das parent der zurückgegebenen LocalInventory-Ressourcen.

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

Um alle lokalen Inventare für das Produkt en~US~1234' und das Konto 4321 abzurufen, sieht die Anfrage so aus:

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

Das übergeordnete Element ist accounts/{account}/products/{product}. Beachten Sie, dass die Ressource localInventories in diesem Fall zwei übergeordnete Elemente in der Namens-ID (accounts/ und products/) enthält, da das Konto das übergeordnete Element der Produktressource ist.

Häufig verwendete Enums

Die Verwendung allgemeiner Enums sorgt für mehr Konsistenz.

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

Das Feld ReportingContext.ReportingContextEnum gibt den Kontext an, auf den sich Ihre Konto- und Produktprobleme beziehen. Dieses Feld wird für alle Berichterstellungsmethoden verwendet, z. B. für IssueSeverityPerReportingContext.

Abwärtskompatibilität

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

Nachdem Sie Ihre untergeordneten APIs zur Merchant API migriert haben, empfehlen wir, nur noch die Merchant API für Ihre migrierten untergeordneten 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

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

Um die Migration zu beschleunigen, empfehlen wir die Verwendung der Clientbibliotheken.

Die Merchant API unterstützt nicht die Methode customBatch, die in der Content API for Shopping enthalten ist. Stattdessen sollten Sie mehrere Anfragen gleichzeitig senden oder Ihre 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.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

Wenn Sie customBatch in der Content API verwenden und dieses Feature für die Merchant API benötigen, teilen Sie uns den Grund in Ihrem Feedback mit.

Exklusive Funktionen

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

Funktionen, die exklusiv in der Merchant API verfügbar sind:

  • Reviews API. Mit Rezensionen können Sie Produkt- und Händlerbewertungen implementieren und verwalten. Weitere Informationen finden Sie unter Händlerrezensionen und Produktrezensionen.
  • Benachrichtigungen: Hier können Sie sich für Push-Benachrichtigungen bei Änderungen an den Produktdaten eines Kontos registrieren.

Preis

Folgendes hat sich für Price im Paket „Merchant Common“ 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. Eine Million Mikros entspricht der Standardeinheit Ihrer Währung.

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

Der Feldname für den Betrag 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 für die einzelnen untergeordneten APIs. Hier finden Sie die neuesten Updates zur Merchant API.

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

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

Zurück
Quickstart
Weiter
Migrate accountstatuses to Account Issues