Von v1beta zu v1 migrieren

In dieser Anleitung erfahren Sie, wie Sie von der Merchant API v1beta zur v1 migrieren, der ersten Version für die allgemeine Verfügbarkeit. Die Version 1 enthält mehrere Updates und einige Änderungen, die möglicherweise Code-Updates erfordern. Mit diesen Änderungen soll die API vereinfacht und die Verwaltung Ihres Merchant Center-Kontos verbessert werden.

Wichtige Unterschiede

Hier sind die wichtigsten Änderungen, die Sie bei der Migration von v1beta zu v1 beachten müssen:

• Einmalige Registrierung von mindestens einem API-Entwickler für die Verwendung der Merchant API:Sie müssen die Methode registerGcp (nur einmal für jedes Google Cloud-Projekt, das für die Authentifizierung verwendet wird) aufrufen, um Ihre Kontaktdaten anzugeben. So können Sie die API verwenden und Updates und Ankündigungen zur Merchant API erhalten. Sie können keine v1- oder v1alpha-API verwenden, bis dieser Schritt abgeschlossen ist. Eine Anleitung finden Sie unter Als Entwickler registrieren.

• Codierung des Produktnamens: Die Felder ProductInput.name und Product.name unterstützen die unpadded base64url-Codierung (RFC 4648, Abschnitt 5). Beachten Sie die folgenden Richtlinien:

  • Vor der Codierung muss der String dem Format contentLanguage~feedLabel~offerId entsprechen.

  • Die Codierung ist erforderlich, wenn Ihr Produktname Zeichen enthält, die von der Merchant API verwendet werden, oder URL-reservierte Zeichen wie:

    % . + / : ~ , ( * ! ) & ? = @ # $
    

  • Wenn Ihr Produktname dem contentLanguage~feedLabel~offerId-Format entspricht und keine von der Merchant API verwendeten Zeichen oder URL-reservierte Zeichen enthält, können Sie das einfache Format ohne Codierung verwenden.

  • Damit die Namen einheitlich und korrekt geparst werden, empfehlen wir, für alle Produktnamen die Base64url-Codierung ohne Padding zu verwenden.

• Entfernen von Steuerinformationen auf Produktebene:taxes und taxCategory.

• Product.attributes umbenannt: Das Feld Product.attributes wurde in Product.productAttributes umbenannt.

• Entfernung von Steuerinformationen auf Produktebene:Die Felder taxes und taxCategory wurden aus dem Objekt Product.productAttributes entfernt. Weitere Informationen finden Sie im Google Merchant Center-Hilfeartikel zum Thema Steuern.

• Änderungen am Feld „GTIN“:Das Feld gtin im Objekt Product.productAttributes wurde in gtins umbenannt, um besser widerzuspiegeln, dass es mehrere Werte enthalten kann. Das Feld gtin im Objekt OrderTrackingSignals.lineItemDetails ist jetzt ein array und wurde in gtins umbenannt.

• Entfernung des Channel-Felds:Das Feld channel wurde aus Produkten, Produkteingaben und Datenquellen entfernt. Ein neues boolesches Feld, legacyLocal, wurde eingeführt, um Produkte, die ausschließlich in physischen Geschäften verkauft werden, eindeutig zu kennzeichnen. Hinweis: Das Feld legacyLocal ist ein Hilfsfeld für die Migration und wird demnächst eingestellt, sobald Online- und lokale Marketingmethoden vollständig mit einer einzigen Produktquelle ausgerichtet werden können. Weitere Informationen finden Sie in der Tabelle im nächsten Abschnitt.

• Neue Felder für regionale und lokale Inventarattribute:

  • Alle RegionalInventory-Felder mit Ausnahme von name, account und region sind jetzt in einem neuen Objekt namens regionalInventoryAttributes enthalten. Das Attribut RegionalInventory.price befindet sich jetzt beispielsweise unter RegionalInventory.regionalInventoryAttributes.price.
  • Alle LocalInventory-Felder mit Ausnahme von name, account und storeCode sind jetzt in einem neuen Objekt namens localInventoryAttributes enthalten. Das Attribut LocalInventory.price befindet sich jetzt beispielsweise unter LocalInventory.localInventoryAttributes.price.

• Entfernung von customAttributes aus regionalen und lokalen Inventaren:Das Feld customAttributes wurde sowohl aus den Ressourcen RegionalInventory als auch aus LocalInventory entfernt.

• Optimierte Kontoerstellung:Das überflüssige Feld users wurde aus CreateAndConfigureAccountRequest entfernt. Verwenden Sie das Einzelfeld user, um einen ersten Nutzer mit einem neuen Konto zu verknüpfen.

• Bestimmte Attributtypen wurden von Strings in Enumerationen geändert:Einige Felder in den Ressourcen Product und Inventory mit einer definierten kurzen Liste von Werten wurden zur besseren Datenvalidierung vom Typ string in den Typ enum geändert. Das Feld Product.ProductAttributes.condition ist jetzt beispielsweise vom Typ enum.

• Entfernung der Methode zum Aktualisieren von Online-Rückgaberichtlinien:Die Methode onlineReturnPolicy.update wird in v1 entfernt. Erstellen Sie stattdessen eine Online-Rückgaberichtlinie mit der Methode onlineReturnPolicy.create.

Vorgehensweise

Die v1beta-Version der Merchant API wird am 28. Februar 2026 eingestellt. Weitere Informationen zum Zeitplan für die Einstellung finden Sie in der Anleitung zur Merchant API-Versionierung.

• Der erste Schritt bei der Migration ist die einmalige Entwicklerregistrierung (siehe Als Entwickler registrieren). Sie müssen die registerGcp-Methode für jedes Google Cloud-Projekt aufrufen, das Sie für die Authentifizierung verwenden, bevor v1-Methoden funktionieren.

• Unabhängig davon, wie Sie die APIs aufrufen (mit REST, gRPC oder über Clientbibliotheken), können Sie die Migration in Phasen durchführen. Das bedeutet, dass Sie Ihren Code API für API aktualisieren und migrieren können (z. B. die Products API zu v1 verschieben, während die Accounts API auf v1beta bleibt), ohne die gesamte Integration auf einmal aktualisieren zu müssen.

Detaillierte Feldänderungen

Diese Tabelle enthält einen detaillierten Vergleich der Felder, die sich zwischen den Versionen v1beta und v1 geändert haben.