MaxCompute：使用本地用戶端（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。 您可以進入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用戶端相關操作

...\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用戶端近期版本的更新說明如下，詳細資料請單擊對應版本連結擷取。