Amazon-API

Vorwort

Die folgenden Themen stammen aus der Arbeit eines Projekts aus dem Jahre 2015. Viele der Problematiken, wie z.B. das Encodingwirrwarr existieren noch bis heute.

Amazon: abenteuerliches Verkaufen

Die Zeit des stationären Handels als bevorzugte Einkaufsmöglichkeit rückt immer weiter aus dem Fokus. Einfacher und zeitsparender ist es “online” einkaufen zu gehen. Amazon als einer der Global Player bietet einen Großteil der Produkte an, die ein Normalsterblicher braucht. Durch die unkomplizierte Handhabung und große Beliebtheit bei den Konsumenten ist es auch für Verkäufer ein attraktiver Absatzkanal. Amazon suggeriert durch sein Auftreten einen einfachen und schnellen Verkauf. Leider war dem nicht so.

Ein Händler, der große Schwierigkeiten damit hatte, seine Produkte ordentlich und effektiv bei Amazon anzubieten, erteilte uns den Auftrag eine Softwarelösung zu entwickeln, um Informationen wie z.B. Produktnamen und -beschreibungen möglichst automatisiert bei Amazon einzustellen, bzw. zu aktualisieren.

Die Amazon API

Um bei Amazon Produkte zu verkaufen, kann man seine Produktinformationen auf 3 Arten hochladen. Für das Anlegen einzelner Produkte bietet Amazon ein einfach zu bedienendes Webinterface. Verkäufern, die eine große Produktpalette anbieten wollen, bietet Amazon die Möglichkeit diese über eine downloadbare Vorlage, ebenfalls im Webinterface zu finden, hochzuladen. Die Vorlage ist eine Datei im TSV-Format. Jeder Eintrag - d.h. jede Zeile in dieser Datei - repräsentiert dabei entweder ein Produkt oder eine Variante eines Produkts. Amazon bietet darüber hinaus ein API an, um Produktdaten ohne Nutzung der Weboberfläche zu übertragen. Diese ist der eben beschriebenen Variante sehr ähnlich, da die um die Daten der Produkte ergänzten Headerinformationen der Vorlage als Text an die Schnittstelle übergeben werden müssen. Wir entschieden uns aus folgenden Gründen, den letzteren Prozess zu benutzen:

1. Unsere Software können wir direkt an das Amazon-API anbinden.
2. Für den Händler entfällt die Notwendigkeit seine Produktinformationen manuell hochzuladen.

Wir ließen uns vom Kunden seine Erfahrung und die Besonderheiten des Amazon-Uploads erläutern, um ein erstes Verständnis der Funktionsweise des Uploads zu bekommen. Als wir zur Analyse der AmazonAPI kamen, stellten wir fest, dass es keine einfache Aufgabe werden würde.

Im Folgenden soll erläutert werden, wie richtig wir mit dieser Vermutung lagen.

Der Weg durch den Encoding-Irrgarten der Amazon-API

Unsere Software sollte Daten des Kunden nehmen und diese so aufbereiten, dass sie über das Amazon-API hochgeladen werden konnten. Diese Daten bilden zwar verschiedene Informationen über die Produkte unseres Kunden ab, am Ende ist es aber doch “nur” Text. Kommen wir also zum Thema Encoding.

Ein kleiner Exkurs dazu, um das nachfolgende Problem besser zu verstehen: Wie Menschen unterschiedliche Sprachen sprechen und einander mitunter nicht verstehen, können auch Computer Probleme haben, die Daten, die ihnen ein anderer Computer zugesandt hat, richtig zu interpretieren. Damit eine Kommunikation stattfinden kann, wird vereinbart, wie diese Daten zu verarbeiten sind, bzw. in unserem Fall: auf welche Weise der Text kodiert wurde. Es gibt verschiedene sogenannte Encodings, zu den bekanntesten dürften Latin-1 (ISO 8859-1) und UTF-8 gehören. (Angemerkt sei an dieser Stelle, dass so ein Encoding nicht nur darüber Auskunft gibt, wie die Daten als Text zu verarbeiten sind, sondern auch etwas darüber sagt, aus welchen Zeichen der Text überhaupt bestehen kann.)

