DataWorks：HDFS資料來源

參數

描述

是否必選

預設值

path

要讀取的檔案路徑，如果要讀取多個檔案，可以使用簡單Regex匹配，例如/hadoop/data_201704*，如果檔案以時間命名且較為規律，則可以結合調度參數使用，調度參數將根據業務時間動態替換，詳情請參見調度參數支援的格式：

• 當指定單個HDFS檔案時，HDFS Reader暫時只能使用單線程進行資料幫浦。

• 當指定多個HDFS檔案時，HDFS Reader支援使用多線程進行資料幫浦，線程並發數通過作業並發數concurrent指定。

  說明

  實際啟動的並發數是您的HDFS待讀取檔案數量和您配置作業並發數兩者中的小者。

• 當指定萬用字元，HDFS Reader嘗試遍曆出多個檔案資訊。例如指定/代表讀取/目錄下所有的檔案，指定/bazhen/代表讀取bazhen目錄下遊所有的檔案。HDFS Reader目前只支援*和?作為檔案萬用字元，文法類似於通常的Linux命令列檔案萬用字元。

請注意以下事項：

• Data Integration會將一個同步作業所有待讀取檔案視作同一張資料表。您必須自己保證所有的File能夠適配同一套schema資訊，並且提供給Data Integration許可權可讀。

• 注意分區讀取：Hive在建表時，可以指定分區。例如建立分區partition(day="20150820", hour="09")，對應的HDFS檔案系統中，相應的表的目錄下則會多出/20150820和/09兩個目錄且/20150820是/09的父目錄。

  分區會列成相應的目錄結構，在按照某個分區讀取某個表所有資料時，則只需配置好JSON中path的值即可。例如需要讀取表名叫mytable01下分區day為20150820這一天的所有資料，則配置如下。

  "path": "/user/hive/warehouse/mytable01/20150820/*"

是

無

defaultFS

Hadoop HDFS檔案系統namenode節點地址。公用資源群組不支援Hadoop進階參數HA的配置。

是

無

fileType

檔案的類型，目前僅支援您配置為TEXT、ORC、RC、SEQ、CSV和parquet。HDFS Reader能夠自動識別檔案的類型，並使用對應檔案類型的讀取策略。HDFS Reader在做資料同步前，會檢查您配置的路徑下所有需要同步的檔案格式是否和fileType一致，如果不一致任務會失敗。

fileType可以配置的參數值列表如下所示：

• TEXT：表示TextFile檔案格式。

• ORC：表示ORCFile檔案格式。

• RC：表示RCFile檔案格式。

• SEQ：表示SequenceFile檔案格式。

• CSV：表示普通HDFS檔案格式（邏輯二維表）。

• PARQUET：表示普通Parquet檔案格式。

由於TextFile和ORCFile是兩種不同的檔案格式，所以HDFS Reader對這兩種檔案的解析方式也存在差異，這種差異導致Hive支援的複雜複合類型（例如map、array、struct和union）在轉換為Data Integration支援的String類型時，轉換的結果格式略有差異，以map類型為例：

• ORCFile map類型經HDFS Reader解析，轉換成Data Integration支援的STRING類型後，結果為{job=80, team=60, person=70}。

• TextFile map類型經HDFS Reader解析，轉換成Data Integration支援的STRING類型後，結果為{job:80, team:60, person:70}。

如上述轉換結果所示，資料本身沒有變化，但是表示的格式略有差異。所以如果您配置的檔案路徑中要同步的欄位在Hive中是複合類型的話，建議配置統一的檔案格式 。

最佳實務建議：

• 如果需要統一複合類型解析出來的格式，建議您在Hive用戶端將TextFile格式的表導成ORCFile格式的表。

• 如果是Parquet檔案格式，後面的parquetSchema則必填，此屬性用來說明要讀取的Parquet格式檔案的格式。

對於您指定的column資訊，type必須填寫，index和value必須選擇其一。

是

無

column

讀取欄位列表，type指定來源資料的類型，index指定當前列來自於文本第幾列（以0開始），value指定當前類型為常量。不從源標頭檔讀取資料，而是根據value值自動產生對應的列。預設情況下，您可以全部按照STRING類型讀取資料，配置為"column": ["*"]。

您也可以指定column欄位資訊（檔案資料列和常量列配置二選一），配置如下。

{
  "type": "long",
  "index": 0
  //從本地檔案文本第一列（下標索引從0開始計數）擷取INT欄位，index表示從資料檔案中擷取列資料。
},
{
  "type": "string",
  "value": "alibaba"
  //HDFS Reader內部產生alibaba的字串欄位作為當前欄位，value表示常量列。
}

是

無

fieldDelimiter

