Carregar um arquivo CSV para uma origem

Permissões de usuário necessárias: "Sources admin" E "Edit messages".

Observação: este artigo demonstra como carregar dados de um arquivo CSV para uma fonte de dados existente. Para entender como primeiro criar uma origem de dados por meio do GUI, consulte aqui.

Principais etapas

Observação: se atualizar mensagens existentes em uma origem, alterar propriedades de mensagem (por exemplo, message text, send_at timestamp e "to" ou "from") que não sejam propriedades do usuário, farão com que as anotações de entidade em conjuntos de dados associados sejam perdidas. É altamente recomendável fixar a versão mais recente do modelo em conjuntos de dados associados antes de fazer isso.

Para carregar dados de um arquivo CSV para uma origem de dados, navegue até a página Fontes (através do console de administração, acessado pela roda dentada no canto superior direito da sua página) e localize a origem para a qual você gostaria de carregar os dados.

Clique no ícone de carregamento no canto superior direito do cartão da origem de dados (conforme mostrado abaixo).

Cartão de origem de dados

Em seguida, clique em "Selecionar arquivo" e escolha o arquivo CSV que deseja carregar.

O arquivo selecionado deve atender aos seguintes critérios:

• O arquivo precisa conter cabeçalhos na primeira linha e ser delimitado por vírgulas ou tabulações
• São necessários no mínimo três colunas: o conteúdo de texto da mensagem (a mensagem), um carimbo de data/hora e um ID exclusivo que identifique a mensagem
• Todos os campos de texto no seu arquivo CSV devem estar entre aspas duplas
• O arquivo deve ser codificado como UTF-8, UTF-16 ou UTF-32 (a plataforma detecta automaticamente qual)
• O arquivo CSV deve ter até 64 MiB. Se você tiver um arquivo maior, ainda poderá carregá-lo dividindo-o em vários arquivos, cada um com menos de 64 MiB

Página de carregamento de CSV — etapa 1

Se seu arquivo atender aos critérios acima, você pode configurar e carregar as mensagens na próxima etapa:

Página de carregamento de CSV — etapa 2

Selecione as colunas necessárias de cada uma das listas suspensas contendo os cabeçalhos de coluna detectados no arquivo CSV:

• Coluna de ID:
  • Deve ser uma coluna com um ID exclusivo que identifique a mensagem
  • Os IDs das mensagens podem conter apenas caracteres alfanuméricos ASCII (AZ az 0-9) e pontuação (exceto /)
  • Observação: se houver mensagens existentes na origem com o mesmo ID, elas serão atualizadas para corresponder ao conteúdo do novo arquivo
• Coluna de mensagem:
  • Esta é simplesmente a coluna que contém o texto da mensagem que você deseja analisar na plataforma
• Coluna de carimbo de data/hora:
  • Esta é uma coluna que contém a data e a hora em que a mensagem foi gravada
  • O formato do carimbo de data/hora é flexível e será inferido automaticamente pela plataforma

Se você tiver dados contendo linhas de assunto, threads ou participantes (normalmente vistos em casos ou threads de e-mail), você também pode carregar estas colunas adicionais dentro de seu arquivo CSV:

• Coluna de Assunto
  • Escolha qual coluna contém o Assunto da mensagem
• Coluna do Remetente
  • Escolha qual coluna contém o Remetente
• Coluna Para
  • Escolha qual coluna contém o(s) Destinatário(s). Vários destinatários devem ficar separados por ponto e vírgula.
• Coluna Cc
  • Escolha qual coluna contém o(s) Destinatário(s) Cc'd. Vários destinatários devem estar separados por ponto e vírgula
• Coluna de ID da Thread
  • Escolha a coluna que contém a mensagem ID do thread
  • Um ID da thread é o que conecta diferentes mensagens na mesma thread

Formato Remetente/Para/CC:

• As seguintes condições nos campos remetente/para/cc irão disparar erros:
  • Excede o número máximo de destinatários (máximo de 2.048 destinatários por thread)
  • Remetente ou destinatário excede o limite máximo de caracteres (máximo de 512 caracteres por destinatário)
  • Dois ou mais pontos e vírgulas são encontrados em uma linha (por exemplo, o seguinte está formatado incorretamente: [e-mail] ; [e-mail])
• Embora a plataforma remova qualquer espaço em branco antes ou depois de um destinatário, ela não fará nenhuma limpeza de dados adicional.
  • Formatos de exemplo em que você pode querer seus dados (não é uma lista exaustiva):
    • Exemplo 1 - Robô Bog <[e-mail]>; John Smith <[e-mail]>
    • Exemplo 2 - [e-mail] ;[e-mail]
    • Exemplo 3 - [e-mail] ; [e-mail]
• A plataforma delimitará os diferentes destinatários com pontos e vírgulas (;)
• Antes de carregar seus dados, verifique se os emails estão em um formato adequado
• Observe que, em um caso de uso típico com threads (por exemplo, e-mails), deve haver apenas um remetente em cada célula “remetente”

Formato do carimbo de data/hora:

• Se o formato de carimbo de data/hora escolhido for ambíguo em relação à ordem de dias/meses/anos (por exemplo, 01/02/03 10:10), é possível sugerir a interpretação correta:
  • 2 de janeiro de 2003 - Nenhum
  • 1º de fevereiro de 2003 - primeiro dia
  • 3 de fevereiro de 2001 — primeiro ano
  • 2 de março de 2001 - Primeiro dia + Ano primeiro
• Para evitar ambiguidade, é recomendável fornecer carimbos de data/hora no formato RFC 3339, se possível (por exemplo, 2020-01-31T12:34:56Z para UTC ou com fuso horário: 2020-08-031T11:20:60-08:00)

