내보내기 문제 해결
이 페이지는 CSV 및 API 워크플로우 모두에서 발생하는 내보내기 관련 일반적인 문제 해결 시나리오를 다룹니다.
탭을 사용하여 기본 Braze S3 버킷으로 내보낼지, 아니면 클라우드 스토리지 파트너로 내보낼지 선택하세요.
기본 내보내기 대상으로 지정된 스토리지 파트너가 없는 경우, Braze는 자체 Amazon S3 버킷을 사용하여 내보내기 파일을 보관합니다. 이 설정의 파일은 임시 파일이며 4시간 후에 만료됩니다.
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 내보내기
클라우드 스토리지 없이 Export API를 통해 내보낼 경우, Braze는 파일을 자체 S3 버킷에 기록합니다. 이메일은 발송되지 않으며, 대신 API 응답에 임시 다운로드 URL이 포함됩니다. 내보내기 파일은 ZIP 형식으로 제공되며, 각 ZIP 파일에는 여러 JSON 파일이 포함되어 있고, 각 JSON 파일에는 한 줄에 한 명의 사용자가 기록됩니다.
CSV 내보내기와 마찬가지로 API 링크도 4시간 후에 만료됩니다. 링크를 너무 일찍 클릭하면 파일이 아직 준비되지 않아 오류가 발생할 수 있습니다. 파일이 준비되었을 때 Braze에서 알림을 받으려면 요청에 callback_endpoint를 제공할 수 있습니다.
대규모 API 내보내기도 시간 초과될 수 있습니다. 이 경우 더 작은 요청을 시도하거나 스토리지 파트너를 연결하여 대용량을 처리하세요.
일반적인 오류
AccessDenied또는ExpiredToken은 일반적으로 링크가 만료되었거나 아직 준비되지 않았음을 의미합니다. 내보내기를 다시 실행하거나 조금 더 기다려 보세요.
대시보드의 기술 파트너 페이지에서 스토리지 파트너(예: Amazon S3, Google Cloud Storage 또는 Azure Blob)를 연결하고 이를 기본 내보내기 대상으로 설정하면, Braze가 내보내기 데이터를 해당 버킷에 직접 기록합니다. 이 설정은 일반적으로 대용량 내보내기에 더 안정적입니다.
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를 통해 데이터를 내보내면, 내보내기 파일은 버킷에 기록됩니다. 이메일은 발송되지 않습니다. 기본 오브젝트는 스토리지에 존재하며 보존 설정을 따르지만, Braze가 반환하는 다운로드 URL은 여전히 시간 제한이 있을 수 있습니다. 각 ZIP 파일에는 JSON 오브젝트가 포함되어 있으며, 각 오브젝트는 한 줄에 하나씩 배치됩니다. 대용량 내보내기는 단일 ZIP 파일 대신 여러 ZIP 파일로 분할될 수 있으며, 이는 일반적으로 대용량 내보내기에 더 안정적인 방법입니다.
일반적인 오류
AccessDenied는 Braze가 버킷에 쓰기 작업을 수행할 수 없거나 오브젝트가 이후에 삭제된 경우 발생합니다. 권한을 확인하고 외부에서 파일을 삭제하는 요소가 없는지 확인하세요.ExpiredToken은 Braze의 버킷 접근 자격 증명이 만료되었음을 의미합니다. 대시보드에서 자격 증명을 새로고침하세요.- 파일이 누락되었거나 예상보다 작은 경우, 먼저 Braze 외부에서 오브젝트를 삭제하는 요소가 없는지 확인하세요. 파일 크기가 작은 것 자체는 정상적인 동작입니다.
Campaign 및 Canvas 분석
CSV 내보내기의 사용자 수가 발송된 메시지 또는 _고유 수신자_와 일치하지 않는 경우
Campaign의 CSV 내보내기에서 발송된 메시지 및 _고유 수신자_와 다른 사용자 수가 표시될 수 있는 이유는 다음과 같습니다.
재자격이 활성화된 경우
사용자가 Campaign을 두 번 이상 수신할 수 있는 경우(또는 과거에 가능했던 경우), Campaign 분석 수치와 사용자 데이터 내보내기의 행 수가 일치하지 않습니다. _발송된 메시지_는 동일한 사용자에게 두 번 이상 메시지를 보낸 경우를 포함하여 모든 발송을 집계합니다. CSV 내보내기 사용자 데이터 다운로드는 고유 사용자를 나열합니다. 즉, Campaign을 수신한 프로필당 한 행이며, 발송당 한 행이 아닙니다. 예를 들어, _발송된 메시지_가 12이고 CSV에 10개의 행이 있다면, 12건의 발송이 10명의 고유 사용자에게 전달된 것입니다(일부 사용자가 Campaign을 두 번 이상 수신한 것입니다).
Campaign 또는 Canvas 발송 이후 사용자가 삭제되거나 병합된 경우
CSV 내보내기는 특정 Campaign 또는 Canvas를 수신한 기존 사용자의 스냅샷을 제공합니다. 사용자가 삭제되거나 병합될 수 있으므로, CSV 내보내기 수가 고유 수신자 수보다 적을 수 있습니다. 예를 들어, 1,000명의 사용자가 Campaign을 수신하면 Campaign에는 1,000명의 고유 수신자가 표시되고, 같은 날 CSV 내보내기에도 1,000명의 사용자가 표시됩니다. 한 달 후 해당 1,000명 중 50명이 삭제되면, CSV 내보내기에는 950명의 사용자가 포함되지만 누적된 고유 수신자 수는 여전히 1,000명입니다.
대시보드 Segment 내보내기 이메일
Segment 내보내기 이메일을 받지 못하는 이유
먼저 스팸 폴더에서 [email protected]으로부터 온 이메일을 확인하세요. 해당 이메일이 스팸 폴더에 있다면, 향후 내보내기 메시지가 필터링되지 않도록 해당 주소를 안전한 발신자 목록에 추가하세요.
이메일이 스팸 폴더에도 없다면, 팀의 다른 구성원이 내보내기를 수신할 수 있는지 확인하세요. 다른 구성원도 수신할 수 없다면, 내보내기 크기를 고려해 보세요. 전달 시간은 내보내기 크기에 따라 달라지지만, 1시간이 지나도 이메일이 도착하지 않으면 고객지원에 문의하세요.
Segment 내보내기 API 다운로드
Braze URL에서 내보낸 Segment ZIP 파일을 다운로드할 수 없는 경우
/users/export/segment 엔드포인트를 사용할 때 403 Forbidden 오류가 발생하면, 파일이 아직 준비되지 않았을 수 있습니다. 대규모 내보내기는 처리하는 데 시간이 걸릴 수 있습니다. 다시 다운로드하기 전에 최대 1시간까지 기다려 보세요.
자동화된 스크립트를 사용하여 파일을 가져오는 경우에도, URL을 너무 빨리 요청하면 403 Forbidden 오류가 발생할 수 있습니다. Segment 데이터를 정기적으로 내보내는 경우, 자체 S3 버킷 통합을 연결하고 파일을 자체 ETL 파이프라인으로 전달하는 것을 고려해 보세요.
내보내기는 완료되기까지 시간이 걸리므로, 스크립트에서 즉시 접근하면 실패하는 경우가 많습니다. 다음과 같은 방법을 사용할 수 있습니다.
- 지수 백오프를 적용하여 다운로드 URL을 폴링하거나,
callback_endpoint파라미터를 사용하여 내보내기가 준비되었을 때 스크립트를 실행하는 서비스를 지정할 수 있습니다.