Custom JSON Zielkonfiguration: Technische Dokumentation und Feldmapping

Einführung in Custom JSON Ziele

Custom JSON Ziele ermöglichen es Ihnen, Produktdaten in einem benutzerdefinierten JSON-Format an beliebige Zielplattformen zu übertragen. Diese Lösung bietet maximale Flexibilität für Integrationen, die nicht durch vordefinierte Kanäle abgedeckt werden. Mit Custom JSON können Sie die Feldstruktur, Datentypen und das Ausgabeformat vollständig nach den Anforderungen Ihrer Zielplattform gestalten.

Diese technische Dokumentation beschreibt die Konfiguration von Custom JSON Destinationen, das Feldmapping, die JSON-Schemastruktur und bewährte Praktiken für die Implementierung.

Custom JSON Ziel-Konfigurationsdatei

Jedes Custom JSON Ziel wird durch eine Konfigurationsdatei definiert, die die Feldmappings, Datentypen und Validierungsregeln festlegt. Die Konfigurationsdatei verwendet das JSON-Format und wird beim Setup der Destination hinterlegt.

Grundstruktur der Zielkonfiguration

Eine typische Custom JSON Konfiguration hat folgende Struktur:

{
  "destination_name": "Mein Custom JSON Ziel",
  "destination_type": "custom_json",
  "output_format": "json",
  "field_mappings": [
    {
      "source_field": "title",
      "target_field": "product_name",
      "data_type": "string",
      "required": true
    },
    {
      "source_field": "price",
      "target_field": "selling_price",
      "data_type": "decimal",
      "required": true
    }
  ],
  "root_element": "products",
  "item_element": "product"
}

Die Konfiguration definiert, welche Quellfelder aus Ihrem Produktdatenbestand in welche Zielfelder abgebildet werden und welche Datentypen erwartet werden.

Feldmapping und Datentypen

Das Feldmapping ist das Herzstück der Custom JSON Konfiguration. Jedes Feldmapping verbindet ein Quellfeld mit einem Zielfeld und definiert dessen Datentyp und Validierungsregeln.

Unterstützte Datentypen

Feldmapping Konfigurationsoptionen

Jedes Feldmapping kann folgende Optionen enthalten:

• source_field: Der Name des Feldes aus Ihrem Produktdatenbestand.
• target_field: Der Name des Feldes in der JSON-Ausgabe.
• data_type: Der erwartete Datentyp (string, integer, decimal, boolean, array, object, date, url).
• required: Boolean-Wert, der angibt, ob das Feld erforderlich ist (true/false).
• default_value: Standardwert, wenn das Quellfeld leer ist.
• transform: Transformationsregel für Datenwerte (z.B. Umrechnung von Einheiten).
• validation_pattern: Regulärer Ausdruck für Validierung von Feldwerten.
• max_length: Maximale Zeichenlänge für String-Felder.
• min_value / max_value: Minimale und maximale Werte für numerische Felder.

Praktische Implementierung von Custom JSON Zielen

Schritt 1: Zielstruktur definieren

Bestimmen Sie zunächst, wie die JSON-Ausgabe strukturiert sein soll. Dies hängt von den Anforderungen Ihrer Zielplattform ab. Die meisten Ziele erwarten entweder ein Array von Produktobjekten oder ein Root-Element mit verschachtelten Produkten.

Beispiel für Array-Struktur:

[
  {
    "id": "12345",
    "name": "Produkt A",
    "price": 29.99
  },
  {
    "id": "12346",
    "name": "Produkt B",
    "price": 39.99
  }
]

Beispiel für Root-Element-Struktur:

{
  "products": [
    {
      "id": "12345",
      "name": "Produkt A",
      "price": 29.99
    }
  ]
}

Schritt 2: Feldmappings konfigurieren

Definieren Sie für jedes Zielfeld ein entsprechendes Quellfeld aus Ihrem Produktdatenbestand. Achten Sie darauf, dass alle erforderlichen Felder gemappt sind. Fehlende erforderliche Felder führen zu Validierungsfehlern und können zur Ablehnung von Produkten führen.

