Solução de problemas de exportação
Use esta página para diagnosticar problemas de exportação de 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 na tabela o comportamento que você está vendo e, em seguida, acesse a seção correspondente para fazer verificações específicas.
| Sintoma | Acessar |
|---|---|
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 |
O URL de download da exportação via API retorna 403 Forbidden |
Não é possível baixar um ZIP de Segment exportado |
| A exportação do Segment falha ou informa que o Segment é grande demais | Segment grande demais |
| 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 Campaign | Divergência na análise de dados de Campaign e Canvas |
| Colunas esperadas estão ausentes do arquivo de exportação | Colunas ausentes |
A exportação para armazenamento em nuvem mostra AccessDenied ou ExpiredToken |
Armazenamento em nuvem conectado: erros de API |
Jornada de investigação padrão
Use este fluxo de trabalho em todos os incidentes de exportação. Comece pela etapa 1.
- Confirme se você está exportando para o bucket S3 padrão da Braze ou para um parceiro de armazenamento em nuvem conectado. A expiração dos links e o comportamento de novas tentativas são diferentes entre os dois.
- Para exportações CSV pelo dashboard, confirme que você está conectado à Braze ao abrir o link de download. Os links do bucket padrão exigem uma sessão ativa no dashboard.
- Verifique há quanto tempo a exportação foi concluída. Os links de download do dashboard enviados por e-mail expiram após quatro horas, seja no bucket padrão da Braze ou em um parceiro de armazenamento conectado. Quando há um parceiro de armazenamento conectado, a Braze também entrega uma cópia no seu bucket. Essa cópia segue suas políticas de retenção e pode continuar disponível depois que o link do e-mail expirar.
- Para exportações grandes de Segments, confirme que o público está abaixo do limite de 500.000 usuários para exportação CSV pelo dashboard. As estimativas do criador de segmentos podem ser diferentes da avaliação feita pelo pipeline de exportação.
- Para exportações via API, aguarde a conclusão do processamento antes de fazer o download. Use
callback_endpointno/users/export/segmentou faça consultas periódicas com backoff exponencial em vez de solicitar a URL imediatamente. - Se ainda não conseguir resolver, entre em contato com o suporte da Braze informando o tipo de exportação (CSV ou API), o ID do segmento ou da campanha, o registro de data e hora (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 elegibilidade está ativada
Se os usuários podem (ou puderam em algum momento) receber a Campaign mais de uma vez, os números da análise de dados da Campaign e o número de linhas na exportação de dados de usuários não vão bater. Mensagens enviadas conta todos os envios, inclusive quando o mesmo usuário recebe a mensagem mais de uma vez. Já 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 for 12 e o CSV tiver 10 linhas, esses 12 envios foram para 10 usuários distintos. Ou seja, alguns usuários receberam a Campaign mais de uma vez.
Usuários foram excluídos ou mesclados desde o envio da Campaign ou do Canvas
A exportação CSV mostra 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 que a contagem de destinatários únicos. Por exemplo, se 1.000 usuários recebem uma Campaign, ela mostra 1.000 destinatários únicos, e a exportação CSV feita 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 terá 950 usuários, enquanto a contagem acumulada de destinatários únicos continua em 1.000.
E-mails de exportação de segmentos do dashboard
O Segment é grande demais ou a exportação falha quando meu Segment parece ter menos de 500.000 usuários
Sintoma: A exportação de segmentos do dashboard falha ou mostra um erro de tamanho, mesmo que a estimativa do Segment pareça aceitável.
O tamanho do Segment no dashboard é uma estimativa. A exportação para 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 ou divida o público em segmentos menores. Outra opção é usar o endpoint /users/export/segment, conforme descrito em Exportação de segmentos grandes.
Por que não estou recebendo os e-mails de exportação de segmentos?
Sintoma: Uma exportação de Segment para CSV foi disparada, mas nenhum e-mail chegou.
Primeiro, verifique sua pasta de SPAM para ver se há um e-mail de [email protected]. Se o e-mail estiver lá, adicione esse endereço à sua lista de remetentes confiáveis para que as próximas mensagens de exportação não sejam filtradas.
Se o e-mail não estiver na pasta de SPAM, verifique se outra pessoa da sua equipe consegue receber a exportação. Se ela também não conseguir, considere o tamanho da sua exportação. O tempo de entrega varia de acordo com o tamanho da exportação, mas se o e-mail não chegar depois de uma hora, entre em contato com o suporte.
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 baixar a partir da URL de resposta do /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 algum tempo para serem processadas. Aguarde até uma hora antes de tentar baixar 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 com frequência, considere conectar sua própria integração de bucket S3 e enviar 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 costuma falhar. Você pode:
- Consultar a URL de download periodicamente 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 de API para exportação de Segment e de usuários
Colunas esperadas estão faltando em um arquivo de exportação de Segment
Sintoma: uma exportação feita pela API ou pelo dashboard não traz campos que você esperava.
No dashboard, a opção CSV Export User Data de 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.
Nas exportações de Segment pela API, você precisa informar fields_to_export no corpo da solicitação. Alguns campos trazem dados relacionados automaticamente. Por exemplo, ao solicitar canvases_received, também é necessário ter dados de resumo da jornada no perfil de usuário. Consulte a referência do endpoint /users/export/segment para ver os nomes de campos válidos e os requisitos.
Se houver colunas faltando no ZIP de uma exportação pela API, confirme se o array fields_to_export da sua solicitação inclui todos os campos de que você precisa e se o seu espaço de trabalho tem as permissões de exportação necessárias.
Quando entrar em contato com o suporte
Entre em contato com o suporte da Braze se você já seguiu o processo padrão de investigação e ainda precisa de ajuda. Informe o tipo de exportação, o ID do Segment ou da Campaign, o registro de data e hora (com o fuso horário) e a mensagem de erro exata ou o código de status HTTP.