DataHub服务用户迁移文档

前言

原Odps版内测DataHub（下文统称为老DataHub服务），于2016年11月21日起已经处于维护状态，新版DataHub届时已经开启公测，公测至今已有半年以上时间，我们决定开始逐步下线老DataHub服务，老版部分用户需要迁移至新版DataHub。

新版本具有更多的特性，性能功能都有不少提升，可以同时支持数据一份数据同步到Odps、OSS、ElasticSearch等多个不同服务中，且提供WebConsole控制台进行更简单的操作。

准备工作

本文档针对使用Logstash、Fluentd、Flume以及使用SDK写入老DataHub服务的用户，提供迁移到新服务的指引，过程中遇到任何困难可以联系我们

新版DataHub相关文档

DataHub产品使用文档

DataHub控制台

创建新datahub project

新版DataHub中存在项目空间-Project概念，与Odps中Project类似，但是不等于Odps中的Project，为了方便管理，我们建议迁移时在DataHub中创建与Odps Project同名的Project（不同名称也可以）

• 登录DataHub官网控制台，使用阿里云账号登录；
• 点击创建Project，输入名称及描述，点击创建（Project描述中建议携带Project用处及Owner的邮箱或联系方式）

创建新DataHub topic

新版DataHub存在主题-Topic的概念，与Odps的Table类似，但是不等于Odps的Table，通常如果是需要导入数据到Odps的话，需要为每张表创建一个Topic，且字段类型、顺序与名称需要一致，Odps中的分区字段当做普通的Topic字段处理，新版DataHub会根据该分区字段再DataHub中的数据值，将数据同步到Odps离线表中。

例如：

MaxCompute表： table_test(f1 string, f2 string, f3 double) partitioned by (ds string, pt string)
对应Topic应为如下的Schema:
Topic: topic_test(f1 string, f2 string, f3 double, ds string, pt string)

创建Topic可以通过以下方式：

• 若Topic数量较少，可以再WebConsole控制台，进入Project页面后点击创建Topic按钮，选择从MaxCompute导入，输入配置信息后勾选“自动创建DataConnector”，点击“导入表结构”即可导入odps表对应的格式，确认格式无误后选择Shard数量及生命周期， Shard数量建议与老服务一样，生命周期建议3天，点击创建即可。
• 若Topic过多，可以使用迁移工具DataHub表结构迁移工具,工具将对列表中的所有表创建对应Topic及Connector。

DataHub与MaxCompute字段类型对应表

映射Odps分区

老DataHub在写入数据时需要直接指定分区，如果是通过fluend或logstash等插件写入的用户是需要配置分区信息或者通过某个时间字段转为固定格式作为分区

新版DataHub在这一行为上有所改变，Odps表的分区字段再DataHub中将会变成一个普通字段，后台Connector同步任务在同步数据到Odps表时会根据分区字段比如pt具体每条记录的值写入Odps对应分区中。

例如：

MaxCompute表： table_test(f1 string, f2 string, f3 double) partitioned by (ds string, pt string)
对应Topic应为如下的Schema:
Topic: topic_test(f1 string, f2 string, f3 double, ds string, pt string)
数据1： ("test", "test", "0.14", "a1", "20170405")
数据2： ("test", "test", "0.14", "aa", "20170406")
则数据1将会同步到odps分区ds=a1,pt=20170405
则数据2将会同步到odps分区ds=a2,pt=20170406

• 若使用插件导入，并且是通过字符串转换为固定格式的分区值的用户，新的插件需要使用fluentd/logstash的filter功能，对分区字段的值进行转换，具体使用方式可以参考这些开源工具的官方文档

不同类型接入方式迁移

使用Java SDK

需要换成新版本DataHub的SDK，Mvn依赖变化

原依赖

<dependency>
    <groupId>com.aliyun.odps</groupId>
    <artifactId>odps-sdk-core</artifactId>
    <version>0.xxx</version>