讀取的欄位分隔符號，HDFS Reader在讀取TextFile資料時，需要指定欄位分割符，如果不指定預設為逗號（,）。HDFS Reader在讀取ORCFile時，您無需指定欄位分割符，Hive本身的預設分隔符號為\u0001。

否

,

encoding

讀取檔案的編碼配置。

否

utf-8

nullFormat

文字檔中無法使用標準字串定義null（null 指標），Data Integration提供nullFormat定義哪些字串可以表示為null。

例如您配置nullFormat:"null"，如果源頭資料是null，Data Integration會將其視作null欄位。

否

無

compress

當fileType（檔案類型）為csv下的檔案壓縮方式，目前僅支援gzip、bz2、zip、lzo、lzo_deflate、hadoop-snappy和framing-snappy壓縮。

否

無

parquetSchema

否

無

csvReaderConfig

讀取CSV類型檔案參數配置，Map類型。讀取CSV類型檔案使用的CsvReader進行讀取，會有很多配置，不配置則使用預設值。

常見配置如下所示。

"csvReaderConfig":{
  "safetySwitch": false,
  "skipEmptyRecords": false,
  "useTextQualifier": false
}

所有配置項及預設值，配置時csvReaderConfig的map中請嚴格按照以下欄位名字進行配置。

boolean caseSensitive = true;
char textQualifier = 34;
boolean trimWhitespace = true;
boolean useTextQualifier = true;//是否使用csv逸出字元。
char delimiter = 44;//分隔字元
char recordDelimiter = 0;
char comment = 35;
boolean useComments = false;
int escapeMode = 1;
boolean safetySwitch = true;//單列長度是否限制100,000字元。
boolean skipEmptyRecords = true;//是否跳過空行。
boolean captureRawRecord = true;

否

無

hadoopConfig

hadoopConfig中可以配置與Hadoop相關的一些進階參數，例如HA的配置。公用資源群組不支援Hadoop進階參數HA的配置。

"hadoopConfig":{
"dfs.nameservices": "testDfs",
"dfs.ha.namenodes.testDfs": "namenode1,namenode2",
"dfs.namenode.rpc-address.youkuDfs.namenode1": "",
"dfs.namenode.rpc-address.youkuDfs.namenode2": "",
"dfs.client.failover.proxy.provider.testDfs": "org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider",
"dfs.data.transfer.protection": "integrity",
"dfs.datanode.use.datanode.hostname" :"true",
"dfs.client.use.datanode.hostname":"true"
}

"hadoopConfig":{ "dfs.data.transfer.protection": "integrity", "dfs.datanode.use.datanode.hostname" :"true", "dfs.client.use.datanode.hostname":"true" }

否

無

haveKerberos

是否有Kerberos認證，預設為false。例如使用者配置為true，則配置項kerberosKeytabFilePath和kerberosPrincipal為必填。

否

false

kerberosKeytabFilePath

Kerberos認證keytab檔案的絕對路徑。如果haveKerberos為true，則必選。

否

無

kerberosPrincipal

Kerberos認證Principal名，如****/hadoopclient@**.*** 。如果haveKerberos為true，則必選。

"haveKerberos":true,
"kerberosKeytabFilePath":"/opt/datax/**.keytab",
"kerberosPrincipal":"**/hadoopclient@**.**"

否

無

參數

描述

是否必選

預設值

defaultFS

Hadoop HDFS檔案系統namenode節點地址，例如hdfs://127.0.0.1:9000。

是

無

fileType

檔案的類型，目前僅支援您配置為text、orc和parquet：

• text：表示Hive中的儲存表，TextFile檔案格式。

• orc：表示Hive中的壓縮表，ORCFile檔案格式。

• parquet：表示普通Parquet File檔案格式。

是

無

path

儲存到Hadoop HDFS檔案系統的路徑資訊，HDFS Writer會根據並發配置在path目錄下寫入多個檔案。

為了與Hive表關聯，請填寫Hive表在HDFS上的儲存路徑。例如Hive上設定的資料倉儲的儲存路徑為/user/hive/warehouse/，已建立資料庫test表hello，則對應的儲存路徑為/user/hive/warehouse/test.db/hello。

是

無

fileName

HDFS Writer寫入時的檔案名稱，實際執行時會在該檔案名稱後添加隨機的尾碼作為每個線程寫入實際檔案名稱。

是

無

column

寫入資料的欄位，不支援對部分列寫入。

為了與Hive中的表關聯，需要指定表中所有欄位名和欄位類型，其中name指定欄位名，type指定欄位類型。

您可以指定column欄位資訊，配置如下。

"column": 
[
    {
        "name": "userName",
        "type": "string"
    },
    {
        "name": "age",
        "type": "long"
    }
]

是（如果filetype為parquet，此項無需填寫）

無

writeMode

