Zwischen Dateifeeds und der Merchant API wählen

Sie können Produktdaten über dateibasierte Feeds, die Merchant API oder eine Kombination aus beidem in das Merchant Center hochladen:

  • Dateibasierte Produktfeeds: Laden Sie CSV-, TSV- oder XML-Dateien über SFTP, Google Cloud Storage, Google Sheets oder geplante Abrufe hoch.
  • Merchant API: Senden Sie programmatische Anfragen direkt von Ihrem Backend, um inkrementelle Aktualisierungen vorzunehmen, wenn sich Produktdaten ändern, und führen Sie regelmäßig vollständige Katalog-Synchronisierungen durch.

In diesem Leitfaden werden beide Ansätze verglichen und es wird erläutert, wann welcher Ansatz (oder beide zusammen) verwendet werden sollte. Außerdem enthält er eine schrittweise Migrationsanleitung, falls Sie sich entscheiden, einige oder alle Ihrer Produkte von Dateifeeds auf die API umzustellen.

Datenquellenansatz auswählen

Bewerten Sie die Volatilität Ihres Katalogs, Ihre Backend-Architektur und Ihre operativen Workflows, um zu entscheiden, ob Sie die Merchant API, Dateifeeds oder eine hybride Einrichtung verwenden möchten.

Wann sollte die Merchant API verwendet werden?

Verwenden Sie eine primäre API-Datenquelle, wenn:

  • Direkte programmatische Integration: Sie möchten eine API direkt über Ihr Backend aufrufen, anstatt Dateien zu generieren und Pipelines für die Dateiübertragung (z. B. SFTP oder Google Cloud Storage) zu verwalten.
  • Hohe Preis- und Inventarschwankungen: Ihre Produktpreise oder Lagerbestände ändern sich im Laufe des Tages häufig.
  • Sofortige Aktualisierungen bei Datenänderungen: Sie möchten Produktänderungen an Google senden, sobald sie in Ihrem Backend vorgenommen werden, anstatt auf die nächste geplante Dateigenerierung und den nächsten Upload zu warten.
  • Inkrementelle Katalogaktualisierungen: Sie möchten einzelne Produkte einfügen, aktualisieren oder löschen, wenn sie sich ändern, ohne jedes Mal den gesamten Katalog neu hochzuladen.
  • Teilweise Attributaktualisierungen: Sie möchten bestimmte Felder eines Produkts (z. B. price oder availability mit productInputs.patch) aktualisieren, ohne die vollständige Produktnutzlast noch einmal zu senden.

Wann Dateifeeds verwendet werden sollten

Verwenden Sie eine dateibasierte primäre Datenquelle, wenn:

  • Statischer Katalog: Ihre Produktdaten ändern sich selten (z. B. einmal täglich oder seltener).
  • Nur-Snapshot-Backend ohne Delta-Tracking: Ihr Backend exportiert nur vollständige Katalog-Snapshots und kann keine Änderungen auf Artikelebene oder explizite Produktlöschungen verfolgen.
  • Tabellenbasierte Workflows: Nicht-technische Teams kuratieren oder überschreiben Produktdaten direkt in Google Sheets oder CSV-Dateien.
  • Wartungsarme Vorgänge: Sie bevorzugen einen geplanten Dateiexport, bei dem das Merchant Center das Abrufen und die Snapshot-Verarbeitung übernimmt, anstatt eine API-Integration mit Anfrage-Pacing, Wiederholungsbehandlung und regelmäßigen Synchronisierungen des gesamten Katalogs zu betreiben.

Wann beide verwendet werden sollten

In den folgenden Szenarien können Sie Dateifeeds und die Merchant API im selben Merchant Center-Konto kombinieren:

  • Partitionierte Produktkataloge: Sie verwenden die Merchant API für Produkte, die sich schnell ändern (z. B. Blitzverkäufe oder Inventar mit hohem Umsatz), und Dateifeeds für statische Katalogsegmente oder separate Produktlinien. Achten Sie darauf, dass jedes Produkt nur von einer primären Datenquelle hochgeladen wird (siehe Parallele Nutzung und Inhaberschaft der primären Datenquelle).
  • Primäre API-Daten mit dateibasierten Sub-Feeds: Sie verwalten die wichtigsten Produktdaten über eine primäre API-Datenquelle, während nicht technische Teams oder Drittanbieter zusätzliche Attribute über dateibasierte Sub-Feeds (z. B. Google-Tabellen oder CSV-Dateien) bereitstellen, die mit Attributregeln verknüpft sind, oder umgekehrt.
  • Teilweise oder schrittweise Migration: Sie stellen bestimmte Märkte, Kategorien oder Unterkonten auf die API um, während der Rest Ihres Katalogs in Dateifeeds verbleibt.