Zum Beispiel:

• title (Quelle) → product_name (Ziel): string, erforderlich
• price (Quelle) → selling_price (Ziel): decimal, erforderlich
• description (Quelle) → product_description (Ziel): string, optional
• image_link (Quelle) → image_url (Ziel): url, erforderlich
• availability (Quelle) → stock_status (Ziel): string, erforderlich

Schritt 3: Validierungsregeln anwenden

Definieren Sie Validierungsregeln, um sicherzustellen, dass nur hochwertige Daten an Ihr Ziel übertragen werden. Diese Regeln verhindern, dass fehlerhafte oder unvollständige Daten die Zielplattform erreichen.

Beispiele für Validierungsregeln:

• Minimale Titellänge: 10 Zeichen
• Maximale Titellänge: 150 Zeichen
• Preise müssen größer als 0 sein
• Image Links müssen mit https:// beginnen
• Verfügbarkeitsstatus muss einer vordefinierten Liste entsprechen (in stock, out of stock, preorder)

Schritt 4: Transformationen definieren

Verwenden Sie Transformationen, um Daten aus dem Quellformat in das Zielformat umzuwandeln. Dies ist besonders hilfreich, wenn Ihre Zielplattform andere Formate oder Einheiten erwartet.

Beispiele für Transformationen:

• Währungsumrechnung: EUR zu GBP
• Einheitsumrechnung: Kilogramm zu Pfund
• Formatierung: Datumsformat von DD/MM/YYYY zu YYYY-MM-DD
• Textmanipulation: Großbuchstaben in Kleinbuchstaben umwandeln
• Wertmapping: "in_stock" zu "available"

Erweiterte Custom JSON Konfigurationen

Verschachtelte Objekte und Arrays

Für komplexe Ziele können Sie verschachtelte Objekte und Arrays konfigurieren. Dies ermöglicht es, mehrere verwandte Daten in einer strukturierten Form zu übertragen.

Beispiel für verschachtelte Objekte:

{
  "source_field": "brand",
  "target_field": "manufacturer.name",
  "data_type": "string"
}

Beispiel für Arrays:

{
  "source_field": "categories",
  "target_field": "product_categories",
  "data_type": "array",
  "item_type": "string"
}

Bedingte Feldmappings

Einige Ziele erfordern bedingte Logik im Feldmapping. Sie können Bedingungen definieren, unter denen bestimmte Felder gemappt oder transformiert werden.

Beispiel:

{
  "source_field": "price",
  "target_field": "discount_price",
  "data_type": "decimal",
  "condition": "source.sale_price < source.price",
  "transform": "source.sale_price"
}

Häufige Fehlerquellen und Lösungen

Bei der Konfiguration von Custom JSON Zielen treten häufig bestimmte Probleme auf. Hier sind die häufigsten Fehlerquellen und deren Lösungen:

Fehlende erforderliche Felder: Wenn erforderliche Felder nicht gemappt sind, werden Produkte abgelehnt. Überprüfen Sie die Zielplattform-Dokumentation und stellen Sie sicher, dass alle erforderlichen Felder konfiguriert sind.

Ungültige Datentypen: Wenn Daten nicht dem erwarteten Datentyp entsprechen, können Validierungsfehler auftreten. Verwenden Sie Transformationen, um Daten in das korrekte Format umzuwandeln.