Als Erstes ist uns aufgefallen, dass der hochzuladende String in Latin-1 kodiert sein muss, um überhaupt vom AmazonAPI erkannt zu werden. Das überraschte uns, da Amazon international operiert (75 Länder in 5 Kontinenten), sodass wir davon ausgingen, dass Amazon einen Zeichensatz verwendet, der möglichst viele Zeichen zulässt. Latin-1 ist ein Encoding, dessen Zeichensatz aus dem lateinischem Alphabet besteht. Warum also nicht ein Encoding verwenden, dass ein möglichst internationales Kontingent an Zeichen besitzt. Der Händler hielt seine Daten in UTF-8 vor, doch um Amazons Vorgaben gerecht zu werden, konvertierten wir den vollständig aufgebauten String zu Latin-1. Dies führte zu einigen Encodingfehlern, da der Kunde Zeichen verwendete, für die es in Latin-1 keine Entsprechung gibt, z.B. Breitenloses Leerzeichen und Auslassungspunkte.

Auf Wunsch des Kunden bauten wir zudem einen Export ein, der eine CSV-Datei mit dem von Amazon gewünschten Header und Daten produzierte. Somit konnte der Kunde auch die Methode nutzen, das CSV-File über das Verkäufer-Webinterface hochzuladen. Auch hier erlebten wir eine Überraschung: das Encoding Windows-1252 (CP-1252). Wieder ein Zeichensatz, der weniger Zeichen zulässt als UTF-8. Uns ist bis heute kein Grund eingefallen, warum Amazon erstens verschiedene Encodings für dieselbe Information erwartet und zweitens, warum überhaupt eines dieser Encodings verwendet wird und nicht UTF-8 in beiden Fällen.

Wir ließen uns auf diese verschiedenen Encodings für dieselbe Information ein und schritten voran. Die nächste Überraschung ließ nicht lange auf sich warten.

Der Boden bewegt sich

Um die nächste Herausforderung zu verstehen, müssen wir kurz die Bezeichnungen von Amazons Marketplacestruktur erläutern. Im linken Teil des folgenden Bildes haben wir versucht, die (interne) Hierarchie, wie sie sich uns bei der Arbeit mit den Templates von Amazon dargestellt hat abzubilden. Im rechten Teil des Bildes sehen wir die Hierachie wie sie auf der Amazonwebseite erscheint.

1. Template-Type: Fasst eine oder mehrere Hauptkategorien von Amazon zusammen, z.B. SportingGoods. Diese Ebene ist eine interne Struktur und für den Käufer unsichtbar. Jedes Template-Type enthält eine eigene Upload-Vorlage.
2. Hauptkategorien (Root-Browsenode): Sind die ersten sichtbaren Knoten auf Amazons Webseite, z.B. Sportschuhe
3. (Parent-)Browsenodes: Sind die jeweiligen Unterkategorien der Hauptkategorien, z.B. Herren und Damen.
4. Leaf-Browsenodes: Sind Unterkategorien der Unterkategorien. Beispiel: Pumps, Sneakers und Sport- & Outdoorschuhe. Wenn es verschiedene Unterkategorien “Sport- & Outdoorschuhe” gibt, ist diese Parent- (für verschiedene Sport- & Outdoorschuhe) und Leafbrowsenode (von Damen) zugleich. Jede Leafbrowsenode hat eine eindeutige Browsenodekennung, die eine Zahl ist.

