File Writer

Descubra mais sobre o componente File Writer e saiba como utilizá-lo na Digibee Integration Platform.

O File Writer escreve informações em um arquivo durante a execução do pipeline. Ele suporta strings simples, arrays de strings e dados binários codificados em base64.

Parâmetros

Configure o conector usando os parâmetros abaixo. Os campos que suportam expressões Double Braces estão marcados na coluna Suporta DB.

Parâmetro	Descrição	Tipo	Suporta DB	Padrão
File Name	Nome do arquivo ou caminho completo (por exemplo, tmp/processed/file.txt) do arquivo a ser criado pelo conector com as informações de input.	String	✅	data.csv
Data	Dados a serem gravados no arquivo. Aceita um array de strings ou uma string simples. Se o valor for um array, cada item é gravado em uma nova linha. Se o valor for um objeto em vez de uma string, ative o Coalesce para evitar um erro.	String	✅	{{ message.data }}
Policy for when file already exists	Comportamento a aplicar quando um arquivo com o mesmo nome já existe na execução atual. Opções: Append (adiciona dados ao arquivo existente), Override (substitui o arquivo existente), Fail (interrompe o fluxo com um erro).	String	❌	Override
End of Line policy	Caractere de fim de linha a ser usado. Opções: Windows (CR + LF, 2 caracteres), Unix (LF, 1 caractere), None (sem caractere de fim de linha).	String	❌	Windows
Charset	Codificação de caracteres a ser usada ao criar o arquivo.	String	❌	UTF-8
Binary file	Quando ativado, trata o valor em Data como uma string base64 e o converte para binário antes de gravar o arquivo.	Boolean	❌	False
Coalesce	Quando ativado, o conector aceita objetos e arrays como input e os grava no arquivo sem retornar um erro. Quando desativado e o input é um objeto (ou um array contendo objetos), o conector lança o erro "Invalid data from request. Could not save file with this data format".	Boolean	❌	False
Metadata	Um objeto JSON com pares chave-valor personalizados para anexar ao arquivo. Quando configurado, o conector retorna os metadados na resposta do step e, se Write metadata sidecar estiver ativado, os grava em um arquivo sidecar junto ao arquivo criado.	JSON Object ou JSON String	✅	N/A
Write metadata sidecar	Quando ativado e Metadata estiver configurado, o conector grava um arquivo sidecar {fileName}.metadata.json no diretório de trabalho do pipeline, junto ao arquivo criado. Quando desativado, os metadados são retornados apenas na resposta.	Boolean	❌	False
Fail on error	Quando ativado, o pipeline para se ocorrer um erro. Quando desativado, o pipeline continua e o output exibe "success": false.	Boolean	❌	False

Manipulação de arquivos no pipeline

O pipeline possui uma área local e temporária para manipulação de arquivos, isolada e disponível apenas durante a execução do pipeline.

Você deve tratar o acesso a arquivos como se fosse realizado em um sistema de arquivos virtual. Os nomes de arquivos podem usar quaisquer caracteres válidos e extensões de arquivo, e podem incluir um caminho de diretório relativo, por exemplo, data.csv ou processing/data.csv.

Quando Write metadata sidecar está ativado, o conector também cria um arquivo {fileName}.metadata.json no mesmo diretório do arquivo principal. Por exemplo, gravar data.csv com metadados produz tanto data.csv quanto data.csv.metadata.json no diretório de trabalho.

Qualquer tentativa de acessar diretórios absolutos fora do sistema de arquivos virtual do pipeline é bloqueada durante a execução.

Fluxo de mensagens

Input

O conector aceita qualquer mensagem de input e pode referenciá-la por meio de Double Braces.

Output

O conector retorna um objeto JSON com o nome do arquivo criado e o resultado da operação.

Sucesso

{
  "fileName": "data.csv",
  "success": true
}

Quando Metadata está configurado, a resposta também inclui o objeto de metadados:

{
  "fileName": "data.csv",
  "success": true,
  "metadata": {
    "source": "orders-pipeline",
    "environment": "production"
  }
}

Erro

{
  "success": false,
  "message": "File data.csv already exists.",
  "exception": "com.digibee.pipelineengine.exception.PipelineEngineRuntimeException"
}

Campos do output:

• fileName: Nome do arquivo gravado.

• success: true se a operação foi bem-sucedida; false se falhou.

• metadata: O objeto de metadados anexado ao arquivo. Retornado apenas quando Metadata está configurado.

• message: Descrição do erro. Retornado apenas quando "success" é false.

• exception: Classe do erro. Retornado apenas quando "success" é false.

File Writer em ação

Os exemplos abaixo mostram como o conector se comporta em situações específicas e a configuração correspondente para cada caso.

Gravar uma string em um arquivo de texto

Este exemplo usa dados de input estáticos e lê o resultado com o File Reader.

Configuração do File Writer

• File Name: booklist.txt

• Data: {{ message.data }}

• Policy for when file already exists: Append