Wenn Sie einige oder alle Ihrer Produkte von Dateifeeds zur Merchant API migrieren möchten, folgen Sie der Schritt-für-Schritt-Anleitung für die Migration.

Wichtige architektonische Unterschiede

Dateifeeds und die pushbasierte Merchant API unterscheiden sich darin, wie Google Produktdaten verarbeitet und verwaltet:

Konzept Dateifeeds Merchant API
Integrationsmodell Offline-Dateidump: Sie exportieren Ihren Katalog in eine Datei und übertragen sie über SFTP, Google Cloud Storage, Google Sheets oder geplante Abrufe. Direkte programmatische Integration: Ihr Backend sendet Anfragen direkt an den API-Endpunkt.
Detaillierungsgrad der Mutation Bulk-Verarbeitung: Wenn Sie einen Artikel ändern, muss in der Regel die gesamte Datei neu verarbeitet werden. Granulare Transaktionen: Sie können nur die Produkte einfügen, patchen oder löschen, die sich geändert haben.
Synchronisierungszeitpunkt Batchsynchronisierung: Änderungen werden in Ihrem Backend gespeichert, bis der nächste geplante Dateiexport- und Übertragungszyklus stattfindet. Sofortige oder geplante Aufrufe: Sie können inkrementelle Änderungen sofort senden, wenn sie auftreten, und zusätzlich regelmäßige vollständige Synchronisierungen durchführen.
Löschverhalten Implizit (Snapshot): Jede Datei ist ein vollständiger Snapshot. Wenn Sie eine Zeile aus Ihrer Primärdatei entfernen, wird das Produkt gelöscht. Explizit: Es gibt kein Snapshot-Konzept. Rufen Sie productInputs.delete auf, um ein eingestelltes Produkt zu entfernen.
Ressourcenrepräsentation Einzelner Status: Die Zeilen Ihrer Datei stellen die Roheingabe dar. Rohdaten und verarbeitete Daten trennen: Die API teilt Daten in ProductInput (Ihre Roheingabe) und Product (den endgültigen verarbeiteten Zustand) auf.
Attributregeln (Feedregeln) Wird auf Rohdateispalten in der Merchant Center-Benutzeroberfläche angewendet. Wird auf der Merchant Center-Benutzeroberfläche unterstützt. Erforderlich, wenn API-Daten mit zusätzlichen Dateien von Drittanbietern zusammengeführt werden. Optional für Transformationen mit einer einzigen Quelle, wenn sie im Backend verarbeitet werden.

Parallele Nutzung und Inhaberschaft der primären Datenquelle („Letzte Aktualisierung gewinnt“)

Sie können zwar sowohl Dateifeeds als auch die API im selben Merchant Center-Konto verwenden, wir empfehlen jedoch dringend, für jedes Produkt nur eine Methode zu verwenden.

Im Merchant Center gilt das Prinzip „Letzte Aktualisierung gewinnt“. Die primäre Datenquelle (API oder Dateifeed), über die das Produkt zuletzt eingefügt wurde, erhält die primäre Inhaberschaft für die Daten dieses Produkts:

  • Wenn die Dateidatenquelle der Inhaber des Produkts ist: Wenn das Produkt bei einem nachfolgenden Dateiupload weggelassen wird, wird es implizit gelöscht und aus dem Merchant Center entfernt.
  • Wenn die API-Datenquelle der Inhaber des Produkts ist: Das Weglassen des Produkts aus einem Dateiupload hat keine Auswirkungen, da der Dateifeed nicht mehr der Inhaber des Produkts ist. Sie müssen accounts.productInputs.delete aufrufen, um es zu entfernen.
  • Risiko einer versehentlichen erneuten Übernahme der Inhaberschaft: Wenn ein aktualisierter Dateifeed nach einem API-Push ausgeführt wird und das Produkt enthält, übernimmt die Dateidatenquelle wieder die Inhaberschaft. Wenn Sie das Produkt dann aus der Datei entfernen, wird es unerwartet gelöscht.

