Skip to main content

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.

Configurações disponíveis

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)
},
...
]
CampoDescrição
pipeline_namestring
Um nome definido pelo usuário para o pipeline. Os nomes dos pipelines devem ser únicos para esta configuração.
formatenum Format
Descreve o formato dos dados sendo carregados.
urlstring
URL do arquivo ou endpoint onde residem os dados que serão carregados.
headersmap (key: string, value: string)
Cabeçalhos HTTP personalizados que serão enviados na requisição da URL. Exemplos:
"Authorization": "cf365fe19f224be09499af3f65aedebb"
"X-Api-Key": "449703493e2f41318585856d8c1a52ff"
authobject Auth
Configurações específicas da autenticação utilizada na requisição da URL.
carolobject Carol
Configurações específicas do conector Carol.
csvobject Csv
Configurações específicas para dados no formato CSV.
xlsxobject Xlsx
Configurações específicas para dados no formato XLSX.
jsonobject Json
Configurações específicas para dados no formato JSON.
parquetobject 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.

ValorDescrição
csvArquivo texto em formato estruturado de tabela, com colunas separadas por separador, normalmente , ou ;.
xlsxArquivo no formato Microsoft Excel Open XML Spreadsheet, armazena os dados em estrutura tabular, organizados em planilhas.
jsonArquivo texto de padrão aberto, armazena dados em pares atributo-valor e arrays.
parquetParquet é 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
}
}
CampoDescrição
typeenum AuthType
Descreve o tipo de autenticação utilizado no pipeline.
usernamestring
Identificação do usuário utilizado na autenticação. Somente Basic.
passwordstring
Senha utilizada na autenticação. Somente Basic.
token_urlstring
URL do serviço de autorização utilizado para geração de token de acesso. Bearer e OAuth2. Ver
cliente_idstring
Identificador público para o aplicativo no fluxo de autenticação OAuth2. Bearer e OAuth2. Ver
cliente_secretstring
Segredo compartilhado entre o aplicativo e Authorization Server durante o fluxo de autenticação OAuth2. Bearer e OAuth2. Ver
refresh_tokenstring
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_uristring
URL cadastrada no aplicativo OAuth2 como retorno após autenticação. Somente OAuth2. Ver
service_account_keystring
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.

ValorDescrição
basicInformações de autenticação (usuário e senha) são codificadas como Base64 no cabeçalho Authorization.
bearerCredenciais 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.
oauth2Credenciais 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
gcpUtilizando a chave de uma conta de serviço para Google Cloud.

Carol

Representação JSON
{
"connector": string,
"staging": string,
"crosswalk": [
string,
...
],
"flexible": boolean
}
CampoDescrição
connectorstring
Nome do conector que possui a tabela de destino para a carga de dados.
stagingstring
Nome da tabela de staging onde os dados serão armazenados na plataforma.
crosswalkstring[]
Colunas que serão usadas como chave primária da tabela.
flexibleboolean
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
}
CampoDescrição
delimiterstring
Delimitador de colunas usado no arquivo CSV.
headerboolean
Indica se o arquivo CSV contém uma linha com os cabeçalhos ou não.
columnsstring[]
Define o nome das colunas do arquivo CSV que não possui cabeçalhos.
ignore_schemaboolean
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,
...
]
}
CampoDescrição
sheetstring
Nome da planilha que contém os dados a serem utilizados.
headerboolean
Indica se o arquivo XLSX contém uma linha com os cabeçalhos ou não.
columnsstring[]
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,
...
]
}
CampoDescrição
rootstring
Notação JSON que representa o array de dados a serem carregados. Exemplos:
"root": ""
"root": "hits"
"root": "meta.view.columns"
propertiesstring[]
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
}
CampoDescrição
columnsstring[]
Seleciona o nome das colunas do arquivo PARQUET que devem ser carregados, podendo ser omitido para carregar todas as colunas.
ignore_schemaboolean
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