檔案輸入功能說明

1.1 版本說明

1.2 應用場景

使用者在搭建數倉時，希望能從 FineDataLink 伺服器本地或者共享目錄中讀取 Excel 、CSV 檔案資料。

同時可以透過 FDL 將 Excel 、CSV 檔案直接上傳至 FDL 伺服器本地。

1.3 功能簡介

FineDataLink 支援「檔案輸入」功能，可讀取檔案資料。如下圖所示：

注：透過分配資料連結權限控制每個人允許存取的 本地伺服器目錄，保證資料與權限安全。

• 若需要讀取或者上傳本地的 Excel 和 CSV 檔案資料至 FineDataLink，需要建立一個「伺服器本地目錄」資料連結，並將要讀取的檔案放到%FDL%/webroot/WEB-INF/assets/local_files路徑下，並且有該資料連結的使用權限。具體請參見：配置伺服器本地目錄資料連結

• 若需要讀取遠端 FTP/SFTP 伺服器 Excel 和 CSV 檔案資料，需要配置 FTP/SFTP資料連結，並且有該資料連結的使用權限。具體請參見：配置FTP/SFTP資料連結

• 4.0.24 版本之前，僅支援上傳後綴小寫 Excel 和 CSV 檔案，對於大寫後綴的 Excel 和 CSV 檔案上傳校驗不透過。若檔案存在，但無法讀取，請檢查檔案後綴是否為大寫 .CSV/.XLSX，請手動修改為小寫。

1）「檔案輸入」算子前端日誌顯示的讀取量，不包含表頭這行資料。

比如 Excel 資料有 100 w行，包括 1 行表頭+999999行資料，「檔案輸入」算子讀取後，前端日誌會顯示讀取 999999 行資料。

2）「檔案輸入」算子中，檔案地址、資料夾地址、檔案篩選、Sheet名設定項中支援使用參數，參數使用方法請參見：如何配置並使用參數；「檔案輸入算子+參數」的具體使用範例請參見本文第七章內容。

3.1 讀取 Excel 檔案

3.1.1 檔案來源

需要提前配置「伺服器本地資料連結」或「FTP/SFTP資料連結」且需要有該資料連結的使用權限，下拉框中才會出現選項。

3.1.2 檔案類型

檔案類型選擇「Excel」時：

• 支援的 Excel 檔案後綴名：.xls、.xlsx、.XLS、.XLSX

• Excel 需要支援滿足的版本為 97~ 最新版本

3.1.3 讀取方式

分為兩種，「檔案讀取」和「資料夾讀取」。

1）檔案讀取

• 讀取單個檔案。

• 檔案地址：選擇要讀取的檔案；支援輸入參數；若檔案來源是「伺服器本地目錄」，此處填寫的是相對於%FDL%/webroot/WEB-INF/assets/local_files的路徑，例如：/home/ftpuser/test/${time}.xlsx（/home 在 %FDL%/webroot/WEB-INF/assets/local_files路徑下）。

注：在「檔案地址」中，貼上完整檔案地址或者手動輸入檔案地址後，按 Enter 鍵儲存。

• 檔案來源為「伺服器本地目錄」且讀取單個檔案時，「檔案地址」處支援手動上傳檔案至有權限的 FDL 伺服器本地目錄中。上傳檔案名稱限制：上傳檔案名稱不能包含「 ? * : " < > \ / | 」，不能以空格開頭。上傳檔案大小不能超過 100M 。

2）資料夾讀取

可讀取資料夾中的多個同格式檔案，將檔案資料合併在一起。資料夾中的 Excel 檔案需要欄位名相同；資料夾中的 CSV 檔案需要分隔符相同。

注1：若需要讀取的資料夾中包含多種格式資料，且僅需要讀取一種檔案類型，則在讀取的時候需要進行檔案篩選，篩選檔案名稱中包含 CSV 或者 Excel 的指定檔案，否則會預設讀取資料夾中的所有類型的檔案。

注2：檔案輸入算子中讀取資料夾中的檔案時，是併發讀取的，最多併發讀取 20 個檔案。

例如資料夾下有兩個檔案 test1 和 test2 ，若選擇「資料夾讀取」則會將檔案資料合併在一起，如下圖所示：

詳細範例詳情參見：批量扫描文件同步数据

3.1.4 sheet 名

填寫要讀取的 Sheet 名。為空時讀取第一個 sheet。sheet 名稱支援使用參數。

