使用本地客户端(odpscmd)连接

如果您习惯使用命令行工具或者需要快速执行任务且不需要图形界面,建议您使用MaxCompute客户端访问MaxCompute项目并执行命令。MaxCompute客户端直接在您的本地计算机上运行,提供了一个简单且高效的方式来执行命令和管理MaxCompute服务。本文为您介绍下载、安装、配置和运行客户端并提供客户端相关使用说明信息。

前提条件

在使用MaxCompute客户端前,请您确认已满足如下条件:

  • 待安装MaxCompute客户端的设备已安装Java 8或以上版本。

  • 已创建MaxCompute项目。

    更多创建MaxCompute项目操作,请参见创建MaxCompute项目

  • 使用MaxCompute客户端的RAM用户已被添加至MaxCompute项目所属的DataWorks工作空间。

    更多添加工作空间成员操作,请参见授权给其他用户

使用限制

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客户端

说明

客户端从v0.27.0版本开始支持MaxCompute 2.0新数据类型,推荐使用新数据类型。支持的数据类型列表,请参见2.0数据类型版本

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

  1. 下载MaxCompute客户端安装包(Github)

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

    • 如果上方链接无法下载,您可以尝试单击此处的odpscmd_public_0.48.0进行下载。更多关于Github链接访问失败的问题,推荐您直接在搜索引擎中查找相关解决方案。

  2. 解压下载的安装包文件,得到binconflibplugins文件夹。

  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。

    您可以进入AccessKey管理页面获取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客户端可通过如下方式启动,您可以任选其中一种:

方式一:安装包的脚本文件

在MaxCompute客户端安装路径下的bin文件夹中,双击odpscmd.bat文件(Windows系统)或者双击odpscmd文件(macOS系统),即可启动MaxCompute客户端。返回如下信息,表明已成功连接MaxCompute项目。image.png

方式二:系统的命令行执行窗口

在系统的命令行执行窗口,进入MaxCompute客户端安装路径下的bin目录,执行odpscmd命令(Windows系统)或sh odpscmd(Linux系统或Mac系统),即可启动MaxCompute客户端。返回如下信息,表明已成功连接MaxCompute项目。

说明

在Ubuntu执行sh odpscmd会提示报错,请您使用./odpscmd命令尝试启动。

image.png

如果您通过系统的命令行窗口启动MaxCompute客户端,可以指定参数来执行命令,更多参数信息,请参见参考:启动参数

MaxCompute客户端相关操作

获取全部命令帮助

您可以通过如下方式快速获取MaxCompute客户端的命令帮助,您可以任选其中一种:

在MaxCompute客户端查看命令帮助信息

  • 查看全部命令的帮助信息。

    odps@project_name>help;
    --等价于如下命令。
    odps@project_name>h;
  • 通过指定关键字查看相关命令帮助信息。

    例如获取与表操作相关的命令帮助。

    odps@project_name>help table;
    --返回结果如下。
    Usage: alter table <tablename> merge smallfiles
    Usage: export table <tablename>
    Usage: show tables [in <project_name>] [like '<prefix>']
           list|ls tables [-p,-project <project_name>]
    Usage: describe|desc [<projectname>.]<tablename> [partition(<spec>)]
    Usage: read [<project_name>.]<table_name> [(<col_name>[,..])] [PARTITION (<partition_spec>)] [line_num]
    重要

    read命令属于SQL语法,涉及收费详细说明请参考SQL收费标准

在系统的命令行执行窗口查看命令帮助信息

在系统的命令行执行窗口,切换到MaxCompute客户端安装路径下的bin目录,执行如下命令查看全部命令的帮助信息。在命令行执行窗口启动MaxCompute客户端时,您可以指定一系列参数,参数信息请参见参考:启动参数

...\odpscmd\bin>odpscmd -h

获取当前登录用户信息

您可以在运行MaxCompute客户端后执行如下命令获取当前登录用户的信息。

odps@project_name>whoami;

返回结果说明如下。

  • Name:当前登录的账号信息。

  • Source IP:MaxCompute客户端所在设备的IP地址。

  • End_Point:MaxCompute服务的连接地址。

  • Project:MaxCompute项目的名称。

  • Schema:MaxCompute项目下的Schema。

退出MaxCompute客户端

您可以在运行MaxCompute客户端后执行如下命令退出。

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

下一步

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

说明

MaxCompute客户端支持的详细命令语法信息,请参见常用命令列表SQL命令及函数

