Tunnel

Tunnel通常用来将本地的数据上传到maxcompute或将maxcompute数据下载到本地

1、MaxCompute数据的上传和下载

MaxCompute系统上传/下载数据包括两种方式
DataHub实时数据通道 Tunnel批量数据通道
OGG插件 大数据开发套件
Flume插件 DTS
LogStash插件 Sqoop
Fluentd插件 Kettle插件

MaxCompute客户端

Tunnel查看帮助信息
不带参数的tunnel或tunnel help查看帮助信息
也可tunnel help upload
Available subcommands：
upload
支持文件或目录（只一级目录）的上传；
每一次上传只支持数据上传到一个表或表的一个分区；
有分区的表一定要指定上传的分区，示例如下：
tunnel upload d:testp1.txt yunxiang_01.t_test_p/gender='male'
tunnel upload d:test yunxiang_01.t_test_p/gender='male' --scan=only
注释：yunxiang_01为项目； t_test_p为表；gender='male'为分区类；--scan=only表示只扫码数据不导入数据。
download
只支持下载到单个文件
每一次下载只支持一个表或者一个分区
有分区的表一定要指定下载的分区
例子：
tunnel download yunxiang_01.t_test_p/gender='male' d:testp_download.txt
resume
因为网络原因或者tunnel服务的原因造成的错误，使用该子命令续传;目前仅支持上传数据续传；
用法：tunnel resume [session_id]
show
显示历史任务
用法：tunnel show history [options]
purge

清除历史任务
用法：tunnel purge [n]
help

2、常用参数和Tunnel命令

-c: 数据文件字符编码，默认为UTF-8，也可以自行指定，如下：
tunnel upload log.txt test_table -c "gbk"
-ni: NULL数据标志符，默认为""（空字符串），也可指定如下：
tunnel upload log.txt test_table -ni "NULL"
-fd: 本地数据文件的列分割符，默认为逗号；
-rd: 本地数据文件的行分割符，默认为rn.
1、支持多个字符的列分隔符和行分隔符
2、支持控制字符等不可见字符做分隔符
3、列分隔符不能包含行分割符
4、转义字符分隔符，在命令行模式下只支持r,n和t
分隔符示例：
tunnel upload d:p.txt t_test_p/gender='male' -fd "||" -rd "rn"
tunnel download t_test_p/gender='male' d:p_download.txt -fd "||||" -rd "&&"
错误语句如下：
tunnel upload d:p.txt t_test_p/gender='male' -fd "b" -rd "t"
-dfp: DateTime类型数据格式，默认为yyyy-MM-dd HH:mm:ss如下
tunnel upload log.txt test_table -dfp "yyyy-MM-dd HH:mm:ss"
常见日期格式：
"yyyyMMddHHmmss": 数据格式"20140209101000"
"yyyy-MM-dd HH:mm:ss"（默认）：数据格式"2014-02-09 10:10:00"
"yyyy年MM月dd日":数据格式"2014年09月01日"
-sd：设置session目录，通过session id可以对上传、下载数据进行监控、续传（resume命令）等操作。执行过程由于数据问题，提示失败会给出session id及错误信息。
例子：
tunnel u d:data.txt sale_detail/sale_date=201312,region=hangzhou -s false
根据session id进行断点续传：
tunnel resume 201506101639224880870a002ec60c --force;
-te: 指定tunnel的Endpoint；
-threads：指定threads的数量，默认为1；
-tz:指定时区。默认为本地时区：Asia/Shanghai,说明Datetime类型默认支持时区为GMT+8
-acp: 如果目标表分区不存在，自动创建目标分区，默认关闭；
-bs: 每次上传至Tunnel的数据块大小，默认值： 100MiB（MiB=1024*1024B）
-cp: 指定是否在本地压缩后再上传，减少网络流量，默认开启；
-dbr: 是否忽略脏数据（多列，少列，列数据类型不匹配等情况）：

当值为true时，将全部不符合表定义的数据忽略
当值为false时，若遇到脏数据，则给出错误提示信息，即目标表内的原始数据不会被污染

-s: 是否扫描本地数据文件，默认为false，具体如下：

值为true时，先扫描数据，若数据格式正确，再导入数据。
值为false时，不扫描数据，直接进行数据导入。
值为only时，仅进行扫描本地数据，扫描结束后不继续导入数据

其他下载参数：
-ci: 指定列索引（从0）下载，使用逗号分隔；
-cn: 指定要下载的列名称，使用逗号分隔每个名称；
-cp: 指定是否压缩，减少网络流量，默认开启；
-e:当下载double值时，如果需要，使用指数函数表示，否则最多保留20位；
-h: 数据文件是否包含表头，如果为true,则dship会跳过表头从第二行开始下载数据。注意，-h=true和threads>1即多线程不能一起使用
-limit: 指定要下载的文件数量
tunnel的一些特点：
tunnel命令是对tunnel模块的SDK封装，具有tunnel的一些特点：