</dependency>

新依赖

<dependency>
    <groupId>com.aliyun.datahub</groupId>
    <artifactId>aliyun-sdk-datahub</artifactId>
    <version>2.3.0-public</version>
</dependency>

Client初始化

原Client初始化步骤

Account account = new AliyunAccount(accessId, accessKey);
odps = new Odps(account);
odps.setDefaultProject(project);
odps.setEndpoint(odpsEndpoint);
DatahubClient client = new DatahubClient(odps, project, table, datahubEndpoint);
client.loadShard(shardNumber);
client.waitForShardLoad();

新Client初始化步骤

AliyunAccount account = new AliyunAccount(accessId, accessKey);
DatahubConfiguration conf = new DatahubConfiguration(account, datahubEndpoint);
DatahubClient client = new DatahubClient(conf);

获取Shard列表

原获取Shard列表及状态方式

HashMap<Long, DatahubClient.ShardState> shardStatus = client.getShardStatus();

新方式

ListShardResult listShardResult = client.listShard(projectName, topicName);

写入数据

原写入方式

DatahubWriter writer = client.openDatahubWriter(shardId);
TableSchema schema = client.getStreamSchema();
DatahubRecordPack recordPack = new DatahubRecordPack(schema);

/* Write another 20 records recordPack into another partition */
for (int i = 0; i < 20; i++) {
    Record record = makeRecord(schema);
    recordPack.append(record);
}

partSpec = "pt='20150809'";
packId = writer.write(new PartitionSpec(partSpec), recordPack)
    .getPackId();
System.out.println("record append to the pack: " + packId);

新写入方式

List<RecordEntry> recordEntries = new ArrayList<RecordEntry>();
RecordEntry entry = new RecordEntry(schema);
entry.setString(0, "Test");
entry.setBigint(1, 5L);
entry.setShardId(shardId);
recordEntries.add(entry);
PutRecordsResult result = client.putRecords(projectName, topicName, recordEntries);
if (result.getFailedRecordCount() != 0) {
    List<ErrorEntry> errors = result.getFailedRecordError();
    // deal with result.getFailedRecords()
}

完整写入新DataHub示例代码

使用Fluentd

通过Fluend插件写入数据的用户，迁移除了上述准备工作外，还需进行三个步骤

• 更换，安装新插件包
• 根据配置文件对比，修改现有配置文件
• 使用新配置文件重新启动fluend进程

插件包更换

新版Fluentd插件使用文档

原安装语句

gem install fluent-plugin-aliyun-odps

新安装语句（也可按照新版文档提供的一键安装包安装logstash）

gem install fluent-plugin-datahub

配置对比

部分配置不需更改，更改match 部分配置即可。

新增配置

[TODO] 能否放一个新老的diff文件example

使用Logstash

通过Logstash插件写入数据的用户，迁移除了上述准备工作外，还需进行三个步骤

• 更换，安装新插件包
• 根据配置文件对比，修改现有配置文件
• 使用新配置文件重新启动Logstash进程

插件包更换

新版Logstash插件使用文档

配置对比

input部分配置不需更改，更改output部分配置即可。

新增配置

使用Apache Flume

通过Flume工具写入数据的用户，迁移除了上述准备工作外，还需进行三个步骤

• 更换，安装新Flume工具插件
• 根据配置文件对比，修改现有配置文件
• 使用新配置文件重新启动Flume进程

插件更新

新版Flume工具文档

配置对比

使用OGG

通过OGG工具写入数据的用户，迁移除了上述准备工作外，还需进行三个步骤

• 更换，安装新OGG工具插件
• 根据配置文件对比，修改现有配置文件
• 使用新配置文件重新启动OGG进程

插件更新

新版OGG工具文档

配置对比

除以上配置外，其他DataHub相关配置均独立到configure.xml文件配置，具体含义请参看新版OGG工具文档。