使用本地客户端（odpscmd）连接

使用限制

MaxCompute客户端从v0.28.0版开始支持JDK 1.9，v0.28.0以下版本只支持JDK 1.8。您可以启动MaxCompute客户端后，在命令行界面查看客户端版本号。更多启动客户端操作，请参见运行MaxCompute客户端。

费用说明

使用MaxCompute客户端连接项目不收费，但是通过客户端执行的操作可能会触发MaxComput计费。例如，当您使用客户端提交一个SQL查询和写入命令，此SQL命令在MaxCompute上运行会消耗计算资源，同时写入数据会占用存储空间，将产生计算费用和存储费用。MaxCompute计费详情请参见计费项与计费方式。

注意事项

• MaxCompute客户端的输出格式不承诺向前兼容，不同版本间的客户端命令格式及行为有差异，请勿依赖客户端的输出格式执行任何解析工作。更多客户端版本，请参见aliyun-odps-console。

• 当您通过MaxCompute客户端首次执行tunnel download命令时，MaxCompute客户端会为您在当前设备的客户端安装目录plugins/dship下创建一个session文件夹，用于存放日志。如果多名用户共用同一设备执行tunnel download命令时，为确保数据安全，可以通过如下方式解决该问题：

  • 通过设备自身的文件夹权限管理功能，管控session文件夹权限。

  • 在tunnel download命令中添加-sd <新session文件夹名称>或-session-dir <新session文件夹名称>参数，将数据下载至其他session文件夹。更多tunnel download命令信息，请参见Download。

• MaxCompute客户端的命令行使用两个减号（--）作为注释。

• 客户端默认编码为UTF-8，因此您需要注意您本机的环境编码。若本机环境编码不是UTF-8，则当您通过客户端查询MaxCompute表数据返回值有中文可能会出现乱码或者您通过客户端执行Tunnel命令上传本地数据文件到MaxCompute，也可能会出现中文乱码。

安装并配置MaxCompute客户端

安装并配置MaxCompute客户端的操作流程如下：

1. 下载MaxCompute客户端安装包（Github）。

   说明

   • 您可以通过上方链接进入客户端发布界面，下载最新版本的MaxCompute客户端安装包（odpscmd_public.zip）。

   • 如果上方链接无法下载，您可以尝试单击此处的MaxCompute客户端安装包（OSS）进行下载。更多关于Github链接访问失败的问题，推荐您直接在搜索引擎中查找相关解决方案。

2. 解压下载的安装包文件，得到bin、conf、lib和plugins文件夹。