Und hier kamen wir im Laufe der Entwicklung des Programms an unsere 2. Hürde. Amazon entschied sich während unserer Umsetzung Hauptkategorien in andere Template-Types zu verschieben. Da jeder Template-Type seine eigene Vorlage für das Erstellen und das Aktualisieren von Produkten hat, bekamen wir die Fehlermeldung, dass die Hauptkategorie nicht zum Template-Type passt. Folgendes war passiert: Die Hauptkategorie Kitchen gehörte ursprünglich zu dem Template-Type Home. Amazon erhob Kitchen zu einem eigenen Template-Type. Überraschenderweise nannte Amazon diesen ebenfalls Kitchen. Wir hatten also nun ein neues Template-Type Kitchen mit nur einer Hauptkategorie namens Kitchen. Diesem Umstand passten wir unsere Software an. Die nächste Hürde ließ allerdings nicht lange auf sich warten.

Die undurchsichtige Wanderung

Wir haben während der Entwicklungszeit mehrfach erlebt, dass Amazon Parent- und Leaf-Browsenodes in andere Root-Browsenodes verschoben hat. Jede Browsenode hat eine eindeutige Kennung, die man in dem “Browsenode-Tree-Guide” einsehen kann. Diese wird beim Hochladen des Produkts zur korrekten Kategorieplatzierung mitgegeben. Nehmen wir zum Beispiel an, die Browsenode “Haushalt/Küche/Möbel & Wohnaccessoires” hat die Kennung 123. Für die Verknüpfung von Browsenodes und deren Kennung gibt es Tabellen, die von Amazon bereitgestellt werden. Diese Kennung ist ebenfalls in der URL der Produkte zu sehen.

Wir nutzten diese Kennung beim Erstellen oder Aktualisieren z.B des Produkts Schmetterlingsticker. Nach erfolgtem Hochladen aber befand sich das Produkt nicht in der erwarteten Kategorie, sondern wir fanden es in “Haushalt/Baumarkt/Malerbedarf, Werkzeuge & Tapeten.” Was war geschehen? Aus uns unbekannten Gründen und ohne Erklärung oder Fehlermeldung hatte Amazon das Produkt während des Uploads in eine andere Browsenode(Kategorie) mit einer anderen Browsenodekennung einsortiert. Die Browsenodekennung im URI entsprach jedoch auch nicht der, die uns Amazon auf der Webseite nannte. Zumindest nicht, wenn die zu diesem Zeitpunkt aktuellste Tabelle für diese Verknüpfungen zu Rate gezogen wurde. Selbst als wir die Browsenodekennung (123 für “Haushalt/Küche/ Möbel & Wohnaccessoires”) manuell in die URL eingaben, wurden wir zu der anderen Browsenode, sprich zu “Haushalt/Baumarkt/Malerbedarf, Werkzeuge & Tapeten”, weitergeleitet. Es war jedoch nicht so, dass es die Browsenode mit der Kennung 123 nicht mehr gab. Über die reguläre Amazon-Webseite war die Kategorie noch zu finden. Dieses Redirecting zu anderen Browsenodes ist für den Laien nicht durchsichtig und kann auch zu wirtschaftlichen Nachteil führen, da man womöglich seine Zielgruppe verfehlt.

Die Sehnsucht nach dem Sandkasten

Der eine oder andere Leser mag sich mittlerweile gefragt haben, warum wir alles direkt in dem Livesystem gemacht haben und nicht erst einmal in einer Testumgebung. Die einfache Antwort: Weil es diese Möglichkeit nicht gab, weder für den Upload über das Webinterface, noch für das API. Zur kurzen Erläuterung: Eine Sandbox ist eine isolierte Umgebung, auf der man Programmcode testen kann, ohne das Livesystem zu verändern. Fehler in der Software oder in den Produktdaten haben in dieser Umgebung keine dramatischen Konsequenzen, da nur der Tester Zugriff auf die Sandbox besitzt. Das Fehlen eben dieser Sandbox bei Amazon bedeutet, dass jegliche Änderung an Produkten direkt auf das Livesystem angewendet werden. Für Verkäufer mit vielen verschiedenen Artikeln, wechselnder Beschreibung und häufigen Änderungen an Preisen kann das schwerwiegende Probleme verursachen, denn Preis- oder Beschreibungsfehler werden direkt für den Kunden sichtbar. Im Folgenden ein Beispiel.

Amazon API – Löschen impossible

