Fehlerbehebung beim Export
Auf dieser Seite können Sie Probleme mit CSV- und API-Exporten im Dashboard und in den Export-APIs diagnostizieren. Informationen zu Export-Workflows und -Limits finden Sie unter Segmentdaten als CSV exportieren und Export-APIs.
Hier starten: Ihr Symptom zuordnen
Suchen Sie in der Tabelle nach dem Verhalten, das Sie beobachten, und wechseln Sie dann zum entsprechenden Abschnitt für gezielte Prüfungen.
| Symptom | Weiter zu |
|---|---|
Der Download-Link für die CSV-Datei gibt AccessDenied, ExpiredToken oder „Datei existiert nicht“ zurück |
Standardexport: CSV-Fehler oder Cloud-Speicher: CSV-Fehler |
Die Download-URL des API-Exports gibt 403 Forbidden zurück |
Exportierte Segment-ZIP-Datei kann nicht heruntergeladen werden |
| Der Segment-Export schlägt fehl oder meldet, dass das Segment zu groß ist | Segment ist zu groß |
| Keine E-Mail zum Segment-Export erhalten | Keine E-Mail zum Segment-Export |
| Die Zeilenanzahl der CSV-Datei stimmt nicht mit den Campaign-Analytics überein | Abweichung bei Campaign- und Canvas-Analytics |
| Erwartete Spalten fehlen in der Exportdatei | Fehlende Spalten |
Der Export in den Cloud-Speicher zeigt AccessDenied oder ExpiredToken |
Cloud-Speicher verbunden: API-Fehler |
Standardvorgehen bei der Untersuchung
Verwenden Sie diesen Ablauf für jeden Export-Vorfall. Beginnen Sie mit Schritt 1.
- Klären Sie, ob Sie in den standardmäßigen Braze-S3-Bucket oder zu einem verbundenen Cloud-Speicher-Partner exportieren. Ablauf der Links und Wiederholungsverhalten unterscheiden sich zwischen beiden Optionen.
- Stellen Sie bei CSV-Exporten aus dem Dashboard sicher, dass Sie beim Öffnen des Download-Links bei Braze angemeldet sind. Links zum Standard-Bucket erfordern eine aktive Dashboard-Sitzung.
- Prüfen Sie, wie lange der Abschluss des Exports zurückliegt. Per E-Mail versendete Download-Links aus dem Dashboard laufen nach vier Stunden ab, unabhängig davon, ob Sie den standardmäßigen Braze-Bucket oder einen verbundenen Speicher-Partner nutzen. Wenn ein Speicher-Partner verbunden ist, liefert Braze zusätzlich eine Kopie in Ihren Bucket. Diese Kopie unterliegt Ihren Aufbewahrungsrichtlinien und kann auch nach Ablauf des E-Mail-Links noch verfügbar sein.
- Stellen Sie bei großen Segment-Exporten sicher, dass die Zielgruppe unter dem Limit von 500.000 Nutzer:innen für CSV-Exporte aus dem Dashboard liegt. Die Schätzungen im Segment-Builder können von der Auswertung in der Export-Pipeline abweichen.
- Warten Sie bei API-Exporten, bis die Verarbeitung abgeschlossen ist, bevor Sie herunterladen. Verwenden Sie
callback_endpointbei/users/export/segmentoder fragen Sie den Status mit exponentiellem Backoff ab, anstatt die URL sofort aufzurufen. - Wenn Sie weiterhin nicht weiterkommen, wenden Sie sich an den Braze-Support und geben Sie den Export-Typ (CSV oder API), die Segment- oder Campaign-ID, den Zeitstempel (mit Zeitzone) und die genaue Fehlermeldung an.
Speicherziele
Verwenden Sie die Tabs, um auszuwählen, ob Sie in den Standard-S3-Bucket von Braze oder zu einem Cloud-Speicher-Partner exportieren. Für Anleitungen zum Cloud-Speicher öffnen Sie den Tab Cloud-Speicher verbunden und lesen Sie die Abschnitte zu CSV und API.
Wenn Sie keinen Speicherpartner als Standard-Exportziel festgelegt haben, verwendet Braze seinen eigenen Amazon S3-Bucket, um Ihre Exportdateien zu speichern. Die Dateien in dieser Konfiguration sind temporär und verfallen nach vier Stunden.
CSV-Exporte
Symptom: Eine E-Mail zum Dashboard-CSV-Export trifft ein, aber der Download-Link funktioniert nicht, oder der Export wird nicht abgeschlossen.
Wenn Sie eine CSV-Datei aus dem Dashboard exportieren, sendet Braze einen Download-Link per E-Mail an die angemeldete Nutzer:in. Dieser Link verweist auf eine ZIP-Datei, die im S3-Bucket von Braze gehostet wird. Die ZIP-Datei enthält mehrere kleinere Dateien, die zusammen Ihren Export bilden.
Sie müssen im Braze-Dashboard angemeldet sein, um den Link nutzen zu können, und die Datei ist nur vier Stunden lang verfügbar. Danach ist der Link nicht mehr funktionsfähig und die Daten werden gelöscht. Sollten bei sehr umfangreichen Exporten (über 500.000 Nutzer:innen) wiederholt Fehler auftreten, kann der Export fehlschlagen. In diesem Fall empfehlen wir, den Export in kleinere Gruppen oder Felder aufzuteilen oder die Einrichtung eines Speicherpartners in Betracht zu ziehen.
Häufige Fehler
- Wenn Sie einen
AccessDenied-Fehler sehen, ist die Datei möglicherweise bereits abgelaufen, oder Sie haben versucht, sie zu öffnen, bevor sie bereit war. Größere Berichte benötigen mehr Zeit für die Erstellung – warten Sie einige Minuten und versuchen Sie es erneut. - Ein
ExpiredToken-Fehler bedeutet, dass das vierstündige Zeitfenster abgelaufen ist. Führen Sie den Export erneut aus, um einen neuen Link zu generieren. - Die Nachricht
Looks like the file doesn't exist anymorewird in der Regel angezeigt, wenn die E-Mail gesendet wurde, die Datei jedoch noch nicht vollständig auf S3 hochgeladen wurde. In der Regel lässt sich das Problem durch einige Minuten Wartezeit beheben. - Apostrophe am Anfang bestimmter Felder (wie
-,=,+oder@) sind erwartetes Verhalten. Beispielsweise wird-1943in der CSV-Datei zu'-1943. Braze tut dies, um zu verhindern, dass Tabellenkalkulationsprogramme die Daten falsch interpretieren. Dies gilt nicht für JSON-Exporte, wie sie etwa vom Endpunkt/users/export/segmentzurückgegeben werden.
API-Exporte
Symptom: Ein Export-API-Aufruf ist erfolgreich, aber die Download-URL funktioniert nicht oder gibt leere Daten zurück.
Wenn Sie über die Export-APIs ohne Cloud-Speicher exportieren, speichert Braze die Dateien in seinem S3-Bucket. Sie erhalten keine E-Mail – stattdessen enthält die API-Antwort eine temporäre Download-URL. Der Export erfolgt als ZIP-Datei, die mehrere JSON-Dateien enthält, wobei jede Datei eine Nutzer:in pro Zeile enthält.
Wie bei CSV-Exporten verfallen auch Links aus der API nach vier Stunden. Wenn Sie den Link zu früh öffnen, können Fehler auftreten, da die Datei noch nicht bereit ist. Sie können in Ihrer Anfrage einen callback_endpoint angeben, falls Sie von Braze benachrichtigt werden möchten, sobald die Datei verfügbar ist.
Umfangreiche API-Exporte können ebenfalls zu Zeitüberschreitungen führen. Sollte dies der Fall sein, versuchen Sie, kleinere Anfragen zu stellen, oder verbinden Sie einen Speicherpartner, um das Volumen zu bewältigen.
Häufige Fehler
AccessDeniedoderExpiredTokenbedeutet in der Regel, dass der Link abgelaufen oder noch nicht verfügbar war. Führen Sie den Export erneut durch oder warten Sie etwas länger.
Wenn Sie einen Speicherpartner (wie Amazon S3, Google Cloud Storage oder Azure Blob) verbinden und ihn auf der Seite Technologie-Partner im Dashboard als Ihr Standard-Exportziel markieren, schreibt Braze Ihre Exporte direkt in Ihren Bucket. Diese Konfiguration ist in der Regel für umfangreichere Exporte zuverlässiger.
CSV-Exporte
Symptom: Der per E-Mail versandte CSV-Link funktioniert nicht, aber Dateien erscheinen (oder erscheinen nicht) in Ihrem verbundenen Bucket.
Bei CSV-Exporten sendet Ihnen Braze einen Download-Link per E-Mail. Dieser Link läuft nach einer kurzen Zeitspanne ab (in der Regel nach etwa vier Stunden). Wenn Sie einen Speicherpartner verbunden und als Standard-Exportziel festgelegt haben, liefert Braze auch eine Kopie des Exports an Ihren verbundenen Bucket. Diese Kopie wird in Ihrer eigenen Infrastruktur gespeichert, wobei Ablauf und Aufbewahrung Ihren Speicherrichtlinien entsprechen.
Im Cloud-Speicher werden CSV-Exporte in einer ZIP-Datei gebündelt. Die ZIP-Datei enthält mehrere kleinere CSV-Dateien. Umfangreiche Exporte werden häufig in Teile aufgeteilt (beispielsweise jeweils etwa 5.000 Nutzer:innen), wobei die Größe der Teile variieren kann. Kleinere Dateien bedeuten nicht, dass Daten fehlen. Sollte der per E-Mail versandte Link nicht funktionieren, die Kopie in Ihrem Speicher jedoch erfolgreich sein, können Sie Ihre Daten jederzeit direkt aus Ihrem Bucket abrufen.
Häufige Fehler
AccessDeniedbedeutet, dass Braze nicht in Ihren Bucket schreiben konnte. Überprüfen Sie, ob Ihre Zugangsdaten und Berechtigungen weiterhin gültig sind.ExpiredTokenwird angezeigt, wenn Braze den Zugriff auf Ihren Bucket verloren hat. Aktualisieren Sie Ihre Zugangsdaten im Braze-Dashboard.- Sollten einige Dateien kleiner als erwartet erscheinen, ist dies normales Verhalten. Der Exportvorgang teilt Dateien aus Stabilitätsgründen absichtlich auf.
- Apostrophe am Anfang bestimmter Felder (wie
-,=,+oder@) sind erwartetes Verhalten. Beispielsweise wird-1943in der CSV-Datei zu'-1943. Braze tut dies, um zu verhindern, dass Tabellenkalkulationsprogramme die Daten falsch interpretieren. Dies gilt nicht für JSON-Exporte, wie sie etwa vom Endpunkt/users/export/segmentzurückgegeben werden.
API-Exporte
Symptom: API-Exporte erscheinen nicht in Ihrem Bucket oder Dateien sind unvollständig.
Wenn Sie Daten über die APIs mit einem verbundenen Speicherpartner exportieren, werden die Exportdateien in Ihren Bucket geschrieben. Es wird keine E-Mail versendet. Die zugrunde liegenden Objekte werden in Ihrem Speicher aufbewahrt und unterliegen Ihren Aufbewahrungseinstellungen, auch wenn die von Braze zurückgegebenen Download-URLs möglicherweise weiterhin zeitlich begrenzt sind.
Dateien erscheinen in der Regel in Ihrem Bucket, während der Export läuft, sodass Sie nicht warten müssen, bis der gesamte Vorgang abgeschlossen ist, bevor Sie auf Teilergebnisse zugreifen. Braze lädt jeden abgeschlossenen Batch inkrementell hoch, anstatt alles bis zum Ende zurückzuhalten. Umfangreiche Exporte werden in mehrere komprimierte Dateien (ZIP oder GZIP) aufgeteilt, die jeweils JSON-Objekte enthalten, eines pro Zeile. Das macht diese Methode für umfangreiche Exporte zuverlässiger.
Häufige Fehler
AccessDeniedtritt auf, wenn Braze nicht in Ihren Bucket schreiben kann oder die Objekte anschließend gelöscht wurden. Überprüfen Sie die Berechtigungen und stellen Sie sicher, dass keine externen Prozesse Dateien löschen.ExpiredTokenbedeutet, dass die Zugangsdaten von Braze für Ihren Bucket veraltet sind. Aktualisieren Sie diese im Dashboard.- Sollten Dateien fehlen oder kleiner als erwartet sein, überprüfen Sie zunächst, ob Objekte außerhalb von Braze gelöscht werden. Kleinere Dateigrößen selbst sind erwartetes Verhalten.
Campaign- und Canvas-Analytics
Anzahl der Nutzer:innen im CSV-Export stimmt nicht mit Gesendete Nachrichten oder Eindeutige Empfänger:innen überein
Symptom: Der CSV-Export einer Campaign zeigt eine andere Nutzerzahl als Gesendete Nachrichten oder Eindeutige Empfänger:innen auf der Analytics-Seite.
Der CSV-Export einer Campaign kann aus folgenden Gründen eine andere Anzahl von Nutzer:innen anzeigen als Gesendete Nachrichten und Eindeutige Empfänger:innen:
Die erneute Teilnahmeberechtigung ist aktiviert
Wenn Nutzer:innen die Campaign mehr als einmal erhalten können (oder zu einem früheren Zeitpunkt konnten), stimmen die Analytics-Zahlen der Campaign und die Anzahl der Zeilen im Export der Nutzerdaten nicht überein. Gesendete Nachrichten zählt jeden Versand, auch wenn dieselbe Person mehrfach eine Nachricht erhält. Der Download CSV-Export Nutzerdaten listet eindeutige Nutzer:innen auf – eine Zeile pro Profil, das die Campaign erhalten hat –, nicht eine Zeile pro Versand. Wenn Gesendete Nachrichten beispielsweise 12 beträgt und die CSV-Datei 10 Zeilen enthält, gingen diese 12 Sendungen an 10 verschiedene Nutzer:innen (einige Nutzer:innen haben die Campaign mehr als einmal erhalten).
Nutzer:innen wurden seit dem Versand der Campaign oder des Canvas gelöscht oder zusammengeführt
Der CSV-Export liefert eine Momentaufnahme der bestehenden Nutzer:innen, die eine bestimmte Campaign oder ein bestimmtes Canvas erhalten haben. Da Nutzer:innen gelöscht oder zusammengeführt werden können, kann die Anzahl im CSV-Export niedriger sein als die Anzahl der eindeutigen Empfänger:innen. Wenn beispielsweise 1.000 Nutzer:innen eine Campaign erhalten, zeigt die Campaign 1.000 eindeutige Empfänger:innen an, und der CSV-Export am selben Tag zeigt ebenfalls 1.000 Nutzer:innen. Werden einen Monat später 50 dieser 1.000 Nutzer:innen gelöscht, enthält der CSV-Export 950 Nutzer:innen, während die hochgezählte Anzahl eindeutiger Empfänger:innen weiterhin 1.000 beträgt.
Dashboard-Segment-Export-E-Mails
Segment ist zu groß oder Export schlägt fehl, obwohl mein Segment unter 500.000 Nutzer:innen zu liegen scheint
Symptom: Der Segment-Export im Dashboard schlägt fehl oder zeigt einen Größenfehler an, obwohl die Segment-Schätzung akzeptabel aussieht.
Die Segmentgröße im Dashboard ist eine Schätzung. Der CSV-Export verwendet diese Schätzung, um das Exportlimit von 500.000 Nutzer:innen durchzusetzen. Die Export-Pipeline kann die Größe außerdem anders bewerten als die UI des Segment-Builders. Wenn Exporte für ein Segment nahe diesem Schwellenwert fehlschlagen, verwenden Sie zufällige Bucket-Nummern oder teilen Sie die Zielgruppe in kleinere Segmente auf. Alternativ können Sie den Endpunkt /users/export/segment verwenden, wie unter Große Segmente exportieren beschrieben.
Warum erhalte ich keine E-Mails zum Segment-Export?
Symptom: Ein CSV-Export eines Segments wurde getriggert, aber es ist keine E-Mail angekommen.
Prüfen Sie zunächst Ihren Spam-Ordner auf eine E-Mail von [email protected]. Falls die E-Mail dort liegt, fügen Sie diese Adresse Ihrer Liste sicherer Absender hinzu, damit zukünftige Export-Nachrichten nicht gefiltert werden.
Falls die E-Mail nicht in Ihrem Spam-Ordner ist, prüfen Sie, ob eine andere Person in Ihrem Team den Export erhalten kann. Ist das nicht der Fall, berücksichtigen Sie die Größe Ihres Exports. Die Zustellungsdauer hängt von der Exportgröße ab. Wenn die E-Mail jedoch nach einer Stunde noch nicht angekommen ist, wenden Sie sich an den Support.
Segment-Export-API-Downloads
Eine exportierte Segment-ZIP-Datei kann nicht von einer Braze-URL heruntergeladen werden
Symptom: Beim Herunterladen von der Antwort-URL des Endpunkts /users/export/segment tritt ein 403 Forbidden-Fehler auf.
Wenn Sie bei der Verwendung des Endpunkts /users/export/segment einen 403 Forbidden-Fehler erhalten, ist die Datei möglicherweise noch nicht bereit. Die Verarbeitung großer Exporte kann einige Zeit dauern. Warten Sie bis zu einer Stunde, bevor Sie den Download erneut versuchen.
Wenn Sie die Datei mit einem automatisierten Skript abrufen, erhalten Sie möglicherweise ebenfalls einen 403 Forbidden-Fehler, wenn Sie die URL zu früh anfragen. Wenn Sie regelmäßig Segment-Daten exportieren, sollten Sie eine eigene S3-Bucket-Integration verbinden und die Dateien an Ihre eigene ETL-Pipeline (Extract, Transform, Load) übergeben.
Exporte benötigen Zeit, bis sie abgeschlossen sind. Ein sofortiger Zugriff per Skript schlägt daher häufig fehl. Sie haben folgende Möglichkeiten:
- Fragen Sie die Download-URL mit exponentiellem Backoff ab, oder
- Verwenden Sie den Parameter
callback_endpointund richten Sie ihn auf einen Dienst, der Ihr Skript ausführt, sobald der Export bereit ist.
API-Felder für Segment- und Nutzerexporte
In einer Segment-Exportdatei fehlen erwartete Spalten
Symptom: In einem API- oder Dashboard-Export fehlen Felder, die Sie erwartet haben.
Der Dashboard-Export CSV Export User Data aus einem Segment verwendet einen festen Spaltensatz (siehe Segmentdaten als CSV exportieren). Er enthält weder eine Spalte noch einen Parameter fields_to_export.
Bei Segment-Exporten über die API müssen Sie fields_to_export im Request-Body übergeben. Einige Felder ziehen automatisch zugehörige Daten mit – wenn Sie beispielsweise canvases_received anfordern, sind zusätzlich Journey-Zusammenfassungsdaten im Nutzerprofil erforderlich. Gültige Feldnamen und Anforderungen finden Sie in der Referenz zum Endpunkt /users/export/segment.
Wenn in einer ZIP-Datei aus einem API-Export Spalten fehlen, prüfen Sie, ob das Array fields_to_export in Ihrer Anfrage alle benötigten Felder enthält und ob Ihr Workspace über die erforderlichen Exportberechtigungen verfügt.
Wann Sie den Support kontaktieren sollten
Wenden Sie sich an den Braze-Support, wenn Sie den standardmäßigen Untersuchungsweg durchlaufen haben und weiterhin Hilfe benötigen. Geben Sie den Exporttyp, die Segment- oder Kampagnen-ID, den Zeitstempel (mit Zeitzone) sowie die genaue Fehlermeldung oder den HTTP-Statuscode an.