3. 进入conf文件夹，配置odps_config.ini文件。

   odps_config.ini文件中使用井号（#）作为注释。参数说明如下。

   参数	是否必填	描述	示例
   project_name	是	访问的目标MaxCompute项目名称。 如果您创建了标准模式的工作空间，在配置project_name时，请注意区分生产环境与开发环境（_dev）的项目名称，请参见必读：简单模式和标准模式的区别。 您可以登录MaxCompute控制台，在工作区> 项目管理页面获取MaxCompute项目名称。	doc_test_dev
   access_id	是	阿里云账号或RAM用户的AccessKey ID。 您可以进入AccessKey管理页面获取AccessKey ID。	无
   access_key	是	AccessKey ID对应的AccessKey Secret。	无
   end_point	是	MaxCompute服务的连接地址。 您需要根据创建MaxCompute项目时选择的地域以及网络连接方式配置Endpoint。各地域及网络对应的Endpoint值，请参见Endpoint。 重要 Endpoint用于MaxCompute服务，Tunnel Endpoint用于MaxCompute的Tunnel服务，此处请填写Endpoint。 如果Endpoint配置有误，会出现无法访问错误，请务必仔细确认。	http://service.cn-hangzhou.maxcompute.aliyun.com/api
   log_view_host	否	Logview地址。您可以通过该地址查看作业的详细运行信息，并为报错处理提供依据。固定取值为：http://logview.odps.aliyun.com。 说明 推荐您配置该参数，如果不配置该参数，在作业报错时无法快速定位问题。	http://logview.odps.aliyun.com
   https_check	否	是否开启HTTPS访问机制，对访问MaxCompute项目的请求进行加密。取值范围如下： True：采用HTTPS机制。 False：采用HTTP机制。 默认值为False。	True
   data_size_confirm	否	输入数据量的最大值，单位为GB。取值范围无限制。推荐设置为100 GB。	100
   update_url	否	预留参数，暂无需关注。	无
   use_instance_tunnel	否	是否使用InstanceTunnel下载SQL执行结果。取值范围如下： True：使用InstanceTunnel下载SQL执行结果。 False：不使用InstanceTunnel下载SQL执行结果。 默认值为False。	True
   instance_tunnel_max_record	否	客户端返回的SQL执行结果的最大记录数。如果use_instance_tunnel值为True，需要配置该参数。最大值为10000。	10000
   tunnel_endpoint	否	Tunnel服务的外网访问链接。如果您未配置Tunnel Endpoint，Tunnel会自动路由到MaxCompute服务所在网络对应的Tunnel Endpoint。如果您配置了Tunnel Endpoint，则以配置为准，不进行自动路由。 各地域及网络对应的Tunnel Endpoint值，请参见Endpoint。	http://dt.cn-hangzhou.maxcompute.aliyun.com
   set.<key>	否	设置MaxCompute项目的属性。 更多属性信息，请参见属性列表。	set.odps.sql.decimal.odps2=true

   说明

   请确保上述信息配置正确，若信息配置错误，会导致项目连接失败。

运行MaxCompute客户端

MaxCompute客户端相关操作

...\odpscmd\bin>odpscmd -h

odps@project_name>whoami;

odps@project_name>quit;
--等价于如下命令。
odps@project_name>q;

下一步

登录MaxCompute客户端后，即可在MaxCompute项目内执行SQL命令，请参见通过客户端使用MaxCompute。

常见报错

配置完odps_config.ini文件后启动MaxCompute客户端，常见报错如下：

参考：启动参数

Usage: odpscmd [OPTION]...
where options include:
    --help                                  (-h)for help
    --config=<config_file>                  specify another config file
    --project=<prj_name>                    use project
    --endpoint=<http://host:port>           set endpoint
    -k <n>                                  will skip begining queries and start from specified position
    -r <n>                                  set retry times
    -f <"file_path;">                       execute command in file
    -e <"command;[command;]...">            execute command, include sql command

在Shell（或Windows命令行）执行窗口，用户可能需要使用odpscmd -e <SQL语句>执行得到的动态返回值，Shell的变量会获取这个动态返回值，然后在Shell中执行后续作业。此场景需要返回值不包含运行信息、表头等额外信息。为便于Shell调用，您需要配置odps_config.ini文件中的use_instance_tunnel参数值为false，关闭Instance Tunnel服务。然后执行set odps.sql.select.output.format={"needHeader":false,"fieldDelim":" "}; 命令，关闭表头显示。

--Windows命令行执行窗口运行命令如下。
...\odpscmd\bin>odpscmd -e "set odps.sql.select.output.format={""needHeader"":false,""fieldDelim"":"" ""};select * from noheader;" >D:\test.txt
--返回结果会保存在D:\test.txt中。

--Shell执行窗口运行命令如下。
/Users/.../odpscmd/bin/odpscmd -e "set odps.sql.select.output.format={\"needHeader\":false,\"fieldDelim\":\"\"};select * from noheader;" >/Users/A/temp/test.txt 
--返回结果会保存在/Users/A/temp/test.txt中。
--返回结果如下。
1
2
3

参考：版本更新记录

MaxCompute客户端近期版本的更新说明如下，详细信息请单击对应版本链接获取。

更多MaxCompute客户端版本及相关功能更新说明，请参见GitHub。