OSS-HDFS資料來源 - DataWorks

OSS-HDFS服務（JindoFS服務）是一款雲原生資料湖儲存產品，OSS-HDFS資料來源為您提供讀取和寫入OSS-HDFS的雙向通道，本文為您介紹DataWorks的OSS-HDFS資料同步的能力支援情況。

使用限制

離線讀

使用OSS-HDFS Reader時，請注意以下事項：
由於連通資源群組到OSS-HDFS的網路鏈路比較複雜，建議您使用Serverless資源群組（推薦）和獨享Data Integration資源群組完成資料同步任務。您需要確保您的資源群組具備OSS-HDFS的網路訪問能力。
OSS-HDFS Reader支援以下功能：
- 支援text、csv、orc和parquet格式的檔案，且要求檔案內容存放的是一張邏輯意義上的二維表。
- 支援多種類型資料讀取，支援列常量。
- 支援遞迴讀取、支援萬用字元*和?。
- 多個File可以支援並發讀取。

重要

OSS-HDFS Reader暫不支援單個File多線程並發讀取，此處涉及到單個File內部切分演算法。

離線寫

使用OSS-HDFS Writer時，請注意以下事項：

目前OSS-HDFS Writer僅支援text、orc和parquet三種格式的檔案，且檔案內容存放的必須是一張邏輯意義上的二維表。
對於text類型，需要保證寫入OSS-HDFS檔案的分隔字元與在Hive上建立表時的分隔字元一致，從而實現寫入OSS-HDFS資料與Hive表欄位關聯。

即時寫

支援即時寫入的能力。
支援即時寫入Hudi格式版本：0.14.x。

實現過程

OSS-HDFS Writer的實現過程如下所示：

根據您指定的path，建立一個OSS-HDFS檔案系統上不存在的臨時目錄。
建立規則：path_隨機。
將讀取的檔案寫入這個臨時目錄。
全部寫入後，將臨時目錄下的檔案移動到您指定的目錄（在建立檔案時保證檔案名稱不重複）。
刪除臨時目錄。如果在此過程中，發生網路中斷等情況造成無法與OSS-HDFS建立串連，需要您手動刪除已經寫入的檔案和臨時目錄。

支援的欄位類型

離線讀

ParquetFile、ORCFile、TextFile、CsvFile中的類型，會預設轉為Data Integration支援的內部類型，如下表所示。

類型分類	OSS-HDFS資料類型
整數類	TINYINT、SMALLINT、INT、BIGINT
浮點類	FLOAT、DOUBLE、DECIMAL
字串類	STRING、CHAR、VARCHAR
日期時間類	DATE、TIMESTAMP
布爾類	BOOLEAN

說明

LONG：OSS-HDFS檔案中的整數型別資料，例如123456789。
DOUBLE：OSS-HDFS檔案中的浮點類型資料，例如3.1415。
BOOLEAN：OSS-HDFS檔案中的布爾類型資料，例如true、false，不區分大小寫。
DATE：OSS-HDFS檔案中的時間類型資料，例如2014-12-31 00:00:00。

離線寫

OSS-HDFS Writer提供向OSS-HDFS檔案系統指定路徑中寫入TextFile檔案、 ORCFile檔案以及ParquetFile格式檔案。

OSS-HDFS支援的資料類型，如下表所示。

類型分類	OSS-HDFS資料類型
整數類	TINYINT、SMALLINT、INT和BIGINT
浮點類	FLOAT和DOUBLE
字串類	CHAR、VARCHAR和STRING
布爾類	BOOLEAN
日期時間類	DATE和TIMESTAMP

建立資料來源

在進行資料同步任務開發時，您需要在DataWorks上建立一個對應的資料來源，操作流程請參見建立並管理資料來源，詳細的配置參數解釋可在配置介面查看對應參數的文案提示。

資料同步任務開發

資料同步任務的配置入口和通用配置流程可參見下文的配置指導。

附錄：OSS-HDFS指令碼Demo與參數說明

離線任務指令碼配置方式

如果您配置離線任務時使用指令碼模式的方式進行配置，您需要按照統一的指令碼格式要求，在任務指令碼中編寫相應的參數，詳情請參見通過指令碼模式配置離線同步任務，以下為您介紹指令碼模式下資料來源的參數配置詳情。

Reader指令碼Demo

{
    "type": "job",
    "version": "2.0",
    "steps": [
        {
            "stepType": "oss_hdfs",//外掛程式名
            "parameter": {
                "path": "",//要讀取的檔案路徑
                "datasource": "",//資料來源
                "column": [
                    {
                        "index": 0,//序號,index從0開始（下標索引從0開始計數），表示從本地文字檔第一列開始讀取資料。
                        "type": "string"//欄位類型
                    },
                    {
                        "index": 1,
                        "type": "long"
                    },
                    {
                        "index": 2,
                        "type": "double"
                    },
                    {
                        "index": 3,
                        "type": "boolean"
                    },
                    {
                        "format": "yyyy-MM-dd HH:mm:ss", //日期格式
                        "index": 4,
                        "type": "date"
                    }
                ],
                "fieldDelimiter": ",",//資料行分隔符號
                "encoding": "UTF-8",//編碼格式
                "fileFormat": ""//文本類型
            },
            "name": "Reader",
            "category": "reader"
        },
        {
            "stepType": "stream",
            "parameter": {},
            "name": "Writer",
            "category": "writer"
        }
    ],
    "setting": {
        "errorLimit": {
            "record": ""//錯誤記錄數
        },
        "speed": {
            "concurrent": 3,//作業並發數
            "throttle": true //當throttle值為false時，mbps參數不生效，表示不限流；當throttle值為true時,表示限流。
            "mbps":"12"//限流，此處1mbps = 1MB/s。
        }
    },
    "order": {
        "hops": [
            {
                "from": "Reader",
                "to": "Writer"
            }
        ]
    }
}

Reader指令碼參數

參數	描述	是否必選	預設值
path	要讀取的檔案路徑。當指定單個OSS-HDFS檔案時，OSS-HDFS Reader暫時只能使用單線程進行資料幫浦。當指定多個OSS-HDFS檔案時，OSS-HDFS Reader支援使用多線程進行資料幫浦，線程並發數通過作業並發數concurrent指定。如果要讀取多個檔案，可以使用簡單Regex匹配，例如`/hadoop/data_201704`。如果檔案以時間命名且較為規律，則可以結合調度參數使用，調度參數將根據業務時間動態替換，詳情請參見調度參數支援的格式。說明實際啟動的並發數是您的OSS-HDFS待讀取檔案數量和您配置作業並發數兩者中的小者。當指定萬用字元，OSS-HDFS Reader嘗試遍曆出多個檔案資訊。例如指定/代表讀取/目錄下所有的檔案，指定/oss-hdfs/代表讀取oss-hdfs目錄下遊所有的檔案。OSS-HDFS Reader目前只支援``和`?`作為檔案萬用字元，文法類似於通常的Linux命令列檔案萬用字元。重要 Data Integration會將一個同步作業所有待讀取檔案視作同一張資料表。您必須自己保證所有的File能夠適配同一套schema資訊。您需要在配置OSS-HDFS資料來源時填寫的AK具有對應OSS-HDFS的讀取許可權。	是	無
fileFormat	檔案的類型，目前僅支援您配置為text、orc和parquet。 OSS-HDFS Reader能夠自動識別檔案的類型，並使用對應檔案類型的讀取策略。OSS-HDFS Reader在做資料同步前，會檢查您配置的路徑下所有需要同步的檔案格式是否和fileFormat一致，如果不一致任務會失敗。 fileFormat可以配置的參數值列表如下所示： text：表示TEXT檔案格式。 orc：表示ORC檔案格式。 csv：表示普通OSS-HDFS檔案格式（邏輯二維表）。 parquet：表示普通Parquet檔案格式。	是	無
column	要讀取的欄位列表。預設情況下，您可以全部按照STRING類型讀取資料，配置為`"column": ["*"]`。您也可以指定column欄位資訊，配置如下。其中： type：指定來源資料的類型。 index：指定當前列來自於文本第幾列（以0開始）。 value：指定當前類型為常量，不從源標頭檔讀取資料，而是根據value值自動產生對應的列。說明檔案資料列（index）和常量列（value）配置二選一。 `{ "type": "long", "index": 0 //從本地檔案文本第一列（下標索引從0開始計數）擷取LONG欄位，index表示從資料檔案中擷取列資料。 }, { "type": "string", "value": "alibaba" //HDFS Reader內部產生alibaba的字串欄位作為當前欄位，value表示常量列。 }`	是	無
fieldDelimiter	讀取的欄位分隔符號，OSS-HDFS Reader在讀取TextFile資料時，需要指定欄位分割符，如果不指定預設為逗號（,）。OSS-HDFS Reader在讀取ORC/PARQUET時，您無需指定欄位分割符。	否	,
encoding	讀取檔案的編碼配置。	否	utf-8
nullFormat	文字檔中無法使用標準字串定義null（null 指標），Data Integration提供nullFormat定義哪些字串可以表示為null。例如您配置`nullFormat:"null"`，如果源頭資料是null，Data Integration會將其視作null欄位。	否	無
compress	目前僅支援gzip、bzip2和snappy壓縮。	否	無

Writer指令碼Demo

{
    "type": "job",
    "version": "2.0",//版本號碼。
    "steps": [
        {
            "stepType": "stream",
            "parameter": {},
            "name": "Reader",
            "category": "reader"
        },
        {
            "stepType": "oss_hdfs",//外掛程式名。
            "parameter": {
                "path": "",//儲存到OSS-HDFS檔案系統的路徑資訊。
                "fileName": "",//OSS-HDFS Writer寫入時的檔案名稱。
                "compress": "",//OSS-HDFS檔案壓縮類型。
                "datasource": "",//資料來源。
                "column": [
                    {
                        "name": "col1",//欄位名。
                        "type": "string"//欄位類型。
                    },
                    {
                        "name": "col2",
                        "type": "int"
                    },
                    {
                        "name": "col3",
                        "type": "double"
                    },
                    {
                        "name": "col4",
                        "type": "boolean"
                    },
                    {
                        "name": "col5",
                        "type": "date"
                    }
                ],
                "writeMode": "",//寫入模式。
                "fieldDelimiter": ",",//資料行分隔符號。
                "encoding": "",//編碼格式。
                "fileFormat": "text"//文本類型。
            },
            "name": "Writer",
            "category": "writer"
        }
    ],
    "setting": {
        "errorLimit": {
            "record": ""//錯誤記錄數。
        },
        "speed": {
            "concurrent": 3,//作業並發數。
            "throttle": false //false代表不限流，下面的限流的速度不生效；true代表限流。
        }
    },
    "order": {
        "hops": [
            {
                "from": "Reader",
                "to": "Writer"
            }
        ]
    }
}

Writer指令碼參數

參數	描述	是否必選	預設值
fileFormat	檔案的類型，目前僅支援您配置為text、orc和parquet。 text：表示檔案寫入類型為text檔案格式。 orc：表示檔案寫入類型為orc檔案格式。 parquet：表示檔案寫入類型為parquet檔案格式。	是	無
path	儲存到OSS-HDFS檔案系統的路徑資訊，OSS-HDFS Writer會根據並發配置在path目錄下寫入多個檔案。與Hive表關聯時，請填寫Hive表在OSS-HDFS上的儲存路徑。例如Hive上設定的資料倉儲的儲存路徑。	是	無
fileName	OSS-HDFS Writer寫入時的檔案名稱，實際執行時會在該檔案名稱後添加隨機的尾碼作為每個線程寫入實際檔案名稱。	是	無
column	寫入資料的欄位，不支援對部分列寫入。與Hive中的表關聯時，需要指定表中所有欄位名和欄位類型，其中name指定欄位名，type指定欄位類型。您可以指定column欄位資訊，配置如下。 `{ "column": [ { "name": "userName", "type": "string" }, { "name": "age", "type": "long" } ] }`	是（如果fileFormat為parquet，此項無需填寫）	無
writeMode	OSS-HDFS Writer寫入前資料清理處理模式： append：寫入前不做任何處理，Data IntegrationOSS-HDFS Writer直接使用filename寫入，並保證檔案名稱不衝突。 nonConflict：如果目錄下有fileName首碼的檔案，直接報錯。 `truncate`：寫入前清理fileName名稱首碼匹配的所有檔案。例如，`"fileName": "abc"`，將清理對應目錄所有abc開頭的檔案。	是	無
fieldDelimiter	OSS-HDFS Writer寫入時的欄位分隔符號。說明僅支援單字元分隔字元，如果輸入多字元將導致運行時報錯。	是（如果fileFormat為parquet，此項無需填寫）	無
compress	OSS-HDFS檔案壓縮類型，預設不填寫，則表示沒有壓縮。其中text類型檔案支援gzip和bzip2壓縮類型。	否	無
encoding	寫檔案的編碼配置。	否	utf-8
parquetSchema	寫Parquet格式檔案時的必填項，用來描述目標檔案的結構，所以此項若且唯若fileFormat為parquet時生效，格式如下。 `message Message名 { 是否必填資料類型列名; .....................; }` 配置項說明如下： Message名：輸入名稱。是否必填：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; }`	否	無