Carol File Loader

Este aplicativo para carregamento de dados estruturados na plataforma Carol é uma ferramenta que permite aos usuários o download e carga de dados nos formatos CSV, XLSX, JSON e API (em breve), utilizando os protocolos HTTP, HTTPS e FTP (em breve). Além disso, o aplicativo suporta os padrões de autenticação Basic, Bearer e OAuth2, o que garante a segurança e privacidade dos dados utilizados. A ferramenta suporta a configuração de diversas fontes de dados e a carga agendada ou manual de maneira escalável.

Siga os links abaixo para instruções detalhadas sobre o uso do app:

→ Instalação

→ Configuração

→ Agendamento

---

Instalação

Para instalar o app é necessário que o mesmo esteja disponível para a organização a que pertence à Tenant.

→ Instalando o Carol App nas Tenants

---

Configuração

Pipeline

Utilizando a configuração CONFIG_JSON, a aplicação suporta a definição de múltiplos pipelines de carga de dados.

Representação JSON

[
  "pipeline_name": {
      "format": enum (Format),
      "url": string,
      "headers": {
          string: string,
          ...
      },
      "auth": {
          object (Auth)
      },
      "carol": {
          object (Carol)
      },
      "csv": {
          object (Csv)
      },
      "json": {
          object (Json)
      },
      "parquet": {
          object (Parquet)
      }
  },
  {
    object (Pipeline)
  },
  ...
]

Campo	Descrição
pipeline_name	string Um nome definido pelo usuário para o pipeline. Os nomes dos pipelines devem ser únicos para esta configuração.
format	enum Format Descreve o formato dos dados sendo carregados.
url	string URL do arquivo ou endpoint onde residem os dados que serão carregados.
headers	map (key: string, value: string) Cabeçalhos HTTP personalizados que serão enviados na requisição da URL. Exemplos: "Authorization": "cf365fe19f224be09499af3f65aedebb" "X-Api-Key": "449703493e2f41318585856d8c1a52ff"
auth	object Auth Configurações específicas da autenticação utilizada na requisição da URL.
carol	object Carol Configurações específicas do conector Carol.
csv	object Csv Configurações específicas para dados no formato CSV.
xlsx	object Xlsx Configurações específicas para dados no formato XLSX.
json	object Json Configurações específicas para dados no formato JSON.
parquet	object Parquet Configurações específicas para dados utilizando PARQUET.

Exemplo Pipelines

[
  {
    "pipeline_name_1": {
        "url": "https://raw.githubusercontent.com/jpatokal/openflights/master/data/airports.dat",
        "format": "csv",
        "carol": {
          ...
        },
        "csv": {
          ...
        }
    }
  },
  {
    "pipeline_name_2": {
        "url": "https://data.wa.gov/api/views/f6w7-q2d2/rows.json?accessType=DOWNLOAD",
        "headers": {
            "Content-Type": "application/json",
            "X-Custom-Header": "foobar"
        },
        "format": "json",
        "carol": {
          ...
        },
        "json": {
          ...
        }
    }
  },
  {
    "pipeline_name_3": {
        "url": "https://drive.google.com/uc?export=download&id=1XUBPHPuqV9JqzVDiFeuxXDVs1234",
        "format": "xlsx",
        "carol": {
          ...
        },
        "xlsx": {
          ...
        }
    }
  },
  {
    "pipeline_name_4": {
        "url": "gs://bucket-name-gcp/airports.parquet",
        "format": "parquet",
        "auth": {
            "type": "gcp",
            "config": {
               ...
            }
        },
        "carol": {
           ...
        },
        "parquet": {
           ...
        }
    }
  }
]

Format

Formatos suportados pela aplicação.

Valor	Descrição
csv	Arquivo texto em formato estruturado de tabela, com colunas separadas por separador, normalmente , ou ;.
xlsx	Arquivo no formato Microsoft Excel Open XML Spreadsheet, armazena os dados em estrutura tabular, organizados em planilhas.
json	Arquivo texto de padrão aberto, armazena dados em pares atributo-valor e arrays.
parquet	Parquet é um formato de arquivo em coluna com otimizações para acelerar as consultas.