支持对表的读写，不支持视图；
写表是追加（Append）模式
采用并发以提高整体吞吐量
避免频繁提交

3、Tunnel SDK相关知识

Tunnel SDK中的几个概念：
基本含义：

session 完成对一张表或partition上传下载的的过程，称为一个session
request 在一个session内，请求一次tunnel RESTful API的过程
writer 当request为上传数据时，需要打开一个writer，将数据序列化的写入odps后台

cfile文件：

Block 当并发上传数据时，blockID就是不同的writer的标识，其对应后台的一个cfile。

相互关系：

session由一到多个request完成
同一个upload session中，用户可以同时打开多个cfile文件中的writer，多线程或多进程的并发上传数据
由于每一个block对应后台一个cfile文件，所以同一个session，两次打开同一个block就会导致覆盖行为，即只保留最后一次close writer对应的数据。

主要接口：

tabletunnel：访问tunnel服务的入口类，用来对maxcompute和tunnel进行访问
uploadsession：上传会话，包括会话的各种属性、动作以及通过会话进行写操作的方法
downloadsession：下载会话，包括会话的各种属性、动作以及通过会话进行读操作的方法

TableTunnel接口定义：

生命周期：从TableTunnel实例被创建开始，一直到程序结束。
提供方法：创建Upload对象和Download对象的方法
createDownloadSession：创建下载会话对象
createUploadSession：创建上传会话对象
getDownloadSession：获取下载对话对象句柄
getUploadSession：获取上传会话对象句柄
注：无论表有无分区，均有两个方法对应
setEndpoint：设置服务接入点

UploadSession接口定义：

commit：上传会话完成、提交
getBlocklist:得到成功上传的Block的列表
getID：得到上传会话的ID
getSchema：得到上传表的schema
getStatus：得到上传状态
newRecord：创建Record类型的记录
openRecordWriter：打开记录写入器

Java+eclipse环境配置

Step01:官网导航中找到并下载odps-sdk-core
Step02:下载eclipse并安装、配置
Step03:在eclipse中新建Java Project
Step04:将1中下载的压缩包中的jar包添加到项目的路径中。

简单上传实例：

处理流程：
创建阿里云账号->创建表通道->创建上传会话->读取文件->写入记录->上传会话提交
需要处理：
1、提供输入参数，通过run configuration的arguments，添加到program arguments里。
-f <source_file> -c <config_file> -t <odps table> -p <partition_spec> -fd <field_delimiter>

2、建表，增加分区
在maxcompute中建表，创建相应分区
3、上传完成后，检查表中的结果。

简单下载实例

处理流程：
创建阿里云账号->创建表通道->创建下载会话->读取记录->写入文件
需要处理：
1、提供输入参数，通过run configuration中的arguments，添加到program arguments里：
-f <target_file> -c <config_file> -t <odps_table> -p <partition_spec> -fd <field_delimiter>
2、下载完成后，找到对应文件，检查文件内容是否正确

多线程上传实例

处理流程：
提供配置信息-创建阿里云账号-创建表通道-创建上传会话-创建线程池-将待插入记录分给不同线程写入-关闭线程池-将每个线程写入的块提交
需要我们做的：
1、将配置参数写入java脚步（参照odps的配置文件）
2、建表，增加分区
3、上传完成后检查表中的结果

多线程下载实例

处理流程：
提供配置信息-创建阿里云账号-创建表通道-创建下载会话-创建线程池-分配待下载记录给不同的线程-执行下载任务-关闭线程池
需要我们做的：
1、将配置参数写入java脚本（参照odps的配置文件）
2、建表，增加分区
3、下载完成后，输入到屏幕的结果

常见问题：

1、一个session的超时时间：24小时
2、writer close时，将相对应的cfile文件从tmp目录挪移到data目录
3、session commit时，tunnel server将相应session data目录下的所有cfile文件挪移到相应表所在目录，即数据进表中，可以通过SQL进行读取
4、同一个session中，有一个block id对应的block上传失败，需要重传shi，使用相同的blockid
5、对于tunnel server，一个session对应一个目录。所以不同的session会产生不同的目录。这就是不同的session上传数据互不影响的原因
6、对同一个表上传数据，只有一台机器时，基本使用多线程并发就可以了，当需要更多带宽来支持上传数据时，使用不同机器不同进程上传（需要做数据切分）
7、在带宽最大能达到100M/s时，16-64个线程并发，太多的并发将消耗更多的CPU切换。