Ingestão em massa de objetos personalizados

Você pode importar registros de objetos personalizados em massa usando dois métodos: SFTP e Importação do Data Warehouse (DWH).  Os dois métodos permitem carregar registros brutos em uma fonte de dados, que é conectada a um tipo de objeto personalizado na IU da Klaviyo.

Este artigo aborda como cada método funciona, como formatar seus arquivos e o que esperar durante e após a importação.

Antes de começar

Familiarize-se com objetos personalizados. Consulte a visão geral do Guia de introdução a objetos personalizados e da API de Objetos Personalizados.

Há algumas partes do recurso de objetos personalizados a serem lembradas ao configurar a ingestão em massa/sincronização:

• Uma Fonte de dados de objetos personalizados é um esquema flexível, definido pelo usuário. Um Registro de fonte de dados representa um registro em uma fonte de dados. Observe que eles persistem na Klaviyo, permitindo que você crie diferentes esquemas/objetos no futuro a partir de registros de fonte de dados que você carregou no passado.
• Um objeto personalizado consiste em um esquema de objeto e um esquema de mapeamento entre uma Fonte de Dados e o objeto.
• Objetos personalizados diferentes podem ser mapeados para uma única fonte de dados, usando mapeamentos de campo iguais ou diferentes.

Para importar objetos personalizados do SFTP, você precisará da ID da fonte de dados onde deseja criar registros de fonte de dados. Você pode criar isso via API ou na UI da web ao criar um novo objeto personalizado. Isso também pode ser criado automaticamente durante o primeiro ciclo de sincronização de uma sincronização do data warehouse para objetos personalizados.

Método 1: Importação SFTP

Fonte de dados

Identifique o ID da fonte de dados de objetos personalizados que você quer segmentar com a importação e crie um arquivo config.json com o ID, assim:

{
  "data_source_id": "01KTMWCZ8ZMNZS0HG5HQNX0H6E"
}

Estrutura do diretório

Na raiz do SFTP, crie uma nova pasta em /imports/custom_objects/. O nome da pasta não afeta como os dados são processados.

Copie seu arquivo config.json, que contém data_source_id, para a nova pasta.

Coloque os arquivos de dados que você quer fazer upload na nova pasta. *.csv e *.jsonl arquivos serão processados.

{company_id}/
  imports/
    profiles/           
    events/             
    custom_objects/     
      pets/            ← User-defined folder
     config.json        ← Configuration file with data_source_id
     pet_records.csv    ← CSV file to process
     pet_records.jsonl    ← JSONL file to process

Arquivos colocados diretamente em custom_objects/ sem um subdiretório serão rejeitados. Toda importação de objeto personalizado deve estar dentro de uma subpasta nomeada.

Formatos de arquivo compatíveis

JSONL é altamente recomendado quando seus registros contêm dados aninhados ou matrizes.

Formatação CSV

• A primeira linha deve ser uma linha de cabeçalho. Os nomes das colunas devem corresponder à definição da fonte de dados.
• O JSON aninhado em uma célula de CSV deve estar entre aspas duplas, e as aspas internas devem ser escapadas com caracteres de aspas duplas (por exemplo, "").
• As células vazias são tratadas como campos ausentes, não como valores nulos.

Exemplo de CSV:

subscription_id,product_name,status,start_date
sub_001,Premium Plan,active,2025-01-15
sub_002,Basic Plan,inactive,2024-06-01

Formatação JSONL

• Cada linha deve ser um objeto JSON válido ({...}).
• As linhas que não são objetos (por exemplo, matrizes ou primitivas) são ignoradas e contabilizadas como erros.
• Linhas vazias são ignoradas silenciosamente.
• Objetos e matrizes aninhados são transmitidos e armazenados por completo.

Exemplo JSONL:

{"subscription_id": "sub_001", "product_name": "Premium Plan", "status": "active", "start_date": "2025-01-15"}
{"subscription_id": "sub_002", "product_name": "Basic Plan", "status": "inactive", "start_date": "2024-06-01", "metadata": {"source": "shopify", "tags": ["vip", "annual"]}}

O que acontece durante a importação

1. O Klaviyo detecta o caminho do subdiretório e determina que o tipo de recurso é custom_objects.
2. A Klaviyo verifica se existe na conta uma fonte de dados de objetos personalizados com o data_source_id no config.json.
3. Os registros são extraídos e processados em lotes de até 500 registros por lote.
4. Cada lote é gravado na fonte de dados por meio do mesmo pipeline usado pela API em massa.
5. Você recebe uma notificação de conclusão (por e-mail ou no produto) quando a tarefa é concluída.

Manipulação de erros

• Linhas inválidas (CSV malformado ou linhas JSONL não analisáveis) são ignoradas. O trabalho continua processando o restante do arquivo.
• A notificação de conclusão inclui uma contagem de linhas ignoradas e um resumo de todos os erros encontrados.
• Se a pasta não tiver .config.json ou se o ID da fonte de dados na configuração for inválido, o arquivo não será processado. Para tentar novamente, você precisa enviar o arquivo de novo com um nome diferente. Arquivos antigos serão removidos após 30 dias.

Método 2: Importação do data warehouse

Visão geral

Se você usar Snowflake, Databricks ou BigQuery, poderá configurar uma sincronização do data warehouse para importar diretamente objetos personalizados. O fluxo de configuração é o mesmo que para perfis e eventos — conecte seu warehouse, selecione uma tabela ou visualização e escolha Objeto personalizado como o tipo de recurso.

Configurando a sincronização

1. Acesse Integrações > Data Warehouse e abra sua conexão do warehouse.
2. Crie uma nova sincronização de importação ou edite uma existente.
3. Em Tipo de recurso, selecione Objeto personalizado.
4. Selecione a Fonte de Dados para a qual deseja rotear os registros.
   1. Para uma fonte de dados existente: os nomes das colunas do data warehouse devem corresponder à definição da fonte de dados.
   2. Se ainda não existir uma fonte de dados, uma será criada automaticamente na primeira execução de sincronização e nomeada "Sincronização de dados: {sync_name}". Você pode modificar esse nome como desejar. Você não poderá configurar novos objetos até que pelo menos um registro tenha sido importado (para estabelecer o esquema da fonte de dados).
5. Salve e ative a sincronização.

Comportamento de sincronização

• Os registros são processados em lotes de até 500 por chamada.
• As linhas com falha são gravadas em um arquivo de erro para download com detalhes no nível da linha (por exemplo, valores com formato incorreto, identificadores ausentes).
• Cada execução de sincronização gera uma entrada de registro visível na aba Logs da sincronização, com detalhes sobre extração, transformação, andamento da carga e quaisquer erros.

Após a importação: se estiver usando uma fonte de dados existente

Se um ou mais objetos personalizados já estiverem configurados com essa fonte de dados, eles serão criados a partir dos novos registros da fonte de dados da mesma forma que seriam se você adicionasse registros da fonte de dados via API.

Se nenhum objeto personalizado ainda usar essa fonte de dados, use o assistente para Novo objeto para criar um novo objeto e selecione a fonte de dados usada em sua sincronização. Certifique-se de que pelo menos um registro tenha sido importado para que o esquema da fonte de dados seja estabelecido.