常见报错

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

  • 报错:no java found

    • 可能原因:

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

    • 解决方法:

      请您在运行MaxCompute客户端的机器安装Java,并配环境变量。

      说明

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

  • 报错:找不到或无法加载主类 com.aliyun.openservices.odps.console.ODPSConsole

    • 可能原因:

      您可能下载了两次客户端安装包,第二次的时候目录被自动重命名为odpscmd_public (1),目录名称里包含了空格等字符,导致路径识别错误。

    • 解决方法:

      删除目录名称中的空格等字符。

  • 报错:Accessing project '<projectname>' failed: ODPS-0420111: Project not found - '<projectname>'.

    • 可能原因:

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

    • 解决方法:

      请您登录MaxCompute控制台,在工作区>项目管理页面获取已创建正确的MaxCompute项目名称后,修改odps_config.ini配置文件。

  • 报错:Accessing project '<projectname>' failed: ODPS-0420095: Access Denied - Authorization Failed [4002], You don't exist in project <projectname>.

  • 报错:Accessing project '<projectname>' failed: { "Code": "InvalidProjectTable", "Message": "The specified project or table name is not valid or missing."}Accessing project '<projectname>' failed: connect timed out

    • 可能原因:

      end_point参数值填写错误。例如您在本地计算机上使用MaxCompute客户端连接项目,您却使用了阿里云产品互联方式下的Endpoint(公网环境使用了内网Endpoint)或填入了Tunnel Endpoint。

    • 解决方法:

      请您参照Endpoint文档,选择与您要连接项目所属区域和网络环境相符的Endpoint。

      说明

      Endpoint用于MaxCompute服务,Tunnel Endpoint用于MaxCompute的Tunnel服务,end_point参数值应填写Endpoint,请不要填入Tunnel Endpoint。

  • 报错:Accessing project '<projectname>' failed: <endpoint>

    • 可能原因:

      end_point参数值填写错误。例如您需要填写华东1(杭州)地域的公网Endpoint(http://service.cn-hangzhou.maxcompute.aliyun.com/api),您却输入为了http://service.ch-hangzhou.maxcompute.aliyun.com/api

    • 解决方法:

      请您参照Endpoint文档,复制您要连接项目所属区域和网络环境相符的Endpoint,建议不要手动输入。

参考:启动参数

在系统的命令行执行窗口,您可以通过指定一系列参数快速执行命令,命令使用方法如下。

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

启动参数说明如下。

命令

说明

命令示例

--help-h

获取MaxCompute客户端的全部命令帮助信息。

odpscmd --help

--config

指定配置文件odps_config.ini的路径。默认配置文件的路径是odpscmd_public/conf/odps_config.ini

odpscmd --config=D:/odpscmd/conf/odps_config.ini

--project

指定访问的MaxCompute项目名称。

odpscmd --project=doc_test

--endpoint

指定连接MaxCompute服务的Endpoint信息。更多Endpoint信息,请参见Endpoint

odpscmd --endpoint=http://service.cn-shanghai.maxcompute.aliyun.com/api

-k

运行从指定位置开始的语句。当n≤0时,从第一条语句开始执行。每条语句以分号(;)分隔。

忽略前两条语句,直接从第三条语句开始执行。odpscmd -k 3 -e "drop table table_name;create table table_name (dummy string);insert overwrite table table_name select count(*) from table_name;"

-r

设置作业运行失败时的重试次数。

odpscmd -r 2 -e "select * from sale_detail;select * from table_test;"

-f

指定读取的文件。

  1. 准备本地脚本文件script.txt,假设存放在D盘,文件内容如下。

    drop table if exists test_table_mj;
    create table test_table_mj (id string, name string);
    drop table test_table_mj;
  2. 在系统命令行窗口,换到MaxCompute客户端安装路径下的bin目录,运行如下命令。

    ..\odpscmd\bin>odpscmd -f D:/script.txt;

-e

指定执行的命令。

odpscmd -e "select * from sale_detail;"

在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":" "}; 命令,关闭表头显示。

例如表noheader中有一列三行数据,为1、2、3。执行如下命令,将计算结果重定向stdout到目标句柄,计算结果仅包含具体数据,不包含其他额外信息:

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

版本

变更类型

描述

v0.47.0-public

新功能

  • HTTP命令:新增HTTP命令,使得用户能够便捷地以当前用户的身份发起HTTP请求。

  • 保持会话变量:新增keep-session-variables启动参数。开启后,执行USE命令切换项目时,之前设置的会话变量将不会被清除。例如,set a=b,即使在不同的项目之间切换,这些设置也会被保持。

  • Tunnel命令升级:

    • tunnel uploadtunnel download 命令新增-qn 选项,用于指定访问MaxCompute使用的Tunnel Quota名称。

    • tunnel upload命令新增-dfp选项,用于设置上传DATETIME类型文本的格式。

    Tunnel命令详情,请参见Tunnel命令

v0.46.5-public

新功能

  • 支持USE功能 ,保持之前设置的SESSION级别Flag。

  • Tunnel命令升级

    • 支持tunnel upsert命令。详情请参见Tunnel命令

    • 下载行级权限的表时,返回执行数据过滤SQL的执行信息。

v0.45.1-public

新功能

支持MaxCompute JSON数据类型MaxCompute TIMESTAMP_NTZ数据类型

v0.43.2-public

新功能

  • 支持创建External Volume。

  • Show命令支持查询当前MaxCompute项目中所有内建函数、或符合某规则的内建函数的信息。

v0.40.10-public

缺陷修复

删除Log4j依赖。

v0.40.8-public

新功能

支持项目按Schema存储。更多信息请参见Schema操作

v0.37.5-public

新功能

支持复杂数据类型通过Tunnel上传、下载。

v0.37.4-public

功能增强

  • 优化命令对应的帮助信息。

  • desc extended partition命令支持返回更多分区属性信息。

v0.36.0-public

新功能

支持创建External Project连接DLF(Data Lake Formation),实现湖仓一体功能。更多湖仓一体信息,请参见MaxCompute湖仓一体概述

缺陷修复

修复下载TIMESTAMP类型数据时,纳秒(nano)部分处理不正确的问题。