エクスポートに関するトラブルシューティング
このページでは、ダッシュボードおよびエクスポートAPIにおけるCSVとAPIのエクスポートに関する問題を診断する方法を説明します。エクスポートのワークフローと制限については、セグメントデータをCSVにエクスポートおよびエクスポートAPIを参照してください。
まずはここから：症状を確認する
以下の表で発生している動作を見つけ、該当するセクションに移動して対象を絞ったチェックを行ってください。
| 症状 | 移動先 |
|---|---|
CSVダウンロードリンクがAccessDenied、ExpiredToken、または「file doesn’t exist」を返す |
デフォルトエクスポート：CSVエラーまたはクラウドストレージ：CSVエラー |
APIエクスポートのダウンロードURLが403 Forbiddenを返す |
エクスポートされたセグメントのZIPをダウンロードできない |
| セグメントエクスポートが失敗する、またはセグメントが大きすぎると表示される | セグメントが大きすぎる |
| セグメントエクスポートメールが届かない | セグメントエクスポートメールが届かない |
| CSVの行数がキャンペーン分析と一致しない | キャンペーンとキャンバスの分析の不一致 |
| エクスポートファイルに期待されるカラムがない | カラムの欠落 |
クラウドストレージエクスポートでAccessDeniedまたはExpiredTokenが表示される |
クラウドストレージ接続済み：APIエラー |
標準調査パス
すべてのエクスポートインシデントに対してこのワークフローを使用してください。ステップ1から開始します。
- デフォルトのBraze S3バケットにエクスポートしているのか、接続されたクラウドストレージパートナーにエクスポートしているのかを確認します。リンクの有効期限とリトライの動作は両者で異なります。
- ダッシュボードのCSVエクスポートの場合、ダウンロードリンクを開く際にBrazeにログインしていることを確認します。デフォルトバケットのリンクにはアクティブなダッシュボードセッションが必要です。
- エクスポートが完了してからどのくらい経過したかを確認します。メールで送信されるダッシュボードのダウンロードリンクは、デフォルトのBrazeバケットを使用している場合でも、接続されたストレージパートナーを使用している場合でも、4時間後に期限切れになります。ストレージパートナーが接続されている場合、Brazeはバケットにもコピーを配信します。そのコピーはお客様のリテンションポリシーに従い、メールリンクの期限切れ後も利用可能な場合があります。
- 大規模なセグメントエクスポートの場合、オーディエンスがダッシュボードのCSVエクスポート制限である500,000ユーザー以下であることを確認します。セグメントビルダーの推定値はエクスポートパイプラインの評価と異なる場合があります。
- APIエクスポートの場合、ダウンロードする前に処理が完了するまで待ちます。URLをすぐにリクエストするのではなく、
/users/export/segmentでcallback_endpointを使用するか、エクスポネンシャルバックオフでポーリングしてください。 - それでも問題が解決しない場合は、エクスポートの種類（CSVまたはAPI）、セグメントまたはキャンペーン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か月後にそのうち50人が削除された場合、CSVエクスポートには950人のユーザーが含まれますが、累積されたユニーク受信者数は引き続き1,000のままです。
ダッシュボードのセグメントエクスポートメール
セグメントが大きすぎる、または500,000ユーザー未満に見えるのにエクスポートが失敗する
症状：ダッシュボードのセグメントエクスポートが失敗する、またはセグメントの推定値が許容範囲内に見えるのにサイズエラーが表示される。
ダッシュボードのセグメントサイズは推定値です。CSVエクスポートはその推定値を使用して500,000ユーザーのエクスポート制限を適用します。エクスポートパイプラインは、セグメントビルダーのUIとは異なる方法でサイズを評価する場合もあります。そのしきい値付近のセグメントでエクスポートが失敗する場合は、ランダムバケット番号を使用するか、オーディエンスをより小さなセグメントに分割するか、大規模なセグメントのエクスポートに記載されている/users/export/segmentエンドポイントを使用してください。
セグメントエクスポートメールが届かないのはなぜですか？
症状：セグメントのCSVエクスポートをトリガーしたが、メールが届かない。
まず、[email protected]からのメールがスパムフォルダーにないか確認してください。メールがスパムフォルダーにある場合は、今後のエクスポートメッセージがフィルタリングされないよう、そのアドレスを安全な送信者リストに追加してください。
メールがスパムフォルダーにもない場合は、チームの他のメンバーがエクスポートを受信できるか確認してください。受信できない場合は、エクスポートのサイズを考慮してください。配信時間はエクスポートサイズによって異なりますが、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ステータスコードを添えてご連絡ください。