使用客户端（odpscmd）连接

使用限制

MaxCompute客户端从v0.28.0版开始支持JDK 1.9，v0.28.0以下版本只支持JDK 1.8。您可以启动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=
   access_id=
   access_key=
   end_point=
   log_view_host=
   https_check=
   # confirm threshold for query input size(unit: GB)
   data_size_confirm=
   # this url is for odpscmd update
   update_url=
   # download sql results by instance tunnel
   use_instance_tunnel=
   # the max records when download sql results by instance tunnel
   instance_tunnel_max_record=
   # IMPORTANT:
   #   If leaving tunnel_endpoint untouched, console will try to automatically get one from odps service, which might charge networking fees in some cases.
   #   Please refer to Endpoint
   # tunnel_endpoint=
   
   # use set.<key>=
   # e.g. set.odps.sql.select.output.format=

   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。 您可以进入AccessKey管理页面获取AccessKey Secret。	无
   end_point	是	MaxCompute服务的连接地址。 您需要根据创建MaxCompute项目时选择的地域以及网络连接方式配置Endpoint。各地域及网络对应的Endpoint值，请参见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客户端

您可以在上述图中的光标位置处输入命令，按下回车即可运行。命令示例及返回结果如下。

获取当前登录用户

您可以在上述运行窗口执行如下命令获取当前登录用户的信息。

odps@project_name>whoami;

返回结果如下。

• Name：当前登录的账号信息。
• Source IP：MaxCompute客户端所在设备的IP地址。
• End_Point：MaxCompute服务的连接地址。
• Project：MaxCompute项目的名称。

退出MaxCompute客户端

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

获取命令帮助

启动参数

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客户端近期版本的更新说明如下，详细信息请单击对应版本链接获取。

常见报错与解决方案

报错：Project not found时，如何解决？

• 问题现象
  配置完odps_config.ini文件后启动MaxCompute客户端，出现如下报错：

  Accessing project ‘projectname’ failed: ODPS-0420111: Project not found - 'projectname'.

• 问题原因

  odps_config.ini配置文件中的项目名称填写错误。

• 解决方法

  请您登录MaxCompute控制台，在项目管理页签获取正确的MaxCompute项目名称后，修改odps_config.ini配置文件。

启动odpscmd时报错：no java found，如何解决？

• 问题现象
  配置完odps_config.ini文件后启动MaxCompute客户端，出现如下报错：

  no java found

• 问题原因

  您运行MaxCompute客户端的机器未安装Java。

• 解决方法
  请您在运行MaxCompute客户端的机器安装Java，并配环境变量。

  说明 MaxCompute客户端从v0.28.0版本起开始支持JDK 1.9，之前版本只支持JDK 1.8。