Um unerwartete Löschungen oder den Verlust von API-Aktualisierungen zu vermeiden, sollten Sie keine gleichzeitigen Aktualisierungen derselben Produkte über die API und über primäre Dateidatenquellen vornehmen.

Wichtige API-Überlegungen

Bevor Sie mit der Implementierung beginnen, sollten Sie sich mit den folgenden wichtigen Verhaltensweisen der Merchant API vertraut machen:

Flexible Datenquellen (ohne Sprache oder Label)

Im Gegensatz zu Dateifeeds, bei denen Sie im Voraus ein bestimmtes Zielfeedlabel und eine bestimmte Sprache festlegen müssen, können Sie mit der Merchant API primäre Datenquellen erstellen, ohne ein feedLabel oder eine contentLanguage anzugeben.

  • Flexible Uploads: Damit können Sie Produkte mit einer beliebigen Kombination aus Sprache und Feedlabel in eine einzige Datenquelle hochladen.
  • Vereinfachte Verwaltung: Sie müssen nicht für jeden Zielmarkt separate Datenquellen erstellen und verwalten. Hinweis: Weitere Informationen zur Auswahl einer Datenquellenstrategie finden Sie unter Datenquellenstrategie auswählen.

Synchronisierungsstrategie und Kontingente

Im Gegensatz zu einem Dateifeed, bei dem Sie Ihren gesamten Katalog in einem einzigen Batch hochladen, sollten Sie Ihre Merchant API-Integration sowohl für inkrementelle Aktualisierungen als auch für zeitlich gestaffelte vollständige Synchronisierungen konzipieren:

  • Inkrementelle Updates mit regelmäßigen vollständigen Synchronisierungen kombinieren: Senden Sie productInputs.insert- oder productInputs.patch-Anfragen, wenn sich Produktattribute in Ihrem Backend ändern. Wenn Sie sich ausschließlich auf inkrementelle Aktualisierungen verlassen, kann es im Laufe der Zeit zu Abweichungen bei den Daten kommen. Führen Sie daher auch regelmäßig vollständige Synchronisierungen durch, um Ihren Katalog mit Ihrer „Source of Truth“ abzugleichen. Dadurch wird auch die 30-tägige Produktablauffrist aktualisiert. Wie oft Sie eine vollständige Synchronisierung ausführen, hängt von der Größe Ihres Katalogs und dem verfügbaren API-Kontingent ab.
  • Anfragen so verteilen, dass API-Kontingente eingehalten werden: Rufen Sie die API nicht für alle Ihre Produkte gleichzeitig auf. Inkrementelle Änderungen können zwar gesendet werden, sobald sie auftreten, aber Sie sollten Anfragen für die vollständige Synchronisierung gleichmäßig über den Tag verteilen, um Ihre Kontingente für Methodenaufrufe pro Minute und Tag nicht zu überschreiten. Weitere Informationen finden Sie unter Kontingente und Limits und Produkte regelmäßig aktualisieren.

Integration testen

Validieren Sie Ihre Integrationslogik in einer sicheren Umgebung, bevor Sie sie in die Produktion überführen.

Testkonten nutzen

Bevor Sie Änderungen in der Produktion vornehmen, empfehlen wir, die ersten Schritte der Migration in einem Sandbox-Testkonto auszuführen:

  1. Testkonto erstellen: Richten Sie ein isoliertes Testkonto ein, um sicher zu experimentieren, ohne dass sich dies auf Live-Anzeigen oder Produkteinträge auswirkt.
  2. API-Datenquelle erstellen: Üben Sie das Erstellen Ihrer primären API-Datenquelle.
  3. Attributregeln testen: Datentransformationen und Verknüpfungen mit Subfeeds überprüfen.
  4. Nutzlasten und Produktschlüssel validieren: Senden Sie Beispielprodukte, um die Groß-/Kleinschreibung, Codierung und Fehlerbehandlung von SKUs zu überprüfen.

Weitere Informationen finden Sie unter Schritt 1: Testkonten erstellen und im Leitfaden Testkonten.

Abstimmung des Produktschlüssels validieren

Achten Sie darauf, dass der Produktschlüssel der programmatischen Nutzlast genau mit den SKUs im Dateifeed übereinstimmt. Google identifiziert Produkte durch die Kombination folgender Informationen:

  • offerId (in Dateifeeds als id bezeichnet, Groß-/Kleinschreibung beachten)
  • contentLanguage (z. B. en)
  • feedLabel (z. B. US)