HDFS Writer寫入前資料清理處理模式：

• append：寫入前不做任何處理，Data IntegrationHDFS Writer直接使用filename寫入，並保證檔案名稱不衝突。

• nonConflict：如果目錄下有fileName首碼的檔案，直接報錯。

• truncate：寫入前清理fileName名稱首碼匹配的所有檔案。例如，"fileName": "abc"，將清理對應目錄所有abc開頭的檔案。

是

無

fieldDelimiter

HDFS Writer寫入時的欄位分隔符號，需要您保證與建立的Hive表的欄位分隔符號一致，否則無法在Hive表中查到資料。

是（如果filetype為parquet，此項無需填寫）

無

compress

HDFS檔案壓縮類型，預設不填寫，則表示沒有壓縮。

其中text類型檔案支援gzip和bzip2壓縮類型。

否

無

encoding

寫檔案的編碼配置。

否

無壓縮

parquetSchema

寫Parquet格式檔案時的必填項，用來描述目標檔案的結構，所以此項若且唯若fileType為parquet時生效，格式如下。

message MessageType名 {
是否必填, 資料類型, 列名;
......................;
}

配置項說明如下：

• MessageType名：填寫名稱。

• 是否必填：required表示非空，optional表示可為空白。推薦全填optional。

• 資料類型：Parquet檔案支援BOOLEAN、INT32、INT64、INT96、FLOAT、DOUBLE、BINARY（如果是字串類型，請填BINARY）和FIXED_LEN_BYTE_ARRAY等類型。

樣本如下。

message m {
optional int64 id;
optional int64 date_id;
optional binary datetimestring;
optional int32 dspId;
optional int32 advertiserId;
optional int32 status;
optional int64 bidding_req_num;
optional int64 imp;
optional int64 click_num;
}

否

無

hadoopConfig

hadoopConfig中可以配置與Hadoop相關的一些進階參數，例如HA的配置。

"hadoopConfig":{
"dfs.nameservices": "testDfs",
"dfs.ha.namenodes.testDfs": "namenode1,namenode2",
"dfs.namenode.rpc-address.youkuDfs.namenode1": "",
"dfs.namenode.rpc-address.youkuDfs.namenode2": "",
"dfs.client.failover.proxy.provider.testDfs": "org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider"
}

否

無

dataxParquetMode

針對Parquet檔案進行同步的模式。使用fields支援array、map和struct等複雜類型。可選值包括fields和columns。

配置dataxParquetMode為fields時，支援hdfs over oss，即HDFS的儲存為OSS，OSS的資料存放區格式為parquet。此時您可以在hadoopConfig中增加OSS相關的參數，詳情如下：

• fs.oss.accessKeyId：訪問OSS的AccessKeyID。

• fs.oss.accessKeySecret：訪問OSS的AccessKeySecret。

• fs.oss.endpoint：訪問OSS的endpoint。

訪問OSS的樣本如下所示。

```json
    "writer": {
    "name": "hdfswriter",
    "parameter": {
        "defaultFS": "oss://test-bucket",
        "fileType": "parquet",
        "path": "/datasets/oss_demo/kpt",
        "fileName": "test",
        "writeMode": "truncate",
        "encoding": "UTF-8",
        "hadoopConfig": {
            "fs.oss.accessKeyId": "the-access-id",
            "fs.oss.accessKeySecret": "the-access-key",
            "fs.oss.endpoint": "oss-cn-hangzhou.aliyuncs.com"
            },
            "parquetSchema": "message test {\n    required int64 id;\n    optional binary name (UTF8);\n    optional int64 gmt_create;\n    required group map_col (MAP) {\n        repeated group key_value {\n            required binary key (UTF8);\n            required binary value (UTF8);\n        }\n    }\n    required group array_col (LIST) {\n        repeated group list {\n            required binary element (UTF8);\n        }\n    }\n    required group struct_col {\n        required int64 id;\n        required binary name (UTF8);\n    }    \n}",
            "dataxParquetMode": "fields"
            }
        }
    ```

否

columns

haveKerberos

是否有Kerberos認證，預設為false。如果您配置為true，則配置項kerberosKeytabFilePath和kerberosPrincipal為必填。

否

false

kerberosKeytabFilePath

Kerberos認證keytab檔案的絕對路徑。

如果haveKerberos為true，則必選。

無

kerberosPrincipal

Kerberos認證Principal名，如****/hadoopclient@**.*** 。如果haveKerberos為true，則必選。

由於Kerberos需要配置keytab認證檔案的絕對路徑，您需要在自訂資源群組上使用此功能。配置樣本如下。

"haveKerberos":true,
"kerberosKeytabFilePath":"/opt/datax/**.keytab",
"kerberosPrincipal":"**/hadoopclient@**.**"

否

無