エクスポートに関するトラブルシューティング
このページを使用して、ダッシュボードおよびエクスポートAPIにおけるCSVとAPIのエクスポートに関する問題を診断します。エクスポートのワークフローと制限については、セグメントデータをCSVにエクスポートおよびエクスポートAPIを参照してください。
ここから開始：症状を確認する
表で発生している動作を見つけ、該当するセクションに移動して確認してください。
| 症状 | 参照先 |
|---|---|
CSVダウンロードリンクが AccessDenied、ExpiredToken、または「ファイルが存在しません」を返す |
デフォルトのエクスポート: CSVエラーまたはクラウドストレージ: CSVエラー |
APIエクスポートのダウンロードURLが 403 Forbidden を返す |
エクスポートしたセグメントのZIPをダウンロードできない |
| セグメントのエクスポートが失敗する、またはセグメントが大きすぎると表示される | セグメントが大きすぎる |
| セグメントエクスポートのメールが届かない | セグメントエクスポートのメールが届かない |
| CSVの行数がキャンペーン分析と一致しない | キャンペーンとキャンバスの分析の不一致 |
| 想定した列がエクスポートファイルにない | 列が欠落している |
クラウドストレージのエクスポートで AccessDenied または ExpiredToken が表示される |
クラウドストレージ接続時: APIエラー |
標準的な調査手順
すべてのエクスポートに関する問題で、このワークフローを使用します。ステップ1から始めてください。
- エクスポート先がデフォルトのBraze S3バケットか、接続済みのクラウドストレージパートナーかを確認します。リンクの有効期限と再試行の動作は、この2つで異なります。
- ダッシュボードのCSVエクスポートの場合は、ダウンロードリンクを開くときにBrazeにログインしていることを確認します。デフォルトバケットのリンクを利用するには、アクティブなダッシュボードセッションが必要です。
- エクスポートが完了してからどれくらい経過したかを確認します。メールで送信されるダッシュボードのダウンロードリンクは、デフォルトのBrazeバケットと接続済みのストレージパートナーのどちらを使用している場合でも、4時間後に有効期限が切れます。ストレージパートナーが接続されている場合、Brazeはお使いのバケットにもコピーを配信します。このコピーにはお客様のリテンションポリシーが適用されるため、メールのリンクの有効期限が切れた後も利用できる場合があります。
- 大規模なセグメントエクスポートの場合は、オーディエンスがダッシュボードCSVエクスポートの上限である500,000ユーザー未満であることを確認します。セグメントビルダーの推定値は、エクスポートパイプラインでの評価と異なる場合があります。
- APIエクスポートの場合は、処理が完了するまで待ってからダウンロードします。URLをすぐにリクエストするのではなく、
/users/export/segmentでcallback_endpointを使用するか、指数バックオフでポーリングしてください。 - それでも解決しない場合は、エクスポートの種類 (CSVまたはAPI)、セグメントIDまたはキャンペーンID、タイムスタンプ (タイムゾーンを含む)、正確なエラーメッセージを添えて、Brazeサポートにお問い合わせください。
ストレージ送信先
タブを使用して、デフォルトのBraze S3バケットにエクスポートするか、クラウドストレージパートナーにエクスポートするかを選択してください。クラウドストレージのガイダンスについては、クラウドストレージ接続済みタブを開き、CSVおよびAPIのセクションを確認してください。
デフォルトのエクスポート送信先としてマークされたストレージパートナーがない場合、Brazeは独自のAmazon S3バケットを使用してエクスポートファイルを保持します。この設定のファイルは一時的なもので、4時間後に期限切れになります。
CSVエクスポート
症状：ダッシュボードのCSVエクスポートメールが届いたが、ダウンロードリンクが失敗する、またはエクスポートが完了しない。
ダッシュボードからCSVをエクスポートすると、Brazeはログインしているユーザーにダウンロードリンクをメールで送信します。このリンクは、BrazeのS3バケットでホストされているZIPファイルを指しています。ZIP内には、エクスポートを構成する複数の小さなファイルが収められています。
リンクを使用するにはBrazeダッシュボードにログインしている必要があり、ファイルは4時間のみ利用可能です。その後、リンクは機能しなくなり、データは削除されます。非常に大規模なエクスポート（500,000ユーザー以上）で繰り返し失敗する場合、エクスポートが失敗する可能性があります。その場合は、エクスポートをより小さなグループやフィールドに分割するか、ストレージパートナーの設定を検討してください。
一般的なエラー
AccessDeniedエラーが表示された場合、ファイルの有効期限がすでに切れているか、準備が完了する前に開こうとした可能性があります。大きなレポートほど生成に時間がかかるため、数分待ってから再試行してください。ExpiredTokenエラーは、4時間の時間枠が経過したことを意味します。エクスポートを再実行して、新しいリンクを生成してください。Looks like the file doesn't exist anymoreというメッセージは、通常、メールは送信されたもののファイルのS3へのアップロードがまだ完了していない場合に表示されます。数分待つと、通常は解決します。- 特定のフィールド（
-、=、+、@など）の先頭にアポストロフィが追加されるのは想定された動作です。たとえば、-1943はCSVでは'-1943になります。Brazeは、スプレッドシートプログラムがデータを誤って解釈するのを防ぐためにこの処理を行っています。これは、/users/export/segmentエンドポイントから返されるものなどのJSONエクスポートには適用されません。
APIエクスポート
症状：エクスポートAPIの呼び出しは成功したが、ダウンロードURLが失敗する、または空のデータが返される。
クラウドストレージを使用せずにエクスポートAPIを通じてエクスポートを行うと、BrazeはファイルをそのS3バケットに書き込みます。メールは送信されません。代わりに、APIレスポンスに一時的なダウンロードURLが含まれます。エクスポートは、1行に1ユーザーを含む複数のJSONファイルが入ったZIPとして提供されます。
CSVエクスポートと同様に、APIからのリンクは4時間後に期限切れになります。リンクを早すぎるタイミングで開くと、ファイルの準備ができていないためにエラーが表示されることがあります。リクエストでcallback_endpointを指定すると、ファイルが利用可能になったときにBrazeから通知を受け取ることができます。
大規模なAPIエクスポートもタイムアウトすることがあります。その場合は、より小さなリクエストに分割するか、ストレージパートナーを接続してボリュームに対応してください。
一般的なエラー
AccessDeniedまたはExpiredTokenは、通常、リンクの期限が切れたか、まだ準備ができていないことを意味します。エクスポートを再度実行するか、もう少し待ってください。
ストレージパートナー（Amazon S3、Google Cloud Storage、Azure Blobなど）を接続し、ダッシュボードのテクノロジーパートナーページからデフォルトのエクスポート送信先としてマークすると、Brazeはエクスポートをバケットに直接書き込みます。この設定は、通常、大規模なエクスポートに対してより信頼性が高くなります。
CSVエクスポート
症状：メールで送信されたCSVリンクが失敗するが、接続されたバケットにファイルが表示される（または表示されない）。
CSVエクスポートでは、Brazeがダウンロードリンクをメールで送信します。このリンクは、短い時間枠（通常は約4時間）後に期限切れになります。ストレージパートナーが接続され、デフォルトのエクスポート送信先としてマークされている場合、Brazeは接続されたバケットにもエクスポートのコピーを配信します。このコピーはお客様自身のインフラに保存され、有効期限とリテンションはお客様のストレージポリシーに従います。
クラウドストレージでは、CSVエクスポートはZIPファイルにバンドルされます。ZIP内には複数の小さなCSVファイルが収められています。大規模なエクスポートは、多くの場合チャンクに分割されます（たとえば、それぞれ約5,000ユーザー）。チャンクサイズは異なる場合があります。ファイルが小さいからといって、データが欠落しているわけではありません。メールで送信されたリンクが失敗しても、ストレージ内のコピーが成功していれば、バケットからデータを直接取得できます。
一般的なエラー
AccessDeniedは、Brazeがバケットに書き込めなかったことを意味します。認証情報と権限がまだ有効であることを再確認してください。ExpiredTokenは、Brazeがバケットへのアクセスを失ったことを示します。Brazeダッシュボードで認証情報を更新してください。- 一部のファイルが予想よりも小さく見える場合がありますが、これは正常な動作です。エクスポートプロセスでは、安定性のために意図的にファイルを分割しています。
- 特定のフィールド（
-、=、+、@など）の先頭にアポストロフィが追加されるのは想定された動作です。たとえば、-1943はCSVでは'-1943になります。Brazeは、スプレッドシートプログラムがデータを誤って解釈するのを防ぐためにこの処理を行っています。これは、/users/export/segmentエンドポイントから返されるものなどのJSONエクスポートには適用されません。
APIエクスポート
症状：APIエクスポートがバケットに表示されない、またはファイルが不完全である。
ストレージパートナーが接続された状態でAPIを通じてデータをエクスポートすると、エクスポートファイルはバケットに書き込まれます。メールは送信されません。Brazeが返すダウンロードURLには引き続き時間制限がある場合がありますが、基盤となるオブジェクトはお客様のストレージに存在し、リテンション設定に従います。
ファイルは通常、エクスポートの実行中にバケットに表示されるため、ジョブ全体の完了を待たずに部分的な結果にアクセスできます。Brazeは完了したバッチをすべてまとめて最後に送信するのではなく、順次アップロードします。大規模なエクスポートは複数の圧縮ファイル（ZIPまたはGZIP）に分割され、それぞれに1行に1つのJSONオブジェクトが含まれます。これにより、大量のエクスポートに対してこの方法の信頼性が高くなります。
一般的なエラー
AccessDeniedは、Brazeがバケットに書き込めない場合、またはオブジェクトがその後削除された場合に発生します。権限を確認し、外部の何かがファイルを削除していないか確認してください。ExpiredTokenは、Brazeのバケットへのアクセス認証情報が古くなっていることを意味します。ダッシュボードで更新してください。- ファイルが見つからない、または予想よりも小さい場合は、まずBraze以外の何かがオブジェクトを削除していないか確認してください。ファイルサイズ自体が小さくなることは想定された動作です。
キャンペーンとキャンバスの分析
CSVエクスポートのユーザー数が送信メッセージ数またはユニーク受信者数と一致しない
症状：キャンペーンのCSVエクスポートに表示されるユーザー数が、分析ページの送信メッセージ数またはユニーク受信者数と異なります。
キャンペーンのCSVエクスポートに表示されるユーザー数が送信メッセージ数やユニーク受信者数と異なる理由は、次のとおりです。
再適格性がオンになっている
ユーザーがキャンペーンを複数回受信できる（または過去に受信できた）場合、キャンペーンの分析の数値とユーザーデータエクスポートの行数は一致しません。送信メッセージ数には、同じユーザーに複数回メッセージを送信した場合も含め、すべての送信がカウントされます。CSVエクスポートユーザーデータのダウンロードには、送信ごとに1行ではなく、ユニークユーザー（キャンペーンを受信したプロファイルごとに1行）が記載されます。たとえば、送信メッセージ数が12でCSVの行数が10の場合、12件の送信は10人の異なるユーザーに送られたことになります（一部のユーザーにはキャンペーンが複数回送信されています）。
キャンペーンまたはキャンバスの送信後にユーザーが削除または統合された
CSVエクスポートは、特定のキャンペーンまたはキャンバスを受信した既存ユーザーのスナップショットを提供します。ユーザーは削除または統合されることがあるため、CSVエクスポートの件数がユニーク受信者数より少なくなる場合があります。たとえば、1,000人のユーザーがキャンペーンを受信した場合、キャンペーンにはユニーク受信者数が1,000と表示され、同じ日のCSVエクスポートにも1,000人のユーザーが表示されます。1か月後にその1,000人のうち50人が削除された場合、CSVエクスポートには950人のユーザーが含まれますが、累積されたユニーク受信者数は1,000のままです。
ダッシュボードのセグメントエクスポートメール
セグメントが50万ユーザー未満に見えるのに、セグメントが大きすぎる、またはエクスポートが失敗する
症状: セグメントの推定値は問題なさそうに見えるのに、ダッシュボードのセグメントエクスポートが失敗するか、サイズエラーが表示されます。
ダッシュボードのセグメントサイズは推定値です。CSVエクスポートでは、この推定値を使用して50万ユーザーのエクスポート上限を適用します。また、エクスポートパイプラインでは、セグメントビルダーのUIとは異なる方法でサイズが評価される場合があります。このしきい値に近いセグメントでエクスポートが失敗する場合は、ランダムバケット番号を使用するか、オーディエンスをより小さなセグメントに分割してください。または、大規模なセグメントのエクスポートで説明されているように、/users/export/segmentエンドポイントを使用してください。
セグメントエクスポートのメールが届かないのはなぜですか?
症状: セグメントのCSVエクスポートを実行したのに、メールが届きません。
まず、スパムフォルダーにno-reply@alerts.braze.comからのメールがないか確認してください。メールが見つかった場合は、今後のエクスポートメッセージがフィルタリングされないように、このアドレスを安全な差出人リストに追加してください。
スパムフォルダーにもメールがない場合は、チームの他のメンバーがエクスポートを受信できるかどうかを確認してください。他のメンバーも受信できない場合は、エクスポートのサイズを検討してください。配信にかかる時間はエクスポートのサイズによって異なりますが、1時間経ってもメールが届かない場合は、サポートにお問い合わせください。
セグメントエクスポートAPIのダウンロード
BrazeのURLからエクスポートしたセグメントのZIPをダウンロードできない
症状:/users/export/segment のレスポンスURLからダウンロードする際に 403 Forbidden エラーが発生します。
/users/export/segment エンドポイントの使用時に 403 Forbidden エラーが発生する場合は、ファイルの準備がまだできていない可能性があります。大規模なエクスポートは処理に時間がかかることがあります。最大1時間待ってから、再度ダウンロードしてください。
自動スクリプトを使用してファイルを取得している場合も、URLへのリクエストが早すぎると 403 Forbidden エラーが返されることがあります。セグメントデータを定期的にエクスポートする場合は、独自のS3バケット連携を接続し、ファイルを独自の抽出・変換・読み込み (ETL) パイプラインに渡すことを検討してください。
エクスポートの完了には時間がかかるため、スクリプトからすぐにアクセスすると失敗することがよくあります。次のいずれかの方法を使用できます。
- 指数バックオフを使用してダウンロードURLをポーリングする
callback_endpointパラメーターを使用し、エクスポートの準備ができたときにスクリプトを実行するサービスを指定する
セグメントおよびユーザーエクスポートAPIのフィールド
セグメントのエクスポートファイルに想定した列が含まれていない
症状：APIまたはダッシュボードからのエクスポートに、想定していたフィールドが含まれていません。
セグメントからダッシュボードのCSVエクスポートユーザーデータを実行すると、固定された列セットが出力されます（セグメントデータをCSVにエクスポートを参照）。この方法には、fields_to_export 列やパラメーターは含まれません。
APIによるセグメントのエクスポートでは、リクエスト本文で fields_to_export を渡す必要があります。一部のフィールドは関連データを自動的に取得します。たとえば、canvases_received をリクエストする場合は、ユーザープロファイルのジャーニーサマリーデータも必要です。有効なフィールド名と要件については、/users/export/segment エンドポイントのリファレンスを参照してください。
APIエクスポートのZIPファイルに列が含まれていない場合は、リクエストの fields_to_export 配列に必要なフィールドがすべて含まれていること、およびワークスペースで必要なエクスポート権限が使用されていることを確認してください。
サポートに連絡するタイミング
標準の調査手順を完了しても問題が解決しない場合は、Braze サポートにお問い合わせください。その際は、エクスポートの種類、セグメントまたはキャンペーンのID、タイムスタンプ (タイムゾーンを含む)、正確なエラーメッセージまたはHTTPステータスコードをお知らせください。