Sonderzeichen und Codierung

Wenn Ihre Produktkennzeichnungen Zeichen wie /, % oder ~ enthalten, verwenden Sie in Ihren API-Aufrufen das codierte Format (base64url-Codierung ohne Auffüllung). Weitere Informationen finden Sie unter ProductInput.name.

Nebenläufigkeitserkennung

Bei einer Echtzeitintegration können Aktualisierungen aufgrund von Netzwerklatenz in falscher Reihenfolge eintreffen. Wenn Sie verhindern möchten, dass ältere Aktualisierungen neuere Daten überschreiben, verwenden Sie das Feld versionNumber in der Ressource ProductInput.

Detaillierte Anleitung zur Migration

Wenn Sie einige oder alle Ihre Produkte von Dateifeeds zur Merchant API migrieren möchten, folgen Sie dieser Anleitung, um Ihre Produkte zu übertragen, ohne Impressionen oder den Bereitstellungsverlauf zu verlieren.

1. Migration in einem Testkonto proben

Bevor du Änderungen in der Produktion vornimmst, solltest du mit der Methode accounts.createTestAccount ein Testkonto in einer Sandbox erstellen (siehe den Leitfaden Testkonten). Testkonten bieten eine isolierte Umgebung, in der Angebote standardmäßig genehmigt werden, keine Domainbestätigung erforderlich ist und Daten nie öffentlich bereitgestellt werden.

Verwenden Sie Ihr Testkonto, um Ihre Produktionseinrichtung zu spiegeln und die Migration von Anfang bis Ende zu testen:

  1. Produktfeed-Einrichtung spiegeln: Erstellen Sie im Testkonto eine primäre Datenquelle für Dateien (und alle zusätzlichen Datenquellen) und laden Sie ein Beispiel Ihrer Produktionsfeeddatei hoch.
  2. Test-API-Datenquelle und ‑Regeln erstellen: Erstellen Sie eine primäre API-Datenquelle und konfigurieren Sie alle erforderlichen Attributregeln oder Verknüpfungen mit zusätzlichen Feeds.
  3. Übernahme der Inhaberschaft und Schlüsselabgleich testen: Senden Sie productInputs.insert-Anfragen für die Beispielprodukte und prüfen Sie, ob die API-Datenquelle die Inhaberschaft der vorhandenen Artikel übernimmt, ohne doppelt vorhandene Produkte zu erstellen.
  4. Aktualisierungen und Löschungen prüfen: Testen Sie Teilaktualisierungen mit productInputs.patch und Entfernungen mit productInputs.delete und prüfen Sie die resultierenden Ressourcen mit products.get.

2. Produktions-API-Datenquellen erstellen

Bevor Sie Daten übertragen, müssen Sie in Ihrem Konto eine primäre Datenquelle vom Typ „API“ erstellen.

Primäre API-Datenquelle erstellen

Wenn Sie eine Datenquelle erstellen möchten, die API-Pushes akzeptiert, senden Sie eine POST-Anfrage an den Endpunkt dataSources. Weitere Informationen finden Sie unter Primäre Produktdatenquelle erstellen.

3. Regeln für benutzerdefinierte Attribute umstellen

Benutzerdefinierte Attributregeln sind an bestimmte Datenquellen gebunden und werden nicht automatisch von Ihrer Dateidatenquelle in Ihre neue API-Datenquelle übertragen.

Wie Sie Ihre Attributregeln umstellen, hängt von ihrem Zweck ab:

  • Quellenübergreifende Zusammenführung und Subfeeds von Drittanbietern: Wenn Sie primäre API-Daten mit externen zusätzlichen Datenquellen kombinieren (z. B. Dateien von Drittanbietern, Inventartabellen oder Angebotsfeeds), müssen Sie die Attributregeln in der Merchant Center-Benutzeroberfläche neu erstellen und an die neue API-Datenquelle anhängen. Die clientseitige Vorverarbeitung kann keine Regeln ersetzen, die Daten aus mehreren unabhängigen Quellen zusammenführen.
  • Datentransformationen für einzelne Quellen: Für die Bereinigung, Standardwerte oder Stringformatierung Ihrer primären Katalogdaten können Sie zwischen folgenden Optionen wählen:
    • Backend-Transformationen (empfohlen): Wenden Sie Transformationen in Ihrem eigenen System an, bevor Sie die API aufrufen. Dies ermöglicht eine bessere programmatische Kontrolle, einfachere Tests und ein vereinfachtes Debugging.
    • Merchant Center-Attributregeln: Erstellen Sie die Transformationsregeln für Ihre neue API-Datenquelle in der Merchant Center-Benutzeroberfläche neu, wenn Sie möchten, dass das Merchant Center sie weiterhin automatisch verwaltet.