Ungültige URLs: Image Links und andere URLs müssen mit einem gültigen Protokoll beginnen (http:// oder https://). Verwenden Sie Validierungsmuster, um ungültige URLs zu erkennen.

Zu lange Texte: Viele Ziele haben Längenbeschränkungen für Textfelder. Definieren Sie max_length Werte und kürzen Sie Texte entsprechend.

Fehlende oder leere Felder: Verwenden Sie default_value Optionen, um Fallback-Werte bereitzustellen, wenn Quellfelder leer sind.

Praktische Anleitung für Händler

Händler verwenden Custom JSON Ziele in folgenden Szenarien:

Integration mit benutzerdefinierten Plattformen: Wenn Sie eine eigene E-Commerce-Plattform oder ein internes System haben, können Sie Custom JSON Ziele verwenden, um Produktdaten automatisch zu synchronisieren.

Anbindung spezialisierter Marktplätze: Für Nischenmärkte oder spezialisierte Plattformen, die nicht in den vordefinierten Kanälen verfügbar sind, ermöglichen Custom JSON Ziele die Datenverteilung.

API-Integrationen: Viele APIs akzeptieren JSON-Eingaben. Mit Custom JSON Zielen können Sie Ihre Produktdaten direkt an API-Endpunkte senden.

Datenverarbeitung und Analysen: Sie können Custom JSON Ziele verwenden, um Produktdaten in strukturierter Form für Datenverarbeitungs- oder Analyseplattformen bereitzustellen.

Schritt-für-Schritt Konfigurationsanleitung

1. Anforderungen sammeln: Dokumentieren Sie alle Anforderungen der Zielplattform. Dies umfasst erforderliche Felder, Datentypen, Längenbeschränkungen und Validierungsregeln.

2. Feldmapping planen: Erstellen Sie eine Tabelle, die Quellfelder auf Zielfelder abbildet. Identifizieren Sie Felder, die transformiert werden müssen.

3. Konfigurationsdatei erstellen: Schreiben Sie die JSON-Konfigurationsdatei mit allen Feldmappings und Validierungsregeln.

4. Validierung testen: Führen Sie einen Test mit einer kleinen Produktmenge durch, um sicherzustellen, dass die Konfiguration korrekt ist.

5. Fehler beheben: Überprüfen Sie Validierungsfehler und passen Sie die Konfiguration an.

6. Vollständigen Feed aktivieren: Sobald die Konfiguration validiert ist, können Sie den vollständigen Produktfeed aktivieren.

7. Monitoring: Überwachen Sie den Feed regelmäßig, um sicherzustellen, dass alle Produkte korrekt übertragen werden.

JSON Destinationen und Ausgabeformate

Custom JSON Ziele unterstützen verschiedene Ausgabeformate, je nach Anforderungen der Zielplattform:

Newline-Delimited JSON (NDJSON): Jedes Produkt ist ein separates JSON-Objekt auf einer eigenen Zeile. Dies ist ideal für Streaming und große Datenmengen.

JSON Array: Alle Produkte sind in einem Array enthalten. Dies ist das Standard-Format für die meisten REST-APIs.

JSON Lines: Ähnlich wie NDJSON, aber mit zusätzlichen Metadaten für jede Zeile.

Pretty-Printed JSON: Formatiertes JSON mit Einrückungen für bessere Lesbarkeit. Dies wird normalerweise für Debugging verwendet.

Wählen Sie das Ausgabeformat basierend auf den Anforderungen Ihrer Zielplattform.

Zusammenfassung und nächste Schritte

Custom JSON Ziele bieten maximale Flexibilität für die Produktdatenverteilung an beliebige Plattformen. Durch sorgfältige Planung des Feldmappings, Definition von Validierungsregeln und Anwendung von Transformationen können Sie sicherstellen, dass Ihre Produktdaten in der richtigen Form bei Ihrer Zielplattform ankommen.

Die wichtigsten Schritte sind:

1. Verstehen Sie die Anforderungen Ihrer Zielplattform vollständig.
2. Planen Sie das Feldmapping sorgfältig.
3. Definieren Sie robuste Validierungsregeln.
4. Testen Sie die Konfiguration mit einer kleinen Produktmenge.
5. Überwachen Sie den Feed regelmäßig auf Fehler.

Bei Fragen oder Problemen mit Ihrer Custom JSON Zielkonfiguration konsultieren Sie die technische Dokumentation Ihrer Zielplattform oder kontaktieren Sie den technischen Support. Mit den richtigen Konfigurationen können Custom JSON Ziele eine zuverlässige Methode zur Automatisierung Ihrer Produktdatenverteilung sein.