Em seguida, selecione as propriedades do usuário adicionais que você deseja carregar com as mensagens. As propriedades do usuário são metadados contextuais associados a cada mensagem que são filtráveis na plataforma. Esses também são potencialmente usados pelos modelos de aprendizado de máquina na plataforma. Há dois tipos, string ou número:

• Propriedades de usuário string são metadados categorizados (exemplos típicos incluem IDs, países, contrapartes, etc.)
• As propriedades numéricas do usuário são metadados numéricos (exemplos típicos incluem NPS, estatísticas de email, quantidades etc.)

Observação:

Se seu arquivo contiver uma pontuação de NPS como uma propriedade do usuário, ela deve ser incluída como uma propriedade numérica e chamada apenas de "NPS", para disparar os gráficos de NPS nativos a serem carregados na plataforma.

Depois de selecionar todas as propriedades do usuário, clique em 'Carregar '.

Em seguida, será solicitado que você inspecione as mensagens carregadas em um conjunto de dados que contém a origem em que você carregou os dados. Se a origem ainda não estiver associada a nenhum conjunto de dados, você pode criar um novo para verificar se o carregamento é conforme o esperado.

Observação:

Se você cometeu um erro ao selecionar as propriedades do usuário, pode carregar novamente o mesmo arquivo e a plataforma usará o ID da coluna como o identificador para substituir as mensagens e propriedades existentes (isso não afetará os rótulos aplicados às mensagens existentes).

Solução de problemas

Esperamos que o upload ocorra sem problemas, mas é possível que você encontre um problema durante o processo e veja uma mensagem de erro. Descrevemos abaixo alguns deles e por que ocorrem, para ajudar você a resolvê-los ou evitá-los.

Nas mensagens de erro abaixo, {something} mapeia informações contextuais sobre onde o erro ocorreu. Além disso, a maneira como nos referimos a uma posição no arquivo é padronizada como:

String	Expande para:
{position}	registro {row-number} na linha {line-number} coluna {column-number} (byte {byte-number})

O título da mensagem de erro é exibido com uma descrição, conforme mostrado abaixo:

Aqui estão algumas possíveis mensagens de erro que os usuários podem encontrar ao carregar arquivos CSV:

Tipo de Erro	Mensagem de Erro	Description
Colunas Sem Colunas Sem Coluna	O arquivo CSV só contém {number-columns} coluna(s), mas pelo menos três são necessárias (texto, carimbo de data/hora e id)	O CSV carregado não contém pelo menos três colunas ou a plataforma detectou incorretamente a codificação do arquivo.
Codificação Inválida	O arquivo contém caracteres inválidos (a codificação foi detectada como {detected-en encoding})	O arquivo não está codificado corretamente como UTF-8/UTF-16/UTF-32 (a plataforma detecta automaticamente o formato do arquivo)
Cabeçalho Inválido	string:ti:er' does not match'(^delimiter|id|message|timestamp |timestamp_default_utc_offset |timestamp_day_first|timestamp_year_first\\Z)|(^(?P<property_type>number|string):(?P<name>\\w(?:[\\w]{0,30}\\w)?)\\Z)'	Se um cabeçalho de coluna for um nome inválido para uma propriedade de usuário, a plataforma retornará a mensagem padrão para quando o esquema de uma solicitação for inválido. Verifique se o cabeçalho de cada coluna tem um formato válido para sua finalidade. O comprimento máximo do cabeçalho da coluna é de 32 caracteres alfanuméricos
Comprimentos de Linhas Desiguais	O CSV contém comprimentos de linha desiguais. A mensagem {position} tem {number} campos, mas o registro anterior tem {number} campos.	O CSV contém linhas com números diferentes de células ou que são inconsistentes com o número de cabeçalhos.
Formato do ID	ID da mensagem inválido para {record}. Os IDs podem consistir apenas em caracteres alfanuméricos e pontuação (exceto '/'). Valor da célula: {célula-valor}	Esse erro ocorre quando um campo Id consiste em caracteres inválidos, conforme descrito na mensagem de erro.
Tamanho do ID	O ID é muito longo para a mensagem {record}. Tem {number} bytes, esperados no máximo 1024	Esse erro ocorre quando um campo de ID é maior do que o comprimento máximo permitido (1024 caracteres)
Formato do carimbo de data/hora	Carimbo de data/hora formatado incorretamente na mensagem {position}: {timestamp-error-message}. Valor da célula: {célula-valor}	Esse erro ocorre quando não foi possível analisar um campo de carimbo de data/hora.
Tamanho da Mensagem	A mensagem é muito longa para a mensagem {position}. Tem {number} bytes, esperados no máximo 65536	Esse erro ocorre quando um campo de mensagem é maior do que o comprimento máximo permitido (65536 caracteres).
Formato da Propriedade Numérica	Número formatado incorretamente na mensagem {position}: {number-error-message}. Valor da célula: {célula-valor}	Esse erro ocorre quando um campo numérico de propriedade do usuário não pode ser analisado. A plataforma deve permitir qualquer formato que possa ser decodificado como um número.
Tamanho da Propriedade	A propriedade é muito longa para a mensagem {position}. Tem {number} bytes, esperados no máximo 4096	Esse erro ocorre quando um campo de propriedade do usuário é maior do que o comprimento máximo permitido (4096 caracteres).
Erro Desconhecido	Erro de CSV desconhecido: {underlying-error-message}	A lista acima não é completamente exaustiva - se ocorrer um erro desconhecido, tente novamente o carregamento.