Von v1beta zu v1 migrieren

In dieser Anleitung erfahren Sie, wie Sie von der Merchant API v1beta zu v1 migrieren, der ersten Version für die allgemeine Verfügbarkeit. Die Version `v1` enthält mehrere Updates und einige Änderungen, für die möglicherweise Codeaktualisierungen erforderlich sind. 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 sollten:

• Einmalige Registrierung von mindestens einem API-Entwickler für die Verwendung der Merchant API: Sie müssen die Methode registerGcp aufrufen (nur einmal für jedes Google Cloud-Projekt, das für die Authentifizierung verwendet wird), 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. Weitere Informationen zum Registrierungsprozess finden Sie unter Registrierung.

• Produktnamencodierung: Die ProductInput.name und Product.name Felder unterstützen die nicht aufgefüllte base64url-Codierung (RFC 4648, Abschnitt 5). Beachten Sie diese Richtlinien:

  • Vor der Codierung muss der String das Format contentLanguage~feedLabel~offerId haben.

  • 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 Zeichen enthält, die von der Merchant API verwendet werden, oder URL-reservierte Zeichen, können Sie das einfache Format ohne Codierung verwenden.

  • Um eine einheitliche und korrekte Analyse zu gewährleisten, empfehlen wir, für alle Produktnamen die nicht aufgefüllte base64url-Codierung zu verwenden.

• Entfernung von Steuerinformationen auf Produktebene:Die Felder 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 Product.productAttributes Objekt entfernt. Weitere Informationen finden Sie im Google Merchant Center-Hilfeartikel zu Steuern.

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

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

• Neue Felder für regionale und lokale Inventarattribute:

  • Alle RegionalInventory Felder außer name, account und region sind jetzt unter einem neuen Objekt namens regionalInventoryAttributes zusammengefasst. Das Attribut RegionalInventory.price befindet sich jetzt beispielsweise unter RegionalInventory.regionalInventoryAttributes.price.
  • Alle LocalInventory Felder außer name, account und storeCode sind jetzt unter einem neuen Objekt namens localInventoryAttributes zusammengefasst. Das Attribut LocalInventory.price befindet sich jetzt beispielsweise unter LocalInventory.localInventoryAttributes.price.

• Entfernung von customAttributes aus regionalem und lokalem Inventar: Das customAttributes Feld wurde sowohl aus den Ressourcen RegionalInventory als auch LocalInventory entfernt.

• Verbesserte Kontoerstellung:Das redundante Feld users wurde aus CreateAndConfigureAccountRequest entfernt. Verwenden Sie das Feld user im Singular, um einen ersten Nutzer mit einem neuen Konto zu verknüpfen.

• Bestimmte Attributtypen wurden von Strings in Enums 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 ein enum.

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

Vorgehensweise

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

• Der erste Schritt bei der Migration ist die einmalige Registrierung als Entwickler (siehe Als Entwickler registrieren). Sie müssen die Methode registerGcp 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 mit Client bibliotheken), können Sie die Migration in Phasen durchführen. Das bedeutet, dass Sie Ihren Code für jede API einzeln aktualisieren und migrieren können. Sie können beispielsweise die Products API zu v1 verschieben, während die Accounts API in v1beta bleibt. So müssen Sie nicht Ihre gesamte Integration auf einmal aktualisieren.

Detaillierte Feldänderungen

In dieser Tabelle finden Sie einen detaillierten Vergleich der Felder, die sich geändert haben zwischen den v1beta und v1 Versionen.