Solução de problemas de exportação
Use esta página para diagnosticar problemas de exportação CSV e API no dashboard e nas APIs de exportação. Para fluxos de trabalho e limites de exportação, consulte Exportar dados de Segment para CSV e APIs de exportação.
Comece aqui: identifique seu sintoma
Encontre o comportamento que você está observando na tabela e vá até a seção correspondente para verificações direcionadas.
| Sintoma | Ir para |
|---|---|
O link de download do CSV retorna AccessDenied, ExpiredToken ou “file doesn’t exist” |
Exportação padrão: erros de CSV ou Armazenamento em nuvem: erros de CSV |
A URL de download da exportação via API retorna 403 Forbidden |
Não é possível fazer download de um ZIP de Segment exportado |
| A exportação de Segment falha ou informa que o Segment é muito grande | O Segment é muito grande |
| Nenhum e-mail de exportação de Segment recebido | Nenhum e-mail de exportação de Segment |
| A contagem de linhas do CSV não corresponde à análise de dados da campanha | Divergência na análise de dados de Campaign e Canvas |
| Colunas esperadas ausentes no arquivo de exportação | Colunas ausentes |
A exportação para armazenamento em nuvem exibe AccessDenied ou ExpiredToken |
Armazenamento em nuvem conectado: erros de API |
Caminho de investigação padrão
Use este fluxo de trabalho para todo incidente de exportação. Comece na etapa 1.
- Confirme se você está exportando para o bucket S3 padrão da Braze ou para um parceiro de armazenamento em nuvem conectado. O comportamento de expiração de links e de novas tentativas difere entre os dois.
- Para exportações CSV do dashboard, confirme que você está conectado à Braze ao abrir o link de download. Links do bucket padrão exigem uma sessão ativa no dashboard.
- Verifique há quanto tempo a exportação foi concluída. Links de download enviados por e-mail pelo dashboard expiram após quatro horas, seja usando o bucket padrão da Braze ou um parceiro de armazenamento conectado. Quando um parceiro de armazenamento está conectado, a Braze também envia uma cópia para o seu bucket; essa cópia segue suas políticas de retenção e pode permanecer disponível após a expiração do link do e-mail.
- Para exportações grandes de Segments, confirme que o público está abaixo do limite de 500.000 usuários para exportação CSV do dashboard. As estimativas do criador de segmentos podem diferir da avaliação do pipeline de exportação.
- Para exportações via API, aguarde o processamento terminar antes de fazer o download. Use
callback_endpointem/users/export/segmentou faça polling com backoff exponencial em vez de solicitar a URL imediatamente. - Se você ainda estiver bloqueado, entre em contato com o suporte da Braze informando o tipo de exportação (CSV ou API), o ID do Segment ou da Campaign, o timestamp (com fuso horário) e a mensagem de erro exata.
Destinos de armazenamento
Use as guias para selecionar se você está exportando para o bucket S3 padrão da Braze ou para um parceiro de armazenamento em nuvem. Para orientações sobre armazenamento em nuvem, abra a guia Armazenamento em nuvem conectado e revise as seções de CSV e API.
Quando você não tem um parceiro de armazenamento marcado como seu destino de exportação padrão, a Braze usa seu próprio bucket Amazon S3 para armazenar seus arquivos de exportação. Os arquivos nessa configuração são temporários e expiram após quatro horas.
Exportações CSV
Sintoma: um e-mail de exportação CSV do dashboard chega, mas o link de download falha, ou a exportação nunca é concluída.
Quando você exporta um CSV do dashboard, a Braze envia um link de download por e-mail para o usuário logado. Esse link aponta para um arquivo ZIP hospedado no bucket S3 da Braze. Dentro do ZIP estão vários arquivos menores que juntos compõem sua exportação.
Você deve estar logado no dashboard da Braze para usar o link, e o arquivo fica disponível por apenas quatro horas. Depois disso, o link não funciona mais e os dados são excluídos. Se você encontrar falhas repetidas com exportações muito grandes (mais de 500.000 usuários), a exportação pode falhar. Nesse caso, tente dividir sua exportação em grupos ou campos menores, ou considere configurar um parceiro de armazenamento.
Erros comuns
- Se você vir um erro
AccessDenied, o arquivo pode já ter expirado ou você pode ter tentado abri-lo antes de estar pronto. Relatórios maiores demoram mais para serem gerados, então aguarde alguns minutos e tente novamente. - Um erro
ExpiredTokensignifica que o período de quatro horas passou. Reexecute a exportação para gerar um novo link. - A mensagem
Looks like the file doesn't exist anymoregeralmente aparece quando o e-mail é enviado, mas o arquivo ainda não terminou de ser enviado para o S3. Aguardar alguns minutos geralmente resolve o problema. - Apóstrofos adicionados no início de certos campos (como
-,=,+ou@) são esperados. Por exemplo,-1943se torna'-1943no CSV. A Braze faz isso para evitar que programas de planilhas interpretem os dados incorretamente. Isso não se aplica a exportações JSON, como as retornadas pelo endpoint/users/export/segment.
Exportações de API
Sintoma: uma chamada à API de exportação é bem-sucedida, mas a URL de download falha ou retorna dados vazios.
Quando você exporta através das APIs de exportação sem armazenamento em nuvem, a Braze grava os arquivos no seu bucket S3. Você não receberá um e-mail — em vez disso, a resposta da API inclui uma URL de download temporária. A exportação vem como um ZIP contendo vários arquivos JSON, cada um com um usuário por linha.
Assim como as exportações CSV, os links da API expiram após quatro horas. Se você abrir o link cedo demais, pode ver erros porque o arquivo ainda não está pronto. Você pode fornecer um callback_endpoint na sua solicitação se quiser que a Braze notifique você quando o arquivo estiver disponível.
Exportações grandes de API também podem atingir o tempo limite. Se isso acontecer, tente fazer solicitações menores ou conecte um parceiro de armazenamento para lidar com o volume.
Erros comuns
AccessDeniedouExpiredTokengeralmente significam que o link expirou ou ainda não estava pronto. Execute a exportação novamente ou espere um pouco mais.
Quando você conecta um parceiro de armazenamento (como Amazon S3, Google Cloud Storage ou Azure Blob) e o marca como seu destino de exportação padrão na página Parceiros de Tecnologia no dashboard, a Braze grava suas exportações diretamente no seu bucket. Essa configuração é geralmente mais confiável para exportações maiores.
Exportações CSV
Sintoma: o link de CSV enviado por e-mail falha, mas os arquivos aparecem (ou não aparecem) no seu bucket conectado.
Com exportações CSV, a Braze envia um link de download por e-mail. Esse link expira após um curto período (geralmente cerca de quatro horas). Quando você tem um parceiro de armazenamento conectado e marcado como seu destino de exportação padrão, a Braze também entrega uma cópia da exportação no seu bucket conectado. Essa cópia reside na sua própria infraestrutura, onde a expiração e a retenção seguem suas políticas de armazenamento.
No armazenamento em nuvem, as exportações CSV são agrupadas em um arquivo ZIP. Dentro do ZIP estão vários arquivos CSV menores. Exportações grandes são frequentemente divididas em partes (por exemplo, cerca de 5.000 usuários cada), e o tamanho das partes pode variar. Arquivos menores não indicam dados ausentes. Se o link enviado por e-mail falhar, mas a cópia no seu armazenamento for bem-sucedida, você sempre pode recuperar seus dados diretamente do seu bucket.
Erros comuns
AccessDeniedsignifica que a Braze não conseguiu gravar no seu bucket. Verifique se suas credenciais e permissões ainda são válidas.ExpiredTokenaparece se a Braze perdeu o acesso ao seu bucket. Atualize suas credenciais no dashboard da Braze.- Se alguns arquivos parecerem menores do que o esperado, isso é um comportamento normal. O processo de exportação divide intencionalmente os arquivos para garantir estabilidade.
- Apóstrofos adicionados no início de certos campos (como
-,=,+ou@) são esperados. Por exemplo,-1943se torna'-1943no CSV. A Braze faz isso para evitar que programas de planilhas interpretem os dados incorretamente. Isso não se aplica a exportações JSON, como as retornadas pelo endpoint/users/export/segment.
Exportações de API
Sintoma: as exportações via API não aparecem no seu bucket ou os arquivos estão incompletos.
Quando você exporta dados através das APIs com um parceiro de armazenamento conectado, os arquivos de exportação são gravados no seu bucket. Nenhum e-mail é enviado. Os objetos subjacentes ficam no seu armazenamento e seguem suas configurações de retenção, mesmo que as URLs de download retornadas pela Braze possam ainda ter limite de tempo.
Os arquivos geralmente aparecem no seu bucket conforme a exportação é executada, então você não precisa esperar o trabalho inteiro terminar para acessar resultados parciais. A Braze faz upload de cada lote concluído de forma incremental, em vez de reter tudo até o final. Exportações grandes são divididas em vários arquivos compactados (ZIP ou GZIP), cada um contendo objetos JSON, um por linha. Isso torna esse método mais confiável para exportações pesadas.
Erros comuns
AccessDeniedacontece quando a Braze não consegue gravar no seu bucket ou os objetos foram excluídos posteriormente. Verifique as permissões e confirme que nada externo está excluindo arquivos.ExpiredTokensignifica que as credenciais de acesso da Braze ao seu bucket estão desatualizadas. Atualize-as no dashboard.- Se arquivos estiverem ausentes ou menores do que o esperado, primeiro confirme que nada fora da Braze está excluindo objetos. Tamanhos de arquivo menores em si são esperados.
Análise de dados de Campaign e Canvas
O número de usuários na exportação CSV não corresponde a Mensagens enviadas ou Destinatários únicos
Sintoma: a exportação CSV de uma Campaign mostra uma contagem de usuários diferente de Mensagens enviadas ou Destinatários únicos na página de análise de dados.
A exportação CSV de uma Campaign pode mostrar um número de usuários diferente de Mensagens enviadas e Destinatários únicos pelos seguintes motivos:
A reelegibilidade está ativada
Se os usuários podem (ou puderam em algum momento) receber a Campaign mais de uma vez, os números de análise de dados da Campaign e o número de linhas na exportação de dados de usuários não coincidem. Mensagens enviadas contabiliza cada envio, inclusive quando o mesmo usuário recebe a mensagem mais de uma vez. O download Exportar dados de usuários em CSV lista usuários únicos — uma linha por perfil que recebeu a Campaign — e não uma linha por envio. Por exemplo, se Mensagens enviadas é 12 e o CSV tem 10 linhas, esses 12 envios foram para 10 usuários distintos (alguns usuários receberam a Campaign mais de uma vez).
Usuários foram excluídos ou mesclados após o envio da Campaign ou do Canvas
A exportação CSV fornece um retrato dos usuários existentes que receberam uma determinada Campaign ou Canvas. Como os usuários podem ser excluídos ou mesclados, a contagem da exportação CSV pode ser menor do que a contagem de destinatários únicos. Por exemplo, se 1.000 usuários recebem uma Campaign, a Campaign mostra 1.000 destinatários únicos e a exportação CSV no mesmo dia também mostra 1.000 usuários. Se um mês depois 50 desses 1.000 usuários forem excluídos, a exportação CSV conterá 950 usuários, enquanto a contagem incrementada de destinatários únicos ainda será 1.000.
E-mails de exportação de Segment pelo dashboard
O Segment é muito grande ou a exportação falha mesmo quando meu Segment parece ter menos de 500.000 usuários
Sintoma: a exportação de Segment pelo dashboard falha ou exibe um erro de tamanho, mesmo quando a estimativa do Segment parece aceitável.
O tamanho do Segment no dashboard é uma estimativa. A exportação CSV usa essa estimativa para aplicar o limite de exportação de 500.000 usuários; o pipeline de exportação também pode avaliar o tamanho de forma diferente da interface do criador de segmentos. Se as exportações falharem para um Segment próximo desse limite, use números de bucket aleatórios, divida o público em Segments menores ou use o endpoint /users/export/segment conforme descrito em Exportando Segments grandes.
Por que não estou recebendo e-mails de exportação de Segment?
Sintoma: uma exportação CSV de Segment foi acionada, mas nenhum e-mail chegou.
Primeiro, verifique a pasta de SPAM para um e-mail de [email protected]. Se o e-mail estiver lá, adicione esse endereço à sua lista de remetentes confiáveis para que futuras mensagens de exportação não sejam filtradas.
Se o e-mail não estiver na sua pasta de SPAM, verifique se outra pessoa da sua equipe consegue receber a exportação. Se ninguém conseguir, considere o tamanho da sua exportação. O tempo de entrega varia conforme o tamanho da exportação, mas se o e-mail não tiver chegado após uma hora, entre em contato com o suporte da Braze.
Downloads da API de exportação de Segment
Não é possível baixar um ZIP de Segment exportado a partir de uma URL da Braze
Sintoma: um erro 403 Forbidden ao fazer download a partir da URL de resposta de /users/export/segment.
Se você receber um erro 403 Forbidden ao usar o endpoint /users/export/segment, o arquivo pode ainda não estar pronto. Exportações grandes podem levar um tempo para serem processadas. Aguarde até uma hora antes de tentar o download novamente.
Se você usa um script automatizado para recuperar o arquivo, também pode receber um erro 403 Forbidden ao solicitar a URL cedo demais. Se você exporta dados de Segment regularmente, considere conectar sua própria integração de bucket S3 e direcionar os arquivos para seu próprio pipeline de extração, transformação e carregamento (ETL).
As exportações levam tempo para serem concluídas, então o acesso imediato a partir de um script geralmente falha. Você pode:
- Consultar a URL de download com backoff exponencial, ou
- Usar o parâmetro
callback_endpointe apontá-lo para um serviço que execute seu script quando a exportação estiver pronta.
Campos da API de exportação de Segments e usuários
Colunas esperadas estão ausentes de um arquivo de exportação de Segment
Sintoma: Uma exportação via API ou dashboard está sem campos que você esperava.
A opção CSV Export User Data do dashboard em um Segment usa um conjunto fixo de colunas (consulte Exportar dados de Segment para CSV). Ela não inclui uma coluna ou parâmetro fields_to_export.
Para exportações de Segment via API, você deve informar fields_to_export no corpo da requisição. Alguns campos carregam dados relacionados automaticamente — por exemplo, solicitar canvases_received também requer dados de resumo de jornada no perfil de usuário. Consulte a referência do endpoint /users/export/segment para nomes de campos válidos e requisitos.
Se houver colunas ausentes no ZIP de exportação da API, confirme se o array fields_to_export na sua requisição inclui todos os campos necessários e se o seu espaço de trabalho possui as permissões de exportação exigidas.
Quando entrar em contato com o suporte
Entre em contato com o suporte da Braze se você concluiu o caminho de investigação padrão e ainda precisa de ajuda. Inclua o tipo de exportação, o Segment ou o ID da Campaign, o registro de data e hora (com fuso horário) e a mensagem de erro exata ou o código de status HTTP.