So befüllten wir einmal bei ca. 100 Produkten ein optionales Attribut falsch. Nachdem wir den Fehler bemerkten, starteten wir einen zweiten Update-Upload. Dieses Mal ließen wir das zuvor falsch befüllte Feld für das Attribut leer, in der Hoffnung, dass dies den Inhalt der falsch befüllten Felder löschen würde. Ergebnis dieses Vorhabens: es passierte nichts. Amazon erkennt leere Felder als “nichts zu updaten”. Im Prinzip ist das auch richtig so: Ein leeres Feld in dem Upload als “Lösch den Wert” zu interpretieren, würde zu großen Problemen führen. Es müsste streng darauf geachtet werden, keine wertvollen Informationen auszulassen. Das Problem war viel mehr, dass es auch sonst keine Möglichkeit gab, ein Feld zu leeren. 100 Produkte mussten also von Hand nacheinander bearbeitet werden. Uns lief ein Schauer über den Rücken, als uns klar wurde, dass es versehentlich mehrere tausend Produkte hätte treffen können. Leider fehlte uns hier die genaue Dokumentation der Funktionsweise des Amazon-Uploads um dieses Problem auf eine einfachere Art zu lösen. Damit sind wir dann auch bei unserem Endgegner oder besser gesagt zum Metagegner angelangt.

Der Metagegner

Die wohl ärgerlichste Tatsache bei der Umsetzung unserer Software zur (automatisierten) Produktverwaltung war die ziemlich dürftige bis gänzlich fehlende Dokumentation. Sehr viel Zeit musste aufgebracht werden, die oben genannten Sachverhalte zu recherchieren. Viele Funktionsweisen, wie z.B. den CSV-Datei-Upload, mussten wir, wie im letzten Absatz angesprochen, schmerzhaft verstehen lernen.

Es ist normal, dass bei der Entwicklung von Software Umgebung und Schnittstellen analysiert werden müssen. Gute und vollständige Dokumentation dieser erleichtert jedoch die Arbeit und hilft Zeit und Ressourcen zu sparen. Leider war die Dokumentation in diesem Fall weder immer gut, noch immer vollständig. Als Ergänzung zu oben bereits geschilderten Problemen, hier nur ein paar Stichpunkte:

• Ein Umstand war, dass die für Verkäufer relevante Dokumentation nicht an einer zentralen Stelle abgelegt wurde. So mussten wir bei verschiedenen Sachverhalten Verlinkungen in Foren finden, die zu dem passenden Dokument führten.
• Auch wurden Problematiken oder Verständnisprobleme mehrfach von anderen Verkäufern in Amazons Sellerforum erfragt. Die Lösungen zu diesen Problemen wurden aber nicht in der dazugehörigen Dokumentation erfasst.
• Ein Manko bei den Beschreibungen der Schnittstellen, war es, dass Felder nicht als optional oder verpflichtend markiert wurden. Dies konnten wir nur mit Hilfe von anderen Verkäufern herausfinden, die selbst schon Erfahrungen damit gesammelt hatten.

Zum Schluss noch ein paar Ratschläge eines Veteranen für den Weg durch den Irrgarten

Da Amazon trotz alledem einer der größten Online-Marktplätze der Welt ist, geben wir euch diese Ratschläge mit auf dem Weg:

• Wenn ihr das API von Amazon benutzt, müsst ihr eure Daten in Latin-1 vorhalten. Benutzt ihr das Webinterface benötigt ihr eure Daten in CP-1252.

• Benutzt immer die neueste Version der Template-Type Vorlagen. Dort seht ihr ob es Änderungen in den Vorlagen gegeben hat.

• Aktualisiert euer Sortiment immer schrittweise, damit im Fehlerfall keine großen Änderungen gemacht werden müssen.

• Überprüft lieber zwei oder besser drei mal was ihr verändert habt, bevor ihr was abschickt. Änderungen gehen immer live.

• Überprüft nach erfolgreichem Upload, ob die Produktinformationen in den richtigen Browsenodes gelandet sind.