Como no S3 h\u00e1 uma separa\u00e7\u00e3o entre processamento e armazenamento, os nossos modelos<\/a> n\u00e3o se aplicam a este destino. Al\u00e9m disso, as opera\u00e7\u00f5es de agrega\u00e7\u00e3o de dados e desduplica\u00e7\u00e3o (UPSERT) devem ser feitas por voc\u00ea, seja na camada de virtualiza\u00e7\u00e3o ou com scripts como o AWS Glue<\/a>. Para ajud\u00e1-lo neste processo, n\u00f3s adicionamos neste destino a possibilidade de voc\u00ea enviar notifica\u00e7\u00f5es para URLs<\/a> que ir\u00e3o disparar estes processos.<\/p>\n\n\n\n Abaixo n\u00f3s iremos explicar detalhadamente como funciona o nosso destino S3 e como adicion\u00e1-lo na Kondado.<\/p>\n\n\n\n O primeiro passo para adicionar o S3 como destino \u00e9 a cria\u00e7\u00e3o de uma chave de acesso na AWS para utiliza\u00e7\u00e3o da Kondado. Voc\u00ea pode acompanhar neste tutorial da AWS como faz\u00ea-lo.<\/a><\/p>\n\n\n\n A access key criada pode utilizar o exemplo de pol\u00edtica abaixo<\/p>\n\n\n\n Lembre-se de editar a vari\u00e1vel “CHANGE-THIS-WITH-BUCKET-NAME” com o nome do seu bucket de fato<\/strong><\/p>\n\n\n\n Al\u00e9m disso, voc\u00ea deve criar um bucket onde os dados ser\u00e3o armazenados<\/a>.<\/p>\n\n\n\n Caso o seu bucket utilize criptografia com KMS, tamb\u00e9m \u00e9 necess\u00e1rio dar ao IAM permiss\u00e3o para acessar a KMS key (substitua REGION:ACCOUNT-ID e CHANGE-THIS-WITH-KMS-KEY-ID): Veja mais neste tutorial da AWS<\/a>\n De posse da access key e do bucket, voc\u00ea j\u00e1 pode preencher as primeiras informa\u00e7\u00f5es de cria\u00e7\u00e3o do destino<\/a><\/p>\n\n\n\n Atualmente, enviamos arquivos nos seguintes formatos:<\/p>\n\n\n\n Este formato salva dados no formato JSON, um em cada linha do arquivo, com aspas escapadas por \\. Este \u00e9 um exemplo de um arquivo jsonl que ser\u00e1 enviado para o seu data lake:<\/p>\n\n\n\n Caso voc\u00ea n\u00e3o aplique compress\u00e3o, os arquivos ser\u00e3o salvos com a extens\u00e3o “.json”<\/p>\n\n\n\n O formato CSV ir\u00e1 salvar arquivos neste formato tradicional e com extens\u00e3o “.csv” caso voc\u00ea n\u00e3o tenha fornecido nenhum m\u00e9todo de compress\u00e3o. Voc\u00ea precisar\u00e1 fornecer alguns par\u00e2metros adicionais de formata\u00e7\u00e3o do arquivo:<\/p>\n\n\n\n 2.2.1 Delimitador de colunas<\/strong><\/p>\n\n\n\n Os valores poss\u00edveis para o delimitador de colunas s\u00e3o<\/p>\n\n\n\n 2.2.2 Quote<\/strong><\/p>\n\n\n\n O par\u00e2metro quote indica como cada coluna em uma linha do arquivo ser\u00e1 envolta em aspas. As op\u00e7\u00f5es poss\u00edveis s\u00e3o um mapeamento 1 x 1 com o m\u00f3dulo CSV<\/a> do python<\/p>\n\n\n\n Recomendamos o formato “All”.<\/p>\n\n\n\n Como voc\u00ea deve ter percebido, quote e o delimitador de colunas podem entrar em conflito com o seu conte\u00fado caso estes caracteres tamb\u00e9m estejam presentes nos valores. Ent\u00e3o, todos os arquivos salvos possuem um caracter de escape padr\u00e3o para valores conflitantes, o backslash (“\\”).<\/p>\n\n\n\n 2.2.3 Cabe\u00e7alho<\/strong><\/p>\n\n\n\n Voc\u00ea tamb\u00e9m pode escolher se deseja que os arquivos enviados venham com cabe\u00e7alho ou n\u00e3o. Lembrando que, se voc\u00ea cadastrar uma URL de notifica\u00e7\u00f5es, o envio de cabe\u00e7alho torna-se desnecess\u00e1rio, pois n\u00f3s enviaremos para voc\u00ea o schema do objeto, com a ordem das colunas de acordo como foram escritas no arquivo. A ordem das colunas tamb\u00e9m obedecer\u00e1 a mesma ordem de exibi\u00e7\u00e3o da nossa UI quando voc\u00ea clica em “DETALHES” de uma dada integra\u00e7\u00e3o.<\/p>\n\n\n\n Este formato salva dados no formato parquet.<\/p>\n\n\n\n Caso voc\u00ea n\u00e3o aplique compress\u00e3o, os arquivos ser\u00e3o salvos com a extens\u00e3o “.parquet”<\/p>\n\n\n\n Voc\u00ea pode escolher aplicar um m\u00e9todo de compress\u00e3o aos seus arquivos ou n\u00e3o. Os m\u00e9todos de compress\u00e3o dispon\u00edveis ir\u00e3o alterar a extens\u00e3o dos arquivos salvos.<\/p>\n\n\n\n Os arquivos comprimidos com o m\u00e9todo gzip ir\u00e3o receber a extens\u00e3o “.gz”<\/p>\n\n\n\n Caso o par\u00e2metro “Notificar alguma URL” seja preenchido, voc\u00ea precisar\u00e1 informar uma URL v\u00e1lida em “URL para notifica\u00e7\u00f5es”. Esta URL deve estar habilitada para receber posts.<\/p>\n\n\n\n Ao fim de uma integra\u00e7\u00e3o, para cada objeto integrado e para cada opera\u00e7\u00e3o, n\u00f3s faremos um post na URL informada:<\/p>\n\n\n\n Iremos considerar como sucesso uma notifica\u00e7\u00e3o para a URL informada que retorne um c\u00f3digo de resposta 200 em at\u00e9 30 segundos. Caso a resposta seja diferente disto ou demore mais, iremos realizar mais 3 tentativas e apontar um erro na integra\u00e7\u00e3o caso a falha persista. Entretanto, os arquivos nas pastas\/prefixos full e deltas n\u00e3o ser\u00e3o apagados<\/p>\n\n\n\n Com os dados que ser\u00e3o enviados para a sua URL de notifica\u00e7\u00e3o, voc\u00ea ter\u00e1 todas as informa\u00e7\u00f5es necess\u00e1rias para disparar processos posteriores para manipula\u00e7\u00e3o dos arquivos enviados. Os campos padr\u00f5es do JSON de payload s\u00e3o os seguintes:<\/p>\n\n\n\n 4.3.1 pipeline_id<\/strong><\/p>\n\n\n\n Id da integra\u00e7\u00e3o que gerou os arquivos. O id de uma integra\u00e7\u00e3o pode ser obtido atrav\u00e9s da URL da integra\u00e7\u00e3o da Kondado no seu navegador: https:\/\/app.kondado.com.br\/pipelines\/id_da_integracao<\/strong><\/p>\n\n\n\n Exemplo:<\/p>\n\n\n\n 4.3.2 bucket<\/strong><\/p>\n\n\n\n Bucket onde os arquivos foram enviados. Corresponde ao bucket cadastrado por voc\u00ea nos par\u00e2metros do destino no momento em que a integra\u00e7\u00e3o salvou os arquivos<\/p>\n\n\n\n Exemplo:<\/p>\n\n\n\n 4.3.3 kdd_operation<\/strong><\/p>\n\n\n\n Opera\u00e7\u00e3o que disparou a notifica\u00e7\u00e3o. Os valores poss\u00edveis s\u00e3o:<\/p>\n\n\n\n Exemplo:<\/p>\n\n\n\n 4.3.4 kdd_replication_type<\/strong><\/p>\n\n\n\n O tipo de replica\u00e7\u00e3o desta integra\u00e7\u00e3o (integral\/incremental). Para integra\u00e7\u00f5es incrementais, voc\u00ea deve fazer “upsert” dos valores dos arquivos com o seu arquivo principal. Para integra\u00e7\u00f5es integrais, os novos arquivos enviados devem substituir o arquivo principal anterior.<\/p>\n\n\n\n Os valores poss\u00edveis deste par\u00e2metro s\u00e3o:<\/p>\n\n\n\n Este par\u00e2metro \u00e9 enviado apenas quando kdd_operation=merge_full.<\/p>\n\n\n\n Exemplo:<\/p>\n\n\n\n 4.3.5 kdd_replication_keys<\/strong><\/p>\n\n\n\n Caso a sua integra\u00e7\u00e3o seja incremental (kdd_replication_type=savepoint), ent\u00e3o este campo ir\u00e1 conter os campos (separados por v\u00edrgula) que voc\u00ea dever\u00e1 utilizar para fazer upsert<\/strong> com o arquivo principal.<\/p>\n\n\n\n Exemplo:<\/p>\n\n\n\n 4.3.6 schema<\/strong><\/p>\n\n\n\n Array de jsons com os campos enviados para os arquivos, na ordem em que aparecem (\u00fatil para CSV e tamb\u00e9m para que o seu arquivo agregador principal tenha uma tipagem condizente com os seus dados).<\/p>\n\n\n\n Neste array, cada json corresponder\u00e1 a um campo no arquivo de destino e conter\u00e1 as seguintes informa\u00e7\u00f5es:<\/p>\n\n\n\n Exemplo:<\/p>\n\n\n\n 4.3.7 files<\/strong><\/p>\n\n\n\n Array com os nomes arquivos disponibilizados e a sua localiza\u00e7\u00e3o (prefixo). Por exemplo:<\/p>\n\n\n\n 4.3.8 file_format<\/strong><\/p>\n\n\n\n Formato do arquivo final criado. Lembre-se que, caso o arquivo sofra compress\u00e3o, o formato n\u00e3o corresponder\u00e1 \u00e0 sua extens\u00e3o, mas o arquivo “dentro” do arquivo comprimido estar\u00e1 neste formato. Exemplo:<\/p>\n\n\n\n 4.3.9 file_format_params<\/strong><\/p>\n\n\n\n Caso o formato de arquivo selecionado requeira par\u00e2metros adicionais de formata\u00e7\u00e3o (por exemplo, CSV) este campo ir\u00e1 trazer um JSON com os par\u00e2metros utilizados para criar o arquivo.<\/p>\n\n\n\n Exemplo (CSV):<\/p>\n\n\n\n 4.3.10 file_compression<\/strong><\/p>\n\n\n\n Este par\u00e2metro indica a compress\u00e3o aplicada ao arquivo de sa\u00edda. Caso nenhuma compress\u00e3o tenha sido aplicada, o seu valor ser\u00e1 “no”.<\/p>\n\n\n\n Exemplo:<\/p>\n\n\n\n 4.3.11 kdd_row_count<\/strong><\/p>\n\n\n\n Este par\u00e2metro indica quantos registros\/linhas h\u00e1 no total nos arquivos enviados.<\/p>\n\n\n\n Exemplo:<\/p>\n\n\n\n Caso o par\u00e2metro “Incluir prefixo no nome do arquivo?” seja preenchido, voc\u00ea dever\u00e1 incluir um texto que ir\u00e1 ser inserido no in\u00edcio do nome do arquivo a ser enviado. Este texto pode conter caracteres de formata\u00e7\u00e3o que possam ajudar a particionar os arquivos em pastas no S3 (exemplo<\/a>).<\/p>\n\n\n\n O nome\/parte final do arquivo, sempre ser\u00e1 a timestamp em que foi executada a integra\u00e7\u00e3o + extens\u00e3o, neste formato: [YYYYMMDDhhmmssfffff] [.] [extens\u00e3o]<\/strong><\/p>\n\n\n\n Al\u00e9m deste nome fixo, com este par\u00e2metro de prefixo, voc\u00ea pode adicionar vari\u00e1veis que ajudar\u00e3o a organizar o seu bucket, s\u00e3o eles:<\/p>\n\n\n\n Estas vari\u00e1veis podem ser combinadas com texto livres e ser\u00e3o concatenadas na frente do nome do arquivo durante a inser\u00e7\u00e3o no S3.<\/p>\n\n\n\n Aten\u00e7\u00e3o<\/strong>: \u00c9 necess\u00e1rio que sejam escritos os colchetes – ] e [<\/p>\n\n\n\n Exemplo<\/strong><\/p>\n\n\n\n Considere que foi preenchido o seguinte prefixo:<\/p>\n\n\n\n Sendo o nome final do arquivo este:<\/p>\n\n\n\n Neste caso, o nome a ser escrito na tabela do destino ser\u00e1:<\/p>\n\n\n\n Perceba que foi utilizado uma barra “\/” no final do prefixo ([exec_year]\/month=[exec_month]\/{day=[exec_day]}\/<\/strong><\/span>) – caso essa barra n\u00e3o fosse inserida, o arquivo seria 2021\/month=09\/{day=22}2<\/span><\/strong>0210922161050851020.json, que pode n\u00e3o ser o que voc\u00ea deseja<\/p>\n\n\n\n Para colunas do tipo date<\/em> e timestamp<\/em>, \u00e9 poss\u00edvel especificar o formato de datas:<\/p>\n\n\n\n1. Cria\u00e7\u00e3o da chave de acesso<\/h3>\n\n\n\n
{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Action\": [\n \"s3:ListBucket\",\n \"s3:GetObject\",\n \"s3:PutObject\",\n \"s3:DeleteObject\",\n \"s3:CopyObject\",\n \"s3:AbortMultipartUpload\",\n \"s3:ListMultipartUploadParts\",\n \"s3:GetBucketLocation\",\n \"s3:ListBucketMultipartUploads\",\n \"s3:DeleteObjectTagging\",\n \"s3:ReplicateObject\",\n \"s3:GetObjectAcl\",\n \"s3:DeleteObjectVersion\",\n \"s3:PutObjectTagging\",\n \"s3:PutObjectAcl\"\n ],\n \"Resource\": [\n \"arn:aws:s3:::CHANGE-THIS-WITH-BUCKET-NAME\",\n \"arn:aws:s3:::CHANGE-THIS-WITH-BUCKET-NAME\/*\"\n ]\n }\n ]\n}\n<\/code><\/pre>\n\n\n\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Action\": [\n \"kms:Encrypt\",\n \"kms:Decrypt\",\n \"kms:ReEncrypt*\",\n \"kms:GenerateDataKey*\",\n \"kms:DescribeKey\"\n ],\n \"Resource\": \"arn:aws:kms:REGION:ACCOUNT-ID:key\/CHANGE-THIS-WITH-KMS-KEY-ID\"\n }\n ]\n}<\/code><\/p><\/code><\/pre>\n\n\n\n![\"\"](\"https:\/\/kondado.com.br\/blog\/wiki\/wp-content\/uploads\/sites\/2\/2020\/11\/image.png\")
<\/figure>\n\n\n\ns3:\/\/meu-bucket<\/s>” est\u00e1 errado. Lembre-se tamb\u00e9m de utilizar apenas o nome ra\u00edz do bucket, sem pastas filhas. Por exemplo, “meu-bucket\/minha-pasta<\/s>” est\u00e1 errado – caso queira colocar uma pasta adiciona, fa\u00e7a isso ao preencher o nome da tabela<\/a> na integra\u00e7\u00e3o<\/li><\/ul>\n\n\n\n2. Formato do arquivo de sa\u00edda<\/h3>\n\n\n\n
2.1 JSON (jsonl)<\/h4>\n\n\n\n
{\"\\\"keyword\\\"\":\"y\",\"\\\"url\\\"\":\"https:\\\/\\\/mailchi.mp\\\/a37895aff5ac\\\/subscribe_newsletter\",\"\\\"title\\\"\":\"https:\\\/\\\/mailchi.mp\\\/a37895aff5ac\\\/subscribe_newsletter\",\"\\\"timestamp\\\"\":1572559835000,\"\\\"clicks\\\"\":1}\n{\"\\\"keyword\\\"\":\"z\",\"\\\"url\\\"\":\"https:\\\/\\\/pipedrivewebforms.com\\\/form\\\/43fd725e54683d565a44ed4872c3560f4639452\",\"\\\"title\\\"\":\"Kondado - contato\",\"\\\"timestamp\\\"\":1572560617000,\"\\\"clicks\\\"\":2}<\/code><\/pre>\n\n\n\n2.2 CSV<\/h4>\n\n\n\n
2.3 Parquet<\/h4>\n\n\n\n
3. Compress\u00e3o<\/h3>\n\n\n\n
3.1 GZIP<\/h4>\n\n\n\n
4. URL de notifica\u00e7\u00e3o<\/h3>\n\n\n\n
4.1 Quando ocorrer\u00e1 a notifica\u00e7\u00e3o na URL?<\/h4>\n\n\n\n
4.2 E se a URL falhar?<\/h4>\n\n\n\n
4.3 Payload enviado<\/h4>\n\n\n\n
\"pipeline_id\":231923<\/pre>\n\n\n\n
\"bucket\":\"my-kdd-data-lake\"<\/pre>\n\n\n\n
\"kdd_operation\":\"merge_deltas\"<\/pre>\n\n\n\n
\"kdd_replication_type\":\"savepoint\"<\/pre>\n\n\n\n
\"kdd_replication_keys\":\"lead_email,campaign_id\"<\/pre>\n\n\n\n
\"schema\":[
{
\"db_name\":\"lead_id\",
\"type\":\"text\",
\"key\":\"id\"
},
{
\"db_name\":\"etapa\",
\"type\":\"text\",
\"key\":\"Etapas__PerguntasRespostas->Etapa\"
},
{
\"db_name\":\"pergunta\",
\"type\":\"text\",
\"key\":\"Etapas__PerguntasRespostas->Pergunta\"
}
]<\/pre>\n\n\n\n\"files\":[\n \"page_hits_deltas\/20201030220519913118.gz\",\n \"page_hits_deltas\/20201030220533013600.gz\"\n ]<\/pre>\n\n\n\n
\"file_format\":\"json\"<\/pre>\n\n\n\n
\"file_format_params\":{\n \"csv_delimiter\":\"pipe\",\n \"csv_quote\":\"all\",\n \"csv_include_header\":\"yes\"\n}<\/pre>\n\n\n\n\"file_compression\":\"gzip\"<\/pre>\n\n\n\n
\"kdd_row_count\":29173<\/pre>\n\n\n\n
5. Prefixo<\/h3>\n\n\n\n
[exec_year]\/month=[exec_month]\/{day=[exec_day]}\/<\/strong><\/pre>\n\n\n\n20210922161050851020.json<\/pre>\n\n\n\n
2021\/month=09\/{day=22}\/<\/strong>20210922161050851020.json<\/pre>\n\n\n\n6. Formato de data<\/h3>\n\n\n\n
![\"\"](\"https:\/\/kondado.com.br\/blog\/wiki\/wp-content\/uploads\/sites\/2\/2021\/10\/S3-dest_-esquema-nome-do-arquivo-1-1024x525.png\")
<\/figure><\/div>\n\n\n\n