Como usar o servidor SFTP genérico

O servidor SFTP de feed genérico permite o upload de vários tipos de feed para um único servidor SFTP por ambiente. Este guia explica como usar o servidor SFTP genérico e fornece links para o guia adequado do feed que você planeja usar.

Consulte a seção Exportar feeds (de ponta a ponta) ou Feeds (iniciante) da documentação.

O servidor SFTP genérico depende de dois uploads separados:

  1. Arquivo descritor:descreve o tipo de feed que você vai enviar.
  2. Arquivos de feed: o conteúdo do feed real

Como estruturar o campo de descritores

O arquivo descritor é enviado para informar ao nosso sistema o tipo de feed que você está enviando. Isso nos permite validar e processar o feed corretamente. O arquivo descritor precisa ser enviado antes do conteúdo do feed e seguir estes requisitos de nomenclatura:

  • Você precisa usar a extensão de arquivo .filesetdesc.json para o arquivo de descritor.
  • Cada nome de arquivo de descritor precisa ser exclusivo e não pode ser reutilizado em vários envios. Recomendamos incluir o carimbo de data/hora de geração e o nome do feed no nome de arquivo.
    • Exemplo: offers_1524606581.filesetdesc.json
  • Cada arquivo de descritor precisa listar todos os arquivos de dados no feed mais recente para o nome de feed relevante.
message FilesetDescriptor {
  // The timestamp at which this feed was generated, in Unix time format
  // (seconds since the epoch). (required)
  int64 generation_timestamp = 1;

  // Identifies the name of this feed. (required)
  string name = 2;

  // Paths (relative to the dropbox root) specifying data files included in this
  // feed. (required)
  repeated string data_file = 3;
}

Os valores possíveis para o campo name incluem:

Confira abaixo um exemplo de arquivo descritor JSON para um feed de ofertas com dois fragmentos:

{
  "generation_timestamp": 1524606581,
  "name": "promote.offer",
  "data_file": [
    "offers_1524606581_1.json",
    "offers_1524606581_2.json"
  ]
}

Estruturar o conteúdo do feed

Depois de fazer upload do arquivo de descritor, envie todos os arquivos de feed para o tipo de dados de feed correspondente ao arquivo de configuração de feed nomeado pelo arquivo de descritor. Os nomes dos arquivos e os locais dos caminhos (relativos no servidor SFTP) precisam corresponder exatamente ao que foi incluído no campo data_file. Se algum arquivo estiver faltando, tiver um nome incorreto ou tiver sido enviado para um local diferente, todo o feed não será processado.

O conteúdo desses arquivos de dados de feed precisa estar em conformidade com a especificação relevante do feed especificado no arquivo de descritor.

Cada nome de arquivo de feed precisa ser exclusivo e não pode ser reutilizado em vários envios. Recomendamos incluir o carimbo de data/hora de geração e o número do fragmento (ID incremental) no nome de arquivo.

  • Exemplo: offers_1524606581_1.json

Tamanhos de arquivo do feed e frequência de upload

  • O arquivo do feed precisa ter até 200 MB (após a compactação).
  • Cada arquivo de dados descompactado precisa ter menos de 2 GB.
  • A maioria das integrações só precisa usar um único fragmento. Use o menor número possível de fragmentos. Há um máximo de 1.000 fragmentos por feed.
  • Registros individuais enviados em um fragmento não precisam ser enviados no mesmo número de fragmento em feeds futuros.
  • Para melhorar o desempenho, divida os dados uniformemente entre os arquivos fragmentos para deixá-los semelhantes.
  • Se necessário, use o gzip para compactar feeds. No entanto, faça isso para cada fragmento de feed individual.

Solução de problemas e depuração

Depois de fazer upload dos arquivos (descritor e feed), acesse o Ingestion Viewer (documentação) no Portal de parceiros (acesse Ingestão > Histórico) para acompanhar o progresso da ingestão do feed.

Procure o name inserido no arquivo de descritor na coluna "Nome do feed" para encontrar seu feed.

Depois que o feed for ingerido (status Success ou Fail), clique na linha dele para conferir os detalhes dos erros e avisos.