JSON para Tabela

• Tipo de Tarefa: json-to-table

A Tarefa "JSON para Tabela" permite importar dados de um ficheiro JSON com estrutura tabular e inseri-los numa tabela de um base de dados. A sua função é dupla: conecta-se a um base de dados para escrever fisicamente os dados e, ao mesmo tempo, expõe os dados importados como um Dataset para utilização por Tarefas subsequentes no Workflow (como um Iterator). Esta Tarefa trabalha com um JSON de entrada fornecido por uma Tarefa anterior (ex. Importar Texto).

1. Conexão com o Base de Dados

Nesta aba, configuram-se todos os parâmetros para estabelecer a ligação ao base de dados de destino.

Tabela de Destino

É possível definir a origem das credenciais para a ligação:

• Manual: permite a inserção manual de todos os dados da ligação e da tabela nos campos abaixo.
• Environment: permite utilizar um ambiente de conexão pré-configurada. Ao selecionar um, os campos de autenticação são preenchidos automaticamente.

Tipo de Base de Dados

Define o tipo de base de dados (DBMS) ao qual se pretende ligar. As opções suportadas incluem:

• PostgreSQL
• SQL Server
• MySQL
• Oracle DB: permite especificar a ligação através de SID ou SERVICE.
• SAP HANA

Ligação SSL

Indica se a ligação ao base de dados deve ocorrer através de um canal seguro.

Autenticação

Campo	Descrição
Host	Endereço do base de dados externo autorizado.
Porta	Porta prevista da ligação ao base de dados externo.
Nome DB	Nome do base de dados ao qual se pretende ligar.
User	Nome de utilizador para aceder ao base de dados.
Definir Password	Abre uma janela para inserir a palavra-passe de forma segura.

Gestão de Tabela

Define como a tarefa deve interagir com a tabela física no base de dados.

1. Tabela de destino: determina a ação a executar na tabela:

• Criar tabela: cria sempre uma nova tabela. A operação falha se já existir uma tabela com o mesmo nome.
• Criar tabela se não existir: cria uma nova tabela apenas se não existir já uma tabela com o mesmo nome.
• Tabela existente: insere os dados numa tabela já presente. Por defeito, os novos dados são adicionados aos já existentes (Append). Ao ativar a caixa Truncate Insert, a tabela é esvaziada antes de inserir os novos dados.

2. Nome da tabela de destino: nome da tabela a ser criada ou onde os dados serão escritos (ex. utenti, prodotti, log_eventi).

2. Estrutura Tabular

A aba Estrutura Tabular permite definir os campos (colunas) da tabela e mapear cada coluna com os elementos do ficheiro JSON de origem.

Campos Disponíveis

Cada linha representa uma coluna da tabela. Para cada campo é possível configurar:

Campo	Descrição
Tipo	Tipo de dado do campo. Valores disponíveis: NUMERICO, STRINGA, DATA, DATA E ORA
Precisão	Para NUMERICO: número máximo de dígitos; para STRINGA: comprimento máximo
Alias	Nome efetivo da coluna na tabela do base de dados. Será este o nome visível no DB.
Expressão JSONPath	Expressão JSONPath para extrair o valor do ficheiro JSON de origem (ex. $.persona.info.name)

Gestão da Estrutura da Tabela

Na parte inferior direita da Estrutura Tabular, existem três botões:

Botão	Ação
Guardar	Guarda a estrutura definida
Importar	Importa uma estrutura existente
Exportar	Exporta a estrutura definida

Esta funcionalidade permite guardar, exportar ou reutilizar mapeamentos, evitando a compilação manual de campos e reduzindo o risco de erros.

Nota Técnica

• Visibilidade: As estruturas guardadas no sistema são visíveis apenas para o utilizador que as criou.
• Aprofundamento: Para uma descrição detalhada de todas as opções e da lógica de funcionamento, consulte a página Estrutura da Tabela.

3. Exemplo de configuração

Para criar uma tabela utenti com os seguintes campos:

Tipo	Alias	Expressão JSONPath
STRINGA	name	$.user.info.name
STRINGA	email	$.user.info.email
NUMERICO	age	$.user.info.age
STRINGA	city	$.address.city
DATA	registration_date	$.registration.date
DATA E HORA	registration_datetime	$.registration.datetime

O resultado desta configuração será a criação de uma tabela no banco de dados com as colunas name, email, age, city, registration_date e registration_datetime (Alias) preenchidas com os valores extraídos do JSON (Expressão JSONPath).

Alias com caracteres especiais ou maiúsculas

Se pretender usar letras maiúsculas, caracteres especiais ou espaços nos nomes das colunas, é necessário envolver o Alias em aspas duplas (ex: "Nome de Utilizador").