Auth

Representação JSON

{
    "type": enum (AuthType),
    "config": {
        "username": string,
        "password": string,
        "token_url": string,
        "client_id": string,
        "client_secret": string,
        "refresh_token": string,
        "redirect_uri": string,
        "service_account_key": string
    }
}

Campo	Descrição
type	enum AuthType Descreve o tipo de autenticação utilizado no pipeline.
username	string Identificação do usuário utilizado na autenticação. Somente Basic.
password	string Senha utilizada na autenticação. Somente Basic.
token_url	string URL do serviço de autorização utilizado para geração de token de acesso. Bearer e OAuth2. Ver
cliente_id	string Identificador público para o aplicativo no fluxo de autenticação OAuth2. Bearer e OAuth2. Ver
cliente_secret	string Segredo compartilhado entre o aplicativo e Authorization Server durante o fluxo de autenticação OAuth2. Bearer e OAuth2. Ver
refresh_token	string Inicialmente recebido juntamente com o token de acesso durante o fluxo de autenticação OAuth2, permite a obtenção não interativa de um novo token de acesso após sua expiração. Somente OAuth2. Ver
redirect_uri	string URL cadastrada no aplicativo OAuth2 como retorno após autenticação. Somente OAuth2. Ver
service_account_key	string Representação Base64 do conteúdo do JSON de chave para a conta de serviço utilizada na autenticação com Google Cloud. Somente GCP.

Exemplo OAuth2

"auth": {
    "type": "oauth2",
    "config": {
        "token_url": "https://oauth2.googleapis.com/token",
        "client_id": "1234931896063-664elpmh56lnjp1egp897l8cgf5r5r2l.apps.googleusercontent.com",
        "client_secret": "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",
        "refresh_token": "1//04e-1hR3F96BmCgYIARAAGAQSNwF-L9Ir2HYVflNTNx6kVIm8cjGkRnnPY4F7ix8PQbN0AuQPjtC35RDVmnEQHYoySyRrfaL1234",
        "redirect_uri": "https://totvslabs.carol.ai/toolbox/apps/dev/carolfileloader/1.0.11/index.html"
    }
}

Exemplo GCP

"auth": {
    "type": "gcp",
    "config": {
        "service_account_key": "ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAicHJvamVjdC1uYW1lIiwKICAicHJpdmF0ZV9rZXlfaWQiOiAiNWI5MjI0Y2Q2YTdhY2YzIiwKICAicHJpdmF0ZV9rZXkiOiAiLS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tXG5cbi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS1cbiIsCiAgImNsaWVudF9lbWFpbCI6ICJzZXJ2aWNlLWFjY291bnRAaWFtLmdzZXJ2aWNlYWNjb3VudC5jb20iLAogICJjbGllbnRfaWQiOiAiMTE2MjMyNTA1MzIxIiwKICAiYXV0aF91cmkiOiAiaHR0cHM6Ly9hY2NvdW50cy5nb29nbGUuY29tL28vb2F1dGgyL2F1dGgiLAogICJ0b2tlbl91cmkiOiAiaHR0cHM6Ly9vYXV0aDIuZ29vZ2xlYXBpcy5jb20vdG9rZW4iLAogICJhdXRoX3Byb3ZpZGVyX3g1MDlfY2VydF91cmwiOiAiaHR0cHM6Ly93d3cuZ29vZ2xlYXBpcy5jb20vb2F1dGgyL3YxL2NlcnRzIiwKICAiY2xpZW50X3g1MDlfY2VydF91cmwiOiAiaHR0cHM6Ly93d3cuZ29vZ2xlYXBpcy5jb20vcm9ib3QvdjEvbWV0YWRhdGEveDUwOS9zZXJ2aWNlLWFjY291bnQlNDBpYW0uZ3NlcnZpY2VhY2NvdW50LmNvbSIKfQo="
    }
}

AuthType

Tipos de autenticação suportados pela aplicação.