3.1.5 讀取行列範圍

指定 Excel 讀取起始行和讀取結束行，指定 Excel 讀取起始列和讀取結束列。

數字框中要求為正整數。

3.1.6 首行為欄位名

勾選時，將解析到的首行資料作為欄位名。

不勾選時，首行將作為實際資料解析。

3.1.7 匯出欄位

1）有兩種獲取方式，說明見下表：

2）4.2.6.1 及之後版本，兩種方式均支援新增三個內建欄位「fileName（檔案名稱）」、「filePath（檔案路徑）」、「lastModifiedTime（檔案修改時間）」，在配置中可新增三個內建欄位作為匯出欄位。

注：支援修改內建欄位的欄位名，限制 30 字元，不能與其他有效欄位重名。

當配置了內建欄位後，資料預覽和實際運作時都會新增該列內容。預覽效果如下： 

3）若 FTP 獲取檔案以及資料夾的時間（lastModifiedTime）比實際伺服器上的時間晚 8 h 或時間錯誤等情況，需要修改配置檔案，此操作會影響資料夾條件中的時間過濾。

修改 /etc/vsftpd/vsftpd.conf 配置檔案，在最下面一行增加：

use_localtime=YES

重啟 FTP

service vsftpd restart

3.2 讀取 CSV 檔案

若檔案類型選擇「CSV」檔案，需配置以下內容：

檔案來源、讀取方式、首行為欄位名、匯出欄位介紹請參見本文 3.1 節內容，其餘設定項說明見下表：

3.3 自訂

支援讀取 xml、json 等檔案類型。

預設獲取為正文資料，一個檔案一行資料，列名預設為「column」，解析內容功能由後續XML解析、JSON解析等算子實現。如下圖所示：

檔案來源、讀取方式、檔案地址請參見本文 3.1 節。

3.3.1 讀取檔案後綴

讀取方式選擇「檔案讀取」時，新增該選項：

• 不區分大小寫。

• 支援寫多種格式，以逗號為分隔符。

• 檔案後綴不能重複。

3.3.2 編碼

編碼可選擇 GBK、BIG5、ISO-8859-1、UTF-8、UTF-16、EUC_JP、EUC_KR、CP850、GB2312。如下圖所示：

3.3 資料預覽

「資料預覽」介面如下圖所示：

說明如下：

• 預覽資料量預設最多20行；使用前5000行資料中出現的欄位與首行列數（如果指定了首行為欄位名稱）取並集，作為預覽時展示的欄位，且僅取數取樣前5000筆資料，但請不要擔心，在匯出資料時為全量匯出。

• 如果首行欄位為合併儲存格的情況，將合併儲存格進行拆分後，以「欄位名稱+數字」的方式對拆分後的欄位命名，如三個儲存格合併後的首行儲存格為「姓名」，則命名為姓名、姓名1、姓名2..:

• 如果CSV首行欄位有重名情況，以「欄位名稱+數字」的方式對重複欄位命名，如重複欄位為姓名，則重複欄位命名為姓名1、姓名2...。

• 未勾選首行包含欄位名時，欄位名稱以「column+數字」的方式對解析出的欄位依次命名，如column、column1、column2...。

FDL 工程的定時任務中使用了「檔案輸入」算子，其中檔案類型選擇 CSV，讀取方式為資料夾讀取：

• 若設定了檔案篩選條件，升級到 4.1.4 及之後版本後，filename 包含.txt、.TXT、.csv、.CSV，與升級前配置的篩選條件為且關係。

• 若沒有設定檔案篩選條件，升級到 4.1.4 及之後版本後，filename 預設包含.txt、.TXT、.csv、.CSV。

儲存格格式與讀取後欄位的關係說明：

1）CSV欄位類型問題

CSV讀取後，匯出只有字串和數字兩種類型，數字需要保證不丟精度。對於時間類型，如2022-11-10類型的時間，解析為字串；時間戳類型的時間解析成數字。

2）合併儲存格讀取問題

對於合併的儲存格，拆分儲存格讀取，複製值到每個拆分後的儲存格進行讀取。

3）欄位為空的情況

如果標題欄位存在空值，則將空值以「column+數字」的方式補充。

如果數字欄位存在空值，填NULL

4）不支援 Excel 的多選Sheet讀取。

5）不支援檔案名稱通配符。

6）不支援讀取設密碼的Excel檔案。