Tipo	Alias	Expressão JSONPath
STRINGA	“Name”	$.name
STRINGA	“Surname”	$.surname

Resultado no Banco de Dados

4. Gestão de estruturas JSON aninhadas

O Task JSON to Table é capaz de lidar com ficheiros JSON que contêm estruturas aninhadas, como arrays ou objetos dentro de outros objetos. Através da Expressão Path/Query, é possível extrair blocos aninhados inteiros ou valores individuais, mapeando-os para colunas da tabela. O Task pode serializar um objeto aninhado numa única coluna de texto, preservando a estrutura original em formato JSON.

Exemplo: Estruturas complexas aninhadas

O Task gere com a mesma facilidade estruturas muito mais complexas. Consideremos um JSON onde departments contém um objeto, que por sua vez contém um array de outros objetos.

[
  {
    "name": "Luca",
    "surname": "Rossi",
    "departments": {
      "department": [
        {
          "details": {
            "name": "Marketing",
            "location": "Milan"
          }
        },
        {
          "details": {
            "name": "Sales",
            "location": "Rome"
          }
        }
      ]
    }
  },
  {
    "name": "Maria",
    "surname": "Bianchi",
    "departments": {
      "department": [
        {
          "details": {
            "name": "HR",
            "location": "Florence"
          }
        }
      ]
    }
  }
]

Neste caso também, a configuração na "Estrutura Tabular" permanece idêntica:

Tipo	Precisão	Alias	Expressão JSONPath
String	1000	name	$.name
String	1000	surname	$.surname
String	4000	departments	$.departments

O Task pegará no objeto inteiro associado à chave departments e serializá-lo numa única string JSON.

Resultado no Banco de Dados:

nome	apelido	departamentos
Luca	Rossi	{"department":[{"details":{"name":"Marketing","location":"Milan"}},{"details":{"name":"Sales","location":"Rome"}}]}
Maria	Bianchi	{"department":[{"details":{"name":"HR","location":"Florence"}}]}

Extração de subelementos com JSONPath

Se, por outro lado, for necessário extrair elementos aninhados individuais, como por exemplo os nomes dos departamentos, é possível utilizar uma Expressão JSONPath específica. Por exemplo:

Tipo	Precisão	Alias	Expressão JSONPath
String	1000	name	$.name
String	1000	surname	$.surname
String	1000	department_names	$.departments.department[*].details.name

Com esta configuração, a Tarefa JSON para Tabela seleciona todos os valores name presentes no array department e insere-os na coluna department_names do banco de dados, separando-os eventualmente por uma vírgula.

Resultado no Banco de Dados

name	surname	department_names
Luca	Rossi	Marketing, Sales
Maria	Bianchi	HR

Esta abordagem permite extrair apenas os dados necessários, sem serializar todo o bloco JSON, tornando a tabela mais facilmente consultável e utilizável em outras Tarefas ou relatórios.

5. Parâmetros de Saída

Assim que a Tarefa "JSON to Table" concluir o processamento, expõe um rico conjunto de parâmetros de saída. Estes parâmetros não só fornecem informações sobre o resultado da operação, mas também disponibilizam os dados processados em vários formatos para as Tarefas subsequentes.

• result: Fornece o estado geral da execução da Tarefa (ex: "Success" ou uma mensagem de erro).
• resultJson: Representa o resultado da execução da tarefa em formato JSON, incluindo informações gerais, configurações e detalhes da execução.
• targetTable: Retorna o nome da tabela do banco de dados onde os dados foram inseridos.
• rowCount: Indica o número total de linhas que foram inseridas na tabela de destino.
• DataExportCsv: Retorna o conjunto completo de dados processados, formatado como texto em formato CSV (Comma-Separated Values).
• DataExportJson: Retorna o conjunto completo de dados processados, formatado como uma string JSON.
• Dataset: Este parâmetro representa o nome da coluna da tabela (Ex: name). É o parâmetro mais importante para ligar esta Tarefa a um Iterador. Para aceder aos valores de uma coluna específica durante uma iteração, utiliza-se a sintaxe Dataset.NomeColuna.
• DataColumn: Este parâmetro permite aceder a todo o conteúdo de uma coluna como uma única entidade (por exemplo, um array ou uma lista).
• DataColumn.NomeColuna: Retorna todos os valores da coluna “NomeColuna”. Ex: “Luca, Maria, Giovanni, Elena”

6. Exemplo de parâmetro resultJson

{
  "run_info": {
    "status": "Completed",
    "run_result": "Success"
  },
  "output_parameters": {
    "exitStatus": "0"
  }
}