4. API-Integration aktivieren

Aktivieren Sie Ihre Products API-Integration, um Produkte in Ihrer neuen primären API-Datenquelle einzufügen, zu aktualisieren und zu löschen:

  • Produkte einfügen und aktualisieren (Übernahme der Eigentumsrechte): Senden Sie productInputs.insert- und productInputs.patch-Anfragen über Ihre Integration. Wenn Sie ein Produkt über die API mit demselben Schlüssel (offerId, contentLanguage, feedLabel) wie ein vorhandenes Dateifeed-Produkt einfügen, übernimmt die API-Datenquelle die Inhaberschaft für dieses Produkt und behält den Auslieferungsverlauf bei. Weitere Informationen finden Sie unter Produkt einfügen und Produkte hinzufügen und verwalten.

  • Nicht mehr erhältliche Produkte löschen: Konfigurieren Sie Ihre Integration so, dass productInputs.delete explizit aufgerufen wird, wenn ein Produkt aus Ihrem Katalog entfernt wird.

  • Schrittweise bereitstellen: Aktivieren Sie bei großen Katalogen die Integration für jeweils ein Merchant Center-Unterkonto oder eine Datenquelle.

  • Nebenläufigkeit konfigurieren: Wenn Sie viele Anfragen senden, konfigurieren Sie Ihren Client so, dass er gleichzeitige Anfragen verarbeiten und mehrere Verbindungen verwalten kann. Weitere Informationen finden Sie im Leitfaden Code für gleichzeitige Anfragen refaktorieren.

5. Aktualisierungen von Dateidatenquellen pausieren

Sobald Ihre API-Integration aktiv ist, sollten Sie Dateiaktualisierungen vor der nächsten geplanten Dateiausführung beenden, damit die Dateidatenquelle Ihre API-Aktualisierungen nicht überschreibt:

  1. Laden Sie keine neuen Dateien mehr in Ihren SFTP-/FTP-Speicherort, Google Cloud Storage oder Google Sheets hoch.
  2. Rufen Sie in der Merchant Center-Benutzeroberfläche Ihre Dateidatenquelle auf und pausieren Sie den geplanten Abruf.
  3. Vorhandene Produkte, die zur Dateidatenquelle gehören, bleiben bis zu 30 Tage lang aktiv, bis sie über Ihre API-Integration eingefügt werden.

6. Warten, bis die Migration abgeschlossen ist, und überprüfen

Warten Sie, bis alle aktiven Produkte von der Dateidatenquelle zur API-Datenquelle migriert wurden. Bei inkrementellen Updates werden Produkte migriert, wenn sie sich ändern. Wenn Sie jedoch eine schrittweise vollständige Katalogsynchronisierung über Ihre reguläre Integration ausführen, wird die Migration des gesamten Katalogs beschleunigt (siehe Synchronisierungsstrategie und Kontingente).

In dieser Phase:

  1. Behalten Sie die Artikelanzahl auf der Merchant Center-Benutzeroberfläche im Blick. Warten Sie, bis die Anzahl der Dateidatenquellen auf 0 sinkt und die Anzahl der API-Datenquellen mit Ihrem aktiven Katalog übereinstimmt.
  2. Verwenden Sie products.get, um zu prüfen, ob Attribute und benutzerdefinierte Attributregeln wie erwartet zusammengeführt werden.
  3. Behalten Sie das API-Diagnose-Tool in der Merchant Center-Benutzeroberfläche im Auge, um Fehlerraten und API-Leistung zu verfolgen.

7. Dateidatenquelle außer Betrieb nehmen

Nachdem die Umstellung abgeschlossen ist und die Anzahl der Feedelemente in der Datei 0 beträgt:

  1. Prüfen Sie, ob die Aktualisierungen in Echtzeit angezeigt werden.
  2. Löschen Sie die alte Dateidatenquelle in der Merchant Center-Benutzeroberfläche, um zu verhindern, dass Ihre API-Daten durch versehentliche dateibasierte Aktualisierungen überschrieben werden.
Zurück
Migrate Local Inventory Ads settings