• End of line policy: Windows

• Charset: UTF-8

• Binary file: desativado

• Coalesce: desativado

• Fail on error: desativado

Input

{
  "data": "To Kill a Mockingbird\n1984\nHarry Potter and the Philosopher's Stone\nThe Lord of the Rings\nThe Great Gatsby\nPride and Prejudice\nThe Diary Of A Young Girl\nThe Book Thief\nThe Hobbit\nLittle Women\nFahrenheit 451\nJane Eyre\nAnimal Farm\nGone with the Wind\nThe Catcher in the Rye\nCharlotte's Web\nThe Lion, the Witch\nThe Grapes of Wrath\nLord of the Flies\nThe Kite Runner\nOf Mice and Men\nA Tale of Two Cities\nRomeo and Juliet\nThe Hitchhikers Guide to the Galaxy\nWuthering Heights\nThe Color Purple\nAlice in Wonderland\nFrankenstein\nThe Adventures of Huckleberry Finn\nSlaughterhouse-Five"
}

Output

{
  "fileName": "booklist.txt",
  "success": true
}

Leitura do arquivo criado

{"data": ["To Kill a Mockingbird","1984","Harry Potter and the Philosopher's Stone","The Lord of the Rings","The Great Gatsby","Pride and Prejudice","The Diary Of A Young Girl","The Book Thief","The Hobbit","Little Women","Fahrenheit 451","Jane Eyre","Animal Farm","Gone with the Wind","The Catcher in the Rye","Charlotte's Web","The Lion, the Witch","The Grapes of Wrath","Lord of the Flies","The Kite Runner","Of Mice and Men","A Tale of Two Cities","Romeo and Juliet","The Hitchhikers Guide to the Galaxy","Wuthering Heights","The Color Purple","Alice in Wonderland","Frankenstein","The Adventures of Huckleberry Finn","Slaughterhouse-Five"],"fileName": "booklist.txt","lineCount": 30}

Gravar dados codificados em base64 em um arquivo

Este exemplo usa dados de input base64 estáticos e lê o resultado com o File Reader. Com Binary file ativado, o conector decodifica a string base64 antes de gravar o arquivo.

Configuração

• File Name: booklist.txt

• Data: {{ message.data }}

• Policy for when file already exists: Append

• End of line policy: Windows

• Charset: UTF-8

• Binary file: ativado

• Coalesce: desativado

• Fail on error: desativado

Input

{
  "data": "VG8gS2lsbCBhIE1vY2tpbmdiaXJkCjE5ODQKSGFycnkgUG90dGVyIGFuZCB0aGUgUGhpbG9zb3BoZXLigJlzIFN0b25lClRoZSBMb3JkIG9mIHRoZSBSaW5ncwpUaGUgR3JlYXQgR2F0c2J5ClByaWRlIGFuZCBQcmVqdWRpY2UKVGhlIERpYXJ5IE9mIEEgWW91bmcgR2lybApUaGUgQm9vayBUaGllZgpUaGUgSG9iYml0CkxpdHRsZSBXb21lbgpGYWhyZW5oZWl0IDQ1MQpKYW5lIEV5cmUKQW5pbWFsIEZhcm0KR29uZSB3aXRoIHRoZSBXaW5kClRoZSBDYXRjaGVyIGluIHRoZSBSeWUKQ2hhcmxvdHRl4oCZcyBXZWIKVGhlIExpb24sIHRoZSBXaXRjaApUaGUgR3JhcGVzIG9mIFdyYXRoCkxvcmQgb2YgdGhlIEZsaWVzClRoZSBLaXRlIFJ1bm5lcgpPZiBNaWNlIGFuZCBNZW4KQSBUYWxlIG9mIFR3byBDaXRpZXMKUm9tZW8gYW5kIEp1bGlldApUaGUgSGl0Y2hoaWtlcnMgR3VpZGUgdG8gdGhlIEdhbGF4eQpXdXRoZXJpbmcgSGVpZ2h0cwpUaGUgQ29sb3IgUHVycGxlCkFsaWNlIGluIFdvbmRlcmxhbmQKRnJhbmtlbnN0ZWluClRoZSBBZHZlbnR1cmVzIG9mIEh1Y2tsZWJlcnJ5IEZpbm4KU2xhdWdodGVyaG91c2UtRml2ZQ=="
}

Output

{
  "fileName": "booklist.txt",
  "success": true
}

Leitura do arquivo criado

{
  "data": [
    "To Kill a Mockingbird",
    "1984",
    "Harry Potter and the Philosopher's Stone",
    "The Lord of the Rings",
    "The Great Gatsby",
    "Pride and Prejudice",
    "The Diary Of A Young Girl",
    "The Book Thief",
    "The Hobbit",
    "Little Women",
    "Fahrenheit 451",
    "Jane Eyre",
    "Animal Farm",
    "Gone with the Wind",
    "The Catcher in the Rye",
    "Charlotte's Web",
    "The Lion, the Witch",
    "The Grapes of Wrath",
    "Lord of the Flies",
    "The Kite Runner",
    "Of Mice and Men",
    "A Tale of Two Cities",
    "Romeo and Juliet",
    "The Hitchhikers Guide to the Galaxy",
    "Wuthering Heights",
    "The Color Purple",
    "Alice in Wonderland",
    "Frankenstein",
    "The Adventures of Huckleberry Finn",
    "Slaughterhouse-Five"
  ],
  "fileName": "booklist.txt",
  "lineCount": 30
}