Valor	Descrição
basic	Informações de autenticação (usuário e senha) são codificadas como Base64 no cabeçalho Authorization.
bearer	Credenciais de autenticação (ID e Secret) são utilizadas para obtenção de token de acesso em um Authorization Server. A requisição ao recurso definido em URL utiliza o token recebido no cabeçalho Authorization.
oauth2	Credenciais de autenticação (ID e Secret) são utilizadas em conjunto com o refresh_token para obtenção de token de acesso em um Authorization Server. Atualmente somente o fluxo de authenticação de aplicativo Web é suportado. A requisição ao recurso definido em URL utiliza o token recebido no cabeçalho Authorization
gcp	Utilizando a chave de uma conta de serviço para Google Cloud.

Carol

Representação JSON

{
    "connector": string,
    "staging": string,
    "crosswalk": [
        string,
        ...
    ],
    "flexible": boolean
}

Campo	Descrição
connector	string Nome do conector que possui a tabela de destino para a carga de dados.
staging	string Nome da tabela de staging onde os dados serão armazenados na plataforma.
crosswalk	string[] Colunas que serão usadas como chave primária da tabela.
flexible	boolean Indica se colunas adicionais serão ignoradas ou não.

Exemplo Carol

"carol": {
    "connector": "openflights",
    "staging": "sample",
    "crosswalk": ["id", "iata"],
    "flexible": true
}

Csv

Representação JSON

{
    "delimiter": string,
    "header": boolean,
    "columns": [
        string,
        ...
    ],
    "ignore_schema": true
}

Campo	Descrição
delimiter	string Delimitador de colunas usado no arquivo CSV.
header	boolean Indica se o arquivo CSV contém uma linha com os cabeçalhos ou não.
columns	string[] Define o nome das colunas do arquivo CSV que não possui cabeçalhos.
ignore_schema	boolean Desabilita a inferência de tipos a partir do schema original considerando todos as colunas como string. Valor padrão: false.

Exemplo CSV

"csv": {
    "delimiter": ",",
    "header": false,
    "columns": [
        "id",
        "name",
        "city",
        "country",
        "iata",
        "icao",
        "latitude",
        "longitude",
        "altitude",
        "timezone",
        "dst",
        "tz",
        "type",
        "source"
    ],
    "ignore_schema": true
}

Xlsx

Representação JSON

{
    "sheet": string,
    "header": boolean,
    "columns": [
        string,
        ...
    ]
}

Campo	Descrição
sheet	string Nome da planilha que contém os dados a serem utilizados.
header	boolean Indica se o arquivo XLSX contém uma linha com os cabeçalhos ou não.
columns	string[] Define o nome das colunas do arquivo XLSX que não possui cabeçalhos.

Exemplo Xlsx

"xlsx": {
    "sheet": "Plan1",
    "header": true
}

Json

Representação JSON

{
    "root": string,
    "properties": [
        string,
        ...
    ]
}

Campo	Descrição
root	string Notação JSON que representa o array de dados a serem carregados. Exemplos: "root": "" "root": "hits" "root": "meta.view.columns"
properties	string[] Lista de campos em notação JSON que devem ser consideradas durante a carga de dados. Este campo deve ser suprimido para que todos os dados sejam utilizados.

Exemplo JSON

"json": {
    "root": "meta.view.columns",
    "properties": [
        "id",
        "name",
        "dataTypeName",
        "fieldName",
        "position",
        "renderTypeName",
        "format",
        "format.align"
    ]
}

Parquet

Representação JSON

{
    "columns": [
        string,
        ...
    ],
    "ignore_schema": true
}

Campo	Descrição
columns	string[] Seleciona o nome das colunas do arquivo PARQUET que devem ser carregados, podendo ser omitido para carregar todas as colunas.
ignore_schema	boolean Desabilita a inferência de tipos a partir do schema original considerando todos as colunas como string. Valor padrão: false.

Exemplo PARQUET

"parquet": {
    "ignore_schema": true
}

---

Agendamento

Em construção