MaxCompute：使用本地用戶端（odpscmd）串連

費用說明

使用MaxCompute用戶端串連專案不收費，但是通過用戶端執行的操作可能會觸發MaxCompute計費。例如，使用用戶端提交一個SQL查詢和寫入命令，此SQL命令在MaxCompute上運行會消耗計算資源，同時寫入資料會佔用儲存空間，將產生計算費用和儲存費用。MaxCompute計費詳情請參見計費項目與計費方式。

安裝並配置MaxCompute用戶端

用戶端從v0.27.0版本開始支援MaxCompute 2.0新資料類型，推薦使用新資料類型。支援的資料類型列表，請參見2.0資料類型版本。

操作流程如下：

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用戶端

1. 建立MaxCompute專案。

2. 若使用MaxCompute用戶端的使用者為RAM使用者，需要通過阿里雲主帳號將該RAM使用者添加至目標MaxCompute專案。更多添加工作空間成員操作，請參見授權給其他使用者。

3. 啟動MaxCompute用戶端有如下兩種方式，任選其一即可：

   方式一：安裝包的指令檔

   在MaxCompute用戶端安裝路徑下的bin檔案夾中，雙擊odpscmd.bat檔案（Windows系統）或者雙擊odpscmd檔案（macOS系統），即可啟動MaxCompute用戶端。返回如下資訊，表明已成功串連MaxCompute專案。

   方式二：系統的命令列執行視窗

   在系統的命令列執行視窗，進入MaxCompute用戶端安裝路徑下的bin目錄，執行odpscmd命令（Windows系統）或sh odpscmd（Linux系統或Mac系統），即可啟動MaxCompute用戶端。返回如下資訊，表明已成功串連MaxCompute專案。

   說明

   在Ubuntu執行sh odpscmd會提示報錯，請使用./odpscmd命令嘗試啟動。

   

   如果通過系統的命令列視窗啟動MaxCompute用戶端，可以指定參數來執行命令，更多參數資訊，請參見啟動參數。

MaxCompute用戶端相關操作

...\odpscmd\bin>odpscmd -h

odps@project_name>whoami;

odps@project_name>quit;
-- 等價於如下命令。
odps@project_name>q;

相關文檔

登入MaxCompute用戶端後，即可在MaxCompute專案內執行SQL命令，請參見通過用戶端使用MaxCompute。

MaxCompute用戶端支援的詳細命令文法資訊，請參見常用命令列表或SQL命令及函數。

常見問題

配置完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。