Gravar um JSON multinível em um arquivo

Este exemplo usa um JSON multinível estático como input e lê o resultado com o File Reader. O Coalesce está ativado para que o conector aceite um objeto como input.

Configuração

• File Name: product.txt

• Data: {{ message.data }}

• Policy for when file already exists: Append

• End of line policy: Windows

• Charset: UTF-8

• Binary file: desativado

• Coalesce: ativado

• Fail on error: desativado

Input

{
  "data": {
    "products": [
      {
        "name": "Samsung 4k Q60T 55",
        "price": 3278.99
      },
      {
        "name": "Samsung galaxy S20 128GB",
        "price": 3698.99
      }
    ]
  }
}

Output

{
  "fileName": "product.txt",
  "success": true
}

Leitura do arquivo criado

O output abaixo é proveniente do conector File Reader lendo o arquivo gravado pelo File Writer.

{
  "data": [
    "{\"products\":[{\"name\":\"Samsung 4k Q60T 55\",\"price\":3278.99},{\"name\":\"Samsung galaxy S20 128GB\",\"price\":3698.99}]}"
  ],
  "fileName": "product.txt",
  "lineCount": 1
}

O JSON multinível é serializado e gravado como uma única linha no arquivo.

Falhar quando um arquivo já existe

Este exemplo usa dois conectores File Writer em sequência, ambos configurados com a política Fail. A segunda tentativa de gravação falha porque o arquivo já foi criado pelo primeiro conector.

Configuração

• File Name: booklist.txt

• Data: {{ message.data }}

• Policy for when file already exists: Fail

• End of line policy: Windows

• Charset: UTF-8

• Binary file: desativado

• Coalesce: desativado

• Fail on error: desativado

Input

{
  "data": "To Kill a Mockingbird\n1984\nHarry Potter and the Philosopher's Stone\nThe Lord of the Rings\nThe Great Gatsby\nPride and Prejudice\nThe Diary Of A Young Girl\nThe Book Thief\nThe Hobbit\nLittle Women\nFahrenheit 451\nJane Eyre\nAnimal Farm\nGone with the Wind\nThe Catcher in the Rye\nCharlotte's Web\nThe Lion, the Witch\nThe Grapes of Wrath\nLord of the Flies\nThe Kite Runner\nOf Mice and Men\nA Tale of Two Cities\nRomeo and Juliet\nThe Hitchhikers Guide to the Galaxy\nWuthering Heights\nThe Color Purple\nAlice in Wonderland\nFrankenstein\nThe Adventures of Huckleberry Finn\nSlaughterhouse-Five"
}

Output

{
  "success": false,
  "message": "File booklist.txt already exists.",
  "exception": "com.digibee.pipelineengine.exception.PipelineEngineRuntimeException"
}

Gravar um arquivo com metadados personalizados

Este exemplo anexa metadados personalizados a um arquivo durante o processamento. O pipeline grava um relatório de pedidos e o etiqueta com informações de rastreabilidade (o pipeline de origem e o ambiente) para que os steps subsequentes e os sistemas de armazenamento possam usar esses valores sem precisar ler o conteúdo do arquivo.

Configuração

• File Name: orders-report.csv

• Data: {{ message.data }}

• Policy for when file already exists: Override

• End of line policy: Unix

• Charset: UTF-8

• Binary file: desativado

• Coalesce: desativado

• Metadata: { "source": "{{ message.pipelineName }}", "environment": "production", "generatedBy": "orders-pipeline" }

• Write metadata sidecar: ativado

• Fail on error: desativado

Input

{
  "pipelineName": "orders-export-v2",
  "data": "orderId,customerId,status,total\nORD-001,C-123,completed,299.90\nORD-002,C-456,pending,149.50\nORD-003,C-789,completed,89.00"
}

Output

{
  "fileName": "orders-report.csv",
  "success": true,
  "metadata": {
    "source": "orders-export-v2",
    "environment": "production",
    "generatedBy": "orders-pipeline"
  }
}

Como Write metadata sidecar está ativado, o conector também grava orders-report.csv.metadata.json no diretório de trabalho do pipeline com o mesmo conteúdo:

{
  "source": "orders-export-v2",
  "environment": "production",
  "generatedBy": "orders-pipeline"
}

Um conector subsequente no pipeline pode então ler orders-report.csv.metadata.json usando o File Reader e repassar os metadados para um conector de armazenamento, como o AWS S3 Storage, sem precisar codificar esses valores em cada step.