Import-Jobs
Import-Jobs führen Dateiimporte asynchron aus. Verwenden Sie diesen Vertrag, wenn eine Integration Daten vorbereitet, eine Datei hochlädt und den Import kontrolliert starten soll.
Ablauf
- Lesen Sie die Metadaten der Zielressource, bevor Sie eine Datei vorbereiten.
- Übernehmen Sie nur Felder, die die Metadaten für das Erstellen erlauben.
- Laden Sie die Importdatei über den vorgesehenen Storage-Upload der Workspace-Oberfläche oder API hoch.
- Erstellen Sie einen Import-Job mit
resourceType,fileId,modeund optionalen Optionen. - Lesen Sie den Job, bis Status, Zähler und Ergebnisreferenz vorliegen.
- Werten Sie den Report maschinenlesbar aus und zeigen Sie fachliche Fehler gezielt an.
POST/api/v1/import-jobs GET/api/v1/import-jobs/{id} GET/api/v1/import-jobs/_meta
Lesen Sie GET /api/v1/import-jobs/_meta, wenn ein Client Feldlisten, Aktions-URLs oder erlaubte Create-Felder maschinenlesbar braucht.
Dry Run und Apply
| Modus | Wirkung |
|---|---|
dry_run | Prüft Datei, Mapping, Pflichtfelder, Referenzen und Konflikte, ohne Zielressourcen zu verändern. |
apply | Führt den Import aus, wenn Validierung und Konfliktstrategie dies erlauben. |
Starten Sie neue Integrationen immer mit dry_run. Prüfen Sie danach Zähler, Zeilenfehler und Konflikte. Wechseln Sie erst auf apply, wenn die Datei fachlich freigegeben ist.
Setzen Sie mode explizit, damit Automationen eindeutig zwischen Prüfung und Ausführung unterscheiden. Verlassen Sie sich nicht auf implizite Defaults.
Mapping und Referenzen
Nutzen Sie options.mapping, wenn CSV-Spalten nicht exakt den Zielfeldern entsprechen. Mappen Sie Quellspalten auf die kanonischen Feldnamen der Zielressource, zum Beispiel auf name, slug, parent_id oder parent_slug, wenn der jeweilige Importvertrag diese Felder anbietet.
Beachten Sie diese Regeln:
- Senden Sie nur Felder, die
/_metafür die Zielressource erlaubt. - Mappen Sie Legacy-Spalten explizit, statt sie im Client umzubenennen und unprüfbar zu machen.
- Nutzen Sie fachliche Schlüssel nur so, wie die Zielressource sie beschreibt.
- Erzeugen Sie fehlende Referenzen nicht still während des Imports.
- Beheben Sie Referenzfehler vor dem nächsten Lauf in den Stammdaten oder in der Importdatei.
Konfliktstrategie
Importe verwenden eine explizite Konfliktstrategie:
| Wert | Wirkung |
|---|---|
fail | Konflikte erzeugen Zeilenfehler. |
update | Bestehende Datensätze werden über den fachlichen Schlüssel aufgelöst und aktualisiert. |
skip | Bestehende Datensätze werden als übersprungen gezählt. |
Wählen Sie die Strategie bewusst pro Integration. Nutzen Sie fail, wenn Datenqualität wichtiger ist als Durchsatz. Nutzen Sie update nur, wenn der fachliche Schlüssel eindeutig ist. Nutzen Sie skip, wenn bestehende Datensätze unangetastet bleiben sollen.
Validierungsfehler
Import-Jobs melden Fehler pro Zeile. Ein Fehler bedeutet nicht automatisch, dass die gesamte Datei unbrauchbar ist. Prüfen Sie status, errorCode und errorParams, bevor Sie dem Nutzer eine Meldung anzeigen.
Typische Fehler betreffen:
- nicht erlaubte oder unbekannte Spalten
- fehlende Pflichtfelder
- ungültige Werte
- fehlende oder mehrdeutige Referenzen
- Konflikte mit bestehenden Datensätzen
Nutzen Sie errorCode und errorParams für lokalisierte UI-Texte. Parsen Sie keine freien Fehlermeldungen, weil diese nur als lesbare Diagnose gedacht sind.
Reports und Zähler
Ein abgeschlossener Job liefert Zähler wie verarbeitete, erstellte, aktualisierte, übersprungene und fehlerhafte Zeilen. Der Ergebnisreport verweist auf ein Storage-Objekt und enthält pro Zeile strukturierte Fehler:
| Feld | Bedeutung |
|---|---|
line | Zeilennummer aus der Importdatei. |
status | Ergebnis der Zeile. |
error | Lesbare Fehlerbeschreibung, wenn die Zeile fehlgeschlagen ist. |
errorCode | Stabiler Fehlercode für Übersetzung und Automatisierung. |
errorParams | Parameter für lokalisierte Fehlermeldungen. |
Job-Statuswerte sind uploaded, parsing, validating, applying, completed, partial und failed.
Die Job-Antwort enthält neben status auch totalRows, processedRows, createdCount, updatedCount, skippedCount, errorCount, resultRef, lastError, requestedBy, startedAt und finishedAt. Nutzen Sie Zähler und resultRef für Automatisierung; zeigen Sie lastError nur als ergänzende Diagnose an.
Reports sicher nutzen
Reports können Personen-, Kontakt-, Produkt-, Preis- oder Geschäftsdaten enthalten. Behandeln Sie sie wie importierte Quelldaten.
- Speichern Sie Report-Links nur dort, wo berechtigte Nutzer sie brauchen.
- Teilen Sie Reports nicht über öffentliche Tickets, Chat-Kanäle oder Screenshots.
- Kürzen Sie Reports in UIs, wenn viele Zeilen betroffen sind.
- Protokollieren Sie nur stabile Fehlercodes, Zähler und technische Job-IDs.
- Entfernen Sie Importdateien und Reports nach den Aufbewahrungsregeln Ihrer Organisation.
Integrationshinweise
- Starten Sie neue Integrationen mit
dry_run. - Erzeugen Sie fehlende Referenzen nicht still während des Imports.
- Nutzen Sie den Natural Key der Zielressource nur so, wie der jeweilige Importvertrag ihn definiert.
- Nutzen Sie
errorCodeunderrorParamsfür UI-Texte. Parsen Sie keine freien Fehlermeldungen. - Begrenzen Sie gespeicherte Reports auf den notwendigen Kreis, wenn sie Personen-, Kontakt- oder Geschäftsdaten enthalten.