Configuração da formatação de arquivo
O Destination SDK suporta um conjunto flexível de recursos que você pode configurar de acordo com suas necessidades de integração. Entre esses recursos está o suporte para a formatação de arquivo CSV.
Ao criar destinos baseados em arquivo por meio do Destination SDK, é possível definir como os arquivos CSV exportados devem ser formatados. É possível personalizar muitas opções de formatação, como, mas não limitado a:
- Se o arquivo CSV deve incluir um cabeçalho;
- Qual caractere usar para citar valores;
- Como os valores vazios devem ser exibidos.
Dependendo da configuração de destino, os usuários verão determinadas opções na interface do usuário ao se conectarem a um destino baseado em arquivo. Você pode ver a aparência dessas opções na documentação opções de formatação de arquivo para destinos baseados em arquivo.
As configurações de formatação de arquivo fazem parte da configuração do servidor de destino para destinos baseados em arquivo.
Para entender onde esse componente se encaixa em uma integração criada com o Destination SDK, consulte o diagrama na documentação de opções de configuração ou consulte o guia sobre como usar o Destination SDK para configurar um destino baseado em arquivo.
Você pode configurar as opções de formatação de arquivo por meio do ponto de extremidade /authoring/destination-servers. Consulte as seguintes páginas de referência de API para obter exemplos detalhados de chamadas de API, onde é possível configurar os componentes mostrados nesta página.
Esta página descreve todas as configurações de formatação de arquivo com suporte para arquivos CSV exportados.
Tipos de integração compatíveis supported-integration-types
Consulte a tabela abaixo para obter detalhes sobre quais tipos de integrações suportam a funcionalidade descrita nesta página.
Parâmetros compatíveis supported-parameters
Você pode modificar várias propriedades dos arquivos exportados para corresponder aos requisitos do sistema de recebimento de arquivos de destino, a fim de ler e interpretar de maneira ideal os arquivos recebidos do Experience Platform.
fileConfigurations não é obrigatória ao configurar um novo servidor de destino. Se você não passar nenhum valor na chamada de API para as opções de CSV, os valores padrão da tabela de referência abaixo serão usados.Opções de CSV nas quais os usuários não podem selecionar opções de configuração file-configuration-templating-none
No exemplo de configuração abaixo, todas as opções de CSV são predefinidas. As configurações de exportação definidas em cada um dos parâmetros csvOptions são finais e os usuários não podem modificá-las.
"fileConfigurations": {
"compression": {
"templatingStrategy": "PEBBLE_V1",
"value": "{{customerData.compression}}"
},
"fileType": {
"templatingStrategy": "PEBBLE_V1",
"value": "{{customerData.fileType}}"
},
"csvOptions": {
"quote": {
"templatingStrategy": "NONE",
"value": "\""
},
"quoteAll": {
"templatingStrategy": "NONE",
"value": "false"
},
"escape": {
"templatingStrategy": "NONE",
"value": "\\"
},
"escapeQuotes": {
"templatingStrategy": "NONE",
"value": "true"
},
"header": {
"templatingStrategy": "NONE",
"value": "true"
},
"ignoreLeadingWhiteSpace": {
"templatingStrategy": "NONE",
"value": "true"
},
"ignoreTrailingWhiteSpace": {
"templatingStrategy": "NONE",
"value": "true"
},
"nullValue": {
"templatingStrategy": "NONE",
"value": ""
},
"dateFormat": {
"templatingStrategy": "NONE",
"value": "yyyy-MM-dd"
},
"timestampFormat": {
"templatingStrategy": "NONE",
"value": "yyyy-MM-dd'T':mm:ss[.SSS][XXX]"
},
"charToEscapeQuoteEscaping": {
"templatingStrategy": "NONE",
"value": "\\"
},
"emptyValue": {
"templatingStrategy": "NONE",
"value": ""
}
},
"maxFileRowCount":5000000,
"includeFileManifest": {
"templatingStrategy":"PEBBLE_V1",
"value":"{{ customerData.includeFileManifest }}"
}
}
Opções de CSV nas quais os usuários podem selecionar opções de configuração file-configuration-templating-pebble
No exemplo de configuração abaixo, nenhuma das opções de CSV é predefinida. O value em cada um dos parâmetros csvOptions é configurado em um campo de dados do cliente correspondente por meio do ponto de extremidade /destinations (por exemplo, customerData.quote para a opção de formatação de arquivo quote) e os usuários podem usar a interface do usuário do Experience Platform para selecionar entre as várias opções configuradas no campo de dados do cliente correspondente. Você pode ver a aparência dessas opções na documentação opções de formatação de arquivo para destinos baseados em arquivo.
{
"fileConfigurations":{
"compression":{
"templatingStrategy":"PEBBLE_V1",
"value":"{% if customerData contains 'compression' and customerData.compression is not empty %}{{customerData.compression}}{% else %}NONE{% endif %}"
},
"fileType":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.fileType}}"
},
"csvOptions":{
"sep":{
"templatingStrategy":"PEBBLE_V1",
"value":"{% if customerData contains 'csvOptions' and customerData.csvOptions contains 'delimiter' %}{{customerData.csvOptions.delimiter}}{% else %},{% endif %}"
},
"quote":{
"templatingStrategy":"PEBBLE_V1",
"value":"{% if customerData contains 'csvOptions' and customerData.csvOptions contains 'quote' %}{{customerData.csvOptions.quote}}{% else %}\"{% endif %}"
},
"escape":{
"templatingStrategy":"PEBBLE_V1",
"value":"{% if customerData contains 'csvOptions' and customerData.csvOptions contains 'escape' %}{{customerData.csvOptions.escape}}{% else %}\\{% endif %}"
},
"nullValue":{
"templatingStrategy":"PEBBLE_V1",
"value":"{% if customerData contains 'csvOptions' and customerData.csvOptions contains 'nullValue' %}{{customerData.csvOptions.nullValue}}{% else %}null{% endif %}"
},
"emptyValue":{
"templatingStrategy":"PEBBLE_V1",
"value":"{% if customerData contains 'csvOptions' and customerData.csvOptions contains 'emptyValue' %}{{customerData.csvOptions.emptyValue}}{% else %}{% endif %}"
}
},
"maxFileRowCount":5000000,
"includeFileManifest": {
"templatingStrategy":"PEBBLE_V1",
"value":"{{ customerData.includeFileManifest }}"
}
}
}
Referência completa e exemplos de opções de formatação de arquivo compatíveis file-formatting-reference-and-example
Abaixo está uma referência completa de todas as opções de formatação de arquivo disponíveis em Destination SDK, juntamente com exemplos de saída para cada opção.
templatingStrategyPara cada opção de formatação de arquivo configurada, é necessário adicionar o parâmetro templatingStrategy, que pode ter dois valores:
NONE: use esse valor se não estiver planejando permitir que os usuários selecionem entre valores diferentes para uma configuração. Consulte esta configuração para obter um exemplo onde as opções de formatação de arquivo são corrigidas.PEBBLE_V1: use este valor se quiser permitir que os usuários selecionem entre valores diferentes para uma configuração. Nesse caso, você também deve configurar um campo de dados do cliente correspondente na configuração do ponto de extremidade/destinationpara exibir as várias opções aos usuários na interface do usuário. Consulte esta configuração para obter um exemplo em que os usuários podem selecionar entre valores diferentes para opções de formatação de arquivo.
compression.valuenone, bzip2, gzip, lz4 e snappy.nonefileType.valuecsv, parquet e json.csvcsvOptions.quote.value"fileType.value": "csv". Define um caractere único usado para sair de valores entre aspas onde o separador pode ser parte do valor.nullquote.value: "u0000" —> male,NULJohn,LastNameNULquote.value: "\"" —> male,"John,LastName"csvOptions.quoteAll.value"fileType.value": "csv". Indica se todos os valores devem sempre estar entre aspas. O padrão é omitir apenas valores que contenham um caractere de aspas.falsequoteAll:false —> male,John,"TestLastName"quoteAll:true —>"male","John","TestLastName"csvOptions.delimiter.value"fileType.value": "csv". Define um separador para cada campo e valor. Esse separador pode conter um ou mais caracteres.,delimiter:, —> comma-separated values"delimiter:\t —> tab-separated valuescsvOptions.escape.value"fileType.value": "csv". Define um caractere único usado para fazer o escape de aspas dentro de um valor já citado.\"escape":"\\" —> male,John,"Test,\"LastName5""escape":"'" —> male,John,"Test,'''"LastName5"csvOptions.escapeQuotes.value"fileType.value": "csv". Indica se os valores contendo aspas devem sempre estar entre aspas. O padrão é omitir todos os valores que contenham um caractere de aspas.truecsvOptions.header.value"fileType.value": "csv". Indica se os nomes das colunas devem ser gravados como a primeira linha no arquivo exportado.truecsvOptions.ignoreLeadingWhiteSpace.value"fileType.value": "csv". Indica se os espaços em branco à esquerda devem ser aparados dos valores.trueignoreLeadingWhiteSpace:true —> "male","John","TestLastName"ignoreLeadingWhiteSpace:false—> " male","John","TestLastName"csvOptions.ignoreTrailingWhiteSpace.value"fileType.value": "csv". Indica se espaços em branco à direita devem ser aparados de valores.trueignoreTrailingWhiteSpace:true —> "male","John","TestLastName"ignoreTrailingWhiteSpace:false—> "male ","John","TestLastName"csvOptions.nullValue.value"fileType.value": "csv". Define a representação da cadeia de caracteres de um valor nulo.""nullvalue:"" —> male,"",TestLastNamenullvalue:"NULL" —> male,NULL,TestLastNamecsvOptions.dateFormat.value"fileType.value": "csv". Indica o formato de data.yyyy-MM-dddateFormat:yyyy-MM-dd —> male,TestLastName,John,2022-02-24dateFormat:MM/dd/yyyy —> male,TestLastName,John,02/24/2022csvOptions.timestampFormat.value"fileType.value": "csv". Define a cadeia de caracteres que indica um formato de carimbo de data e hora.yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]csvOptions.charToEscapeQuoteEscaping.value"fileType.value": "csv". Define um único caractere usado para escapar do escape para o caractere de citação.\ quando os caracteres de escape e aspas são diferentes. \0 quando o caractere de escape e aspas são iguais.csvOptions.emptyValue.value"fileType.value": "csv". Define a representação da cadeia de caracteres de um valor vazio."""emptyValue":"" --> male,"",John"emptyValue":"empty" --> male,empty,JohnmaxFileRowCountincludeFileManifestmanifest-<<destinationId>>-<<dataflowRunId>>.json.Exibir um arquivo de manifesto de exemplo. O arquivo de manifesto inclui os seguintes campos:
flowRunId: A execução do fluxo de dados que gerou o arquivo exportado.scheduledTime: A hora em UTC quando o arquivo foi exportado.exportResults.sinkPath: O caminho no local de armazenamento onde o arquivo exportado está depositado.exportResults.name: O nome do arquivo exportado.size: O tamanho do arquivo exportado, em bytes.
Próximas etapas next-steps
Depois de ler este artigo, você terá uma melhor compreensão de como a formatação de arquivos funciona em uma configuração de servidor de destino e como configurá-la.
Para saber mais sobre os outros componentes do servidor de destino, consulte os seguintes artigos: