關於ApsaraDBForOceanbase資料同步能力支援問題 - DataWorks

ApsaraDB for OceanBase資料來源提供讀取和寫入ApsaraDB for OceanBase資料的雙向功能，您可以使用ApsaraDB for OceanBase資料來源配置同步任務同步資料。本文為您介紹DataWorks的ApsaraDB for OceanBase資料同步能力支援情況。

支援的版本

離線讀寫

ApsaraDB For OceanBase Reader和ApsaraDB For OceanBase Writer通過OceanBase資料庫驅動訪問ApsaraDB For OceanBase，您需要確認驅動和您的ApsaraDB For OceanBase服務之間的相容能力。資料庫驅動使用如下版本。

<dependency>
    <groupId>com.alipay.OceanBase</groupId>
    <artifactId>OceanBase-connector-java</artifactId>
    <version>3.1.0</version>
</dependency>

使用限制

離線讀

ApsaraDB For OceanBase包括Oracle和MySQL兩種租戶模式，您在配置where資料過濾條件、column中的函數列時，需要符合對應租戶模式的SQL文法約束，否則SQL語句可能執行失敗。
支援閱讀檢視表。
在離線讀取OceanBase資料的過程中，請避免對正在同步的資料進行修改操作，否則可能會導致資料品質問題（如資料重複或資料丟失）。

離線寫

insert into...：當主鍵或唯一性索引衝突時，無法寫入衝突的行。Oracle租戶模式下僅支援insert into。
insert into...ON DUPLICATE KEY UPDATE...：當主鍵或唯一性索引未衝突時，與insert into的行為一致。當主鍵或唯一性索引衝突時，新行會替換指定的欄位。MySQL租戶模式下支援insert into...和insert into...ON DUPLICATE KEY UPDATE...。
目的表所在資料庫必須是主庫才能寫入資料。
說明
整個任務需要至少具備insert into...的許可權。是否需要其它許可權，取決於您配置任務時，在preSql和postSql中指定的語句。
建議您使用batch的方式批量寫入資料，當行數累計到預定閾值時，再發起寫入請求。
ApsaraDB For OceanBase包括Oracle和MySQL兩種租戶模式，您在配置preSql、postSql時，需要符合對應租戶模式的SQL文法約束，否則SQL語句可能執行失敗。

即時讀

OceanBase為Distributed Relational Database Service，可以將物理分布不同的多個資料庫上的資料整合為一個完整的邏輯資料庫。但即時同步OceanBase的資料至AnalyticDB for MySQL，目前僅支援同步單個物理庫的資料，不支援同步邏輯庫資料。

說明

在整庫即時同步任務中，不支援串連串模式資料來源。
在整庫即時同步任務中，版本需要在V3.0及以上。

資料同步前準備

在DataWorks上進行資料同步前，您需要參考本文提前在ApsaraDB For OceanBase側進行資料同步環境準備，以便在DataWorks上進行ApsaraDB For OceanBase資料同步任務配置與執行時服務正常。以下為您介紹ApsaraDB For OceanBase同步前的相關環境準備。

準備工作1：配置白名單

將Serverless資源群組或獨享Data Integration資源群組所在的VPC網段添加至OceanBase的白名單中，詳情請參見添加白名單。

準備工作2：建立帳號並配置帳號許可權

您需要規劃一個資料庫的登入賬戶用於後續執行操作，此帳號需要擁有OceanBase的相關操作許可權，詳情請參見建立帳號。

建立資料來源

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

資料同步任務開發

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

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

離線任務指令碼配置方式

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

Reader指令碼Demo

{
    "type": "job",
    "steps": [
        {
            "stepType": "apsaradb_for_OceanBase", //外掛程式名
            "parameter": {
                "datasource": "", //資料來源名
                "where": "",
                "column": [ //欄位
                    "id",
                    "name"
                ],
                "splitPk": ""
            },
            "name": "Reader",
            "category": "reader"
        },
        {
            "stepType": "stream",
            "parameter": {
                "print": false,
                "fieldDelimiter": ","
            },
            "name": "Writer",
            "category": "writer"
        }
    ],
    "version": "2.0",
    "order": {
        "hops": [
            {
                "from": "Reader",
                "to": "Writer"
            }
        ]
    },
    "setting": {
        "errorLimit": {
            "record": "0" //錯誤記錄數
        },
        "speed": {
            "throttle": true, //當throttle值為false時，mbps參數不生效，表示不限流；當throttle值為true時,表示限流。
            "concurrent": 1, //作業並發數
            "mbps":"12"//限流，此處1mbps = 1MB/s。
        }
    }
}

Reader指令碼參數

參數	描述	是否必選	預設值
datasource	如果您使用的DataWorks版本支援添加ApsaraDB For OceanBase資料來源，即可在此處根據資料來源名稱引用您添加的ApsaraDB For OceanBase資料來源。包括jdbcUrl和username兩種配置方式。	是	無
jdbcUrl	到對端資料庫的JDBC串連資訊。使用JSON的數組描述，並支援一個庫填寫多個串連地址。如果配置了多個，ApsaraDB For OceanBase Reader可以依次探測IP的可串連性，直到選擇一個合法的IP。如果全部串連失敗，則ApsaraDB For OceanBase Reader報錯。說明 jdbcUrl必須包含在connection登錄區中。 jdbcUrl根據ApsaraDB For OceanBase官方規範，可以填寫串連附件控制資訊。例如`jdbc:oceanbase://127.0.0.1:3306/database`，需要和username配置方式二選一。	否	無
username	資料來源的使用者名稱。	否	無
password	資料來源指定使用者名稱的密碼。	否	無
table	選取的需要同步的表。使用JSON的數組進行描述，支援同時讀取多張表。當配置為多張表時，您需要保證多張表的Schema結構一致，ApsaraDB For OceanBase Reader不檢查表的邏輯是否統一。說明 table必須包含在connection登錄區中。	是	無
column	所配置的表中需要同步的列名集合，使用JSON的數組描述欄位資訊。預設使用所有列配置，例如[ * ]。支援列裁剪：可以匯出部分列。支援列換序：可以不按照表Schema資訊順序進行匯出。支援常量配置：例如`'123'`。支援函數列：例如`date('now')`。 column必須顯示指定同步的列集合，不允許為空白。	是	無
splitPk	ApsaraDB For OceanBase Reader進行資料幫浦時，如果指定splitPk，表示您希望使用splitPk代表的欄位進行資料分區，資料同步因此會啟動並發任務進行資料同步，提高資料同步的效能。推薦splitPk使用者使用表主鍵，因為表主鍵通常情況下比較均勻，因此切分出來的分區也不容易出現資料熱點。目前splitPk僅支援整型資料切分，不支援字串、浮點和日期等其它類型。如果您指定其它非支援類型，ApsaraDB For OceanBase Reader將報錯。如果設定splitPk值為空白，底層將視作您不允許對單表進行切分，因此使用單通道進行抽取。	否	空
where	ApsaraDB For OceanBase Reader根據指定的column、table、where條件拼接SQL，並根據該SQL進行資料幫浦。例如，在進行測試時，可以指定where條件為limit 10。在實際業務情境中，通常會選擇當天的資料進行同步，指定where條件為`gmt_create>$bizdate`。 where條件可以有效地進行業務增量同步處理。 where條件不配置或為空白，則視作全表同步資料。	否	無
querySql	在部分業務情境中，where配置項不足以描述所篩選的條件，您可以通過該配置型來自訂篩選SQL。配置該項後，資料同步系統會忽略tables、columns和splitPk配置項，直接使用該項配置的內容對資料進行篩選。當您配置querySql時，ApsaraDB For OceanBase Reader直接忽略table、column、where和splitPk條件的配置。	否	無
fetchSize	該配置項定義了外掛程式和資料庫伺服器端每次批量資料擷取條數，該值決定了Data Integration和伺服器端的網路互動次數，能夠較大地提升資料幫浦效能。說明 fetchSize值過大（>2048）可能造成資料同步進程OOM。	否	1,024

Writer指令碼Demo

{
    "type":"job",
    "version":"2.0",//版本號碼。
    "steps":[
        {
            "stepType":"stream",
            "parameter":{},
            "name":"Reader",
            "category":"reader"
        },
        {
            "stepType":"apsaradb_for_OceanBase",//外掛程式名。
            "parameter":{
                "datasource": "資料來源名",
                "column": [//欄位。
                    "id",
                    "name"
                ],
                "table": "apsaradb_for_OceanBase_table",//表名。
                "preSql": [ //執行資料同步任務之前率先執行的SQL語句。
                    "delete from @table where db_id = -1"
                ],
                "postSql": [//執行資料同步任務之後率先執行的SQL語句。
                    "update @table set db_modify_time = now() where db_id = 1"
                ],
                "writeMode": "insert",
            },
            "name":"Writer",
            "category":"writer"
        }
    ],
    "setting":{
        "errorLimit":{
            "record":"0"//錯誤記錄數。
        },
        "speed":{
            "throttle":true,//當throttle值為false時，mbps參數不生效，表示不限流；當throttle值為true時,表示限流。
            "concurrent":1, //作業並發數。
            "mbps":"12"//限流，此處1mbps = 1MB/s。
        }
    },
    "order":{
        "hops":[
            {
                "from":"Reader",
                "to":"Writer"
            }
        ]
    }
}

Writer指令碼參數

參數	描述	是否必選	預設值
datasource	如果您使用的DataWorks版本支援添加ApsaraDB For OceanBase資料來源，即可在此處根據資料來源名稱引用您添加的ApsaraDB For OceanBase資料來源。包括jdbcUrl和username兩種配置方式。	否	無
jdbcUrl	到對端資料庫的JDBC串連資訊，jdbcUrl包含在connection登錄區中。在一個資料庫上只能配置一個值，不支援同一個資料庫存在多個主庫的情況（雙主匯入資料情況）。 jdbcUrl的格式和ApsaraDB For OceanBase官方一致，並可串連附加參數資訊。例如，`jdbc:oceanbase://127.0.0.1:3306/database`。	是	無
username	資料來源的使用者名稱。	是	無
password	資料來源指定使用者名稱的密碼。	是	無
table	需要同步寫出的表名稱，使用JSON的數組進行描述。說明 table必須包含在connection登錄區中。	是	無
column	目標表需要寫入資料的欄位，欄位之間用英文所逗號分隔。例如，`"column": ["id", "name", "age"]`。說明 column配置項必須指定，不可為空。	是	無
writeMode	控制寫入資料至目標表使用的模式，包括`insert into`和 `ON DUPLICATE KEY UPDATE`。	是	無
preSql	寫入資料至目標表前，會先執行此處的標準語句。如果SQL中有需要操作的表名稱，請使用`@table`表示，以便在實際執行SQL語句時，對變數按照實際表名稱進行替換。	否	無
postSql	寫入資料至目標表後，會執行此處的標準語句。	否	無
batchSize	一次性批量提交的記錄數大小，該值可以極大減少資料同步系統與伺服器端的網路互動次數，並提升整體輸送量。說明 fetchSize值過大（>2048）可能造成資料同步進程OOM。	否	1,024