CLIツールの使用に慣れている場合、またはグラフィカルユーザーインターフェイス (GUI) なしでタスクをすばやく実行したい場合は、MaxComputeクライアントを使用してMaxComputeプロジェクトにアクセスし、コマンドを実行することをお勧めします。 オンプレミスのマシンでMaxComputeクライアントを実行すると、MaxComputeプロジェクトを簡単かつ効率的に管理できます。 このトピックでは、MaxComputeクライアントインストールパッケージをダウンロードし、MaxComputeクライアントをインストール、設定、実行する方法について説明します。 このトピックでは、関連する手順も提供します。
前提条件
MaxComputeクライアントをインストールする前に、次の条件が満たされていることを確認してください。
MaxComputeクライアントをインストールするマシンにJava 8以降がインストールされます。
MaxComputeプロジェクトが作成されます。
MaxComputeプロジェクトの作成方法の詳細については、「MaxComputeプロジェクトの作成」をご参照ください。
MaxComputeクライアントを使用するRAMユーザーが、MaxComputeプロジェクトが属するDataWorksワークスペースに追加されます。
DataWorksワークスペースにメンバーを追加する方法の詳細については、「RAMユーザーへの権限の付与」をご参照ください。
制限事項
MaxComputeクライアントV0.28.0以降は、Java Development Kit (JDK) 1.8とJDK 1.9をサポートしています。 V0.28.0より前のバージョンのMaxComputeクライアントは、JDK 1.8のみをサポートします。 MaxComputeクライアントを起動した後、CLIでクライアントのバージョンを確認できます。 MaxComputeクライアントを起動する方法の詳細については、「MaxComputeクライアントの実行」をご参照ください。
課金ルール
MaxComputeクライアントでMaxComputeプロジェクトにアクセスした場合、料金は発生しません。 ただし、MaxComputeクライアントで実行した操作に対して課金される場合があります。 たとえば、MaxComputeクライアントでSQL文を実行してデータを照会したりデータを書き込んだりすると、SQL文はコンピューティングリソースを消費し、書き込まれたデータはストレージ容量を占有します。 その結果、データコンピューティングとストレージに対して課金されます。 MaxComputeの課金ルールの詳細については、「概要」をご参照ください。
注意事項
MaxComputeクライアントの出力形式は、フォワード互換性がない場合があります。 クライアントのコマンド構文と実行ルールは、クライアントのバージョンによって異なります。 データの解析をクライアントの出力形式に依存しないことをお勧めします。 クライアントバージョンの詳細については、「aliyun-odps-console」をご参照ください。
MaxComputeクライアントで初めて
Tunnel Download
コマンドを実行すると、MaxComputeクライアントはオンプレミスマシンのクライアントインストールディレクトリplugins/dship
にsessionという名前のフォルダを作成します。 フォルダはログを保存するために使用されます。 複数のユーザーが同じマシンでTunnel Download
コマンドを実行する場合、次のいずれかの方法を使用してデータのセキュリティを確保できます。マシンが提供するフォルダー権限管理機能を使用して、セッションフォルダーの権限を管理します。
別のセッションフォルダにデータをダウンロードするには、
-sd <Name of the new session folder>
または-session-dir <Name of the new session folder>
パラメーターをTunnel Download
コマンドに追加します。Tunnel Download
コマンドの詳細については、「Download」をご参照ください。
2つの連続したマイナス記号 (-) を使用して、MaxComputeクライアントのコマンドラインをコメントアウトします。
デフォルトでは、MaxComputeクライアントはUTF-8エンコーディングを使用します。 UTF-8エンコーディングを使用しないオンプレミス環境では、以下のシナリオで文字化けが存在する可能性があります。 1. MaxComputeクライアントを使用してMaxComputeテーブル内のデータをクエリすると、システムは漢字を含む値を返します。 2. MaxComputeクライアントでTunnelコマンドを実行して、ローカルデータファイルをMaxComputeにアップロードします。
MaxComputeクライアントのインストールと設定
MaxComputeクライアントV0.27.0以降は、MaxCompute V2.0データ型エディションをサポートしています。 MaxCompute V2.0データ型エディションの使用を推奨します。 MaxCompute V2.0データ型エディションでサポートされているデータ型の詳細については、「MaxCompute V2.0データ型エディション」をご参照ください。
MaxComputeクライアントをインストールして設定するには、次の手順を実行します。
GitHubからMaxComputeクライアントインストールパッケージをダウンロードします。
説明上記のリンクをクリックすると、表示されるページで最新バージョンのMaxComputeクライアントインストールパッケージodpscmd_public.zipをダウンロードできます。
上記のリンクをクリックしてもパッケージをダウンロードできない場合は、odpscmd_public_0.48.0.zipをクリックしてパッケージをダウンロードします。 ダウンロードの失敗を解決する方法の詳細については、検索エンジンを使用して関連ソリューションを検索することをお勧めします。
ダウンロードしたパッケージを解凍し、bin,conf,lib、およびpluginsフォルダーを作成します。
confフォルダーをを開きます。odps_config.iniファイルを設定します。
odps_config.iniファイルで、番号記号 (#) で始まる行はコメントです。 odps_config.iniファイルのパラメーターを次の表に示します。
パラメーター
必須
説明
例
project_name
必須
アクセスするMaxComputeプロジェクトの名前。
標準モードでワークスペースを作成する場合、[既定のプロジェクト] パラメーターを設定するときに、運用環境と開発環境のプロジェクト名の違いに注意してください。 開発環境のプロジェクトの名前は_devで終わります。 詳細については、「基本モードのワークスペースと標準モードのワークスペースの違い」をご参照ください。
MaxComputeプロジェクトの名前を取得するには、次の手順を実行します。MaxComputeコンソールにログインします。 上部のナビゲーションバーで、リージョンを選択します。 左側のナビゲーションウィンドウで、[ワークスペース] > [プロジェクト] を選択します。 [プロジェクト] ページで、MaxComputeプロジェクトの名前を表示します。
doc_test_dev
access_id
必須
Alibaba CloudアカウントまたはRAMユーザーのAccessKey ID。
MaxComputeコンソールの右上隅にあるプロファイル画像をクリックし、AccessKey管理を選択してAccessKey IDを取得します。
なし
access_key
必須
AccessKey IDに対応するAccessKeyシークレット。
MaxComputeコンソールの右上隅にあるプロファイル画像をクリックし、AccessKey Managementを選択してAccessKeyシークレットを取得できます。
なし
end_point
必須
MaxComputeプロジェクトのエンドポイントを取得します。
このパラメーターは、MaxComputeプロジェクトの作成時に選択したリージョンとネットワーク接続方法に基づいて設定する必要があります。 異なるリージョンとネットワーク接続タイプに対応するエンドポイントの詳細については、「エンドポイント」をご参照ください。
重要このパラメーターの値は、MaxComputeトンネルではなくMaxComputeへのアクセスに使用されるMaxComputeのエンドポイントです。
無効なエンドポイントを指定した場合、MaxComputeプロジェクトにアクセスするとエラーが発生します。
http://service.cn-hangzhou.maxcompute.aliyun.com/api
log_view_host
選択可能
LogViewのURL (Uniform Resource Locator) 。 このURLを使用すると、ジョブの詳細な実行時情報を表示できます。 この情報は、ジョブエラーのトラブルシューティングに役立ちます。 値を http://logview.odps.aliyun.com に設定します。
説明このパラメーターを設定することを推奨します。 このパラメーターを設定しないと, ジョブエラーの原因を特定できません。
http://logview.odps.aliyun.com
https_check
選択可能
HTTPSアクセスを有効にするかどうかを指定します。 HTTPSアクセスが有効になっている場合、MaxComputeプロジェクトへのアクセス要求は暗号化されます。 有効な値:
True: HTTPSアクセスが有効です。
False: HTTPアクセスが有効です。
デフォルト値:False。
True
data_size_confirm
選択可能
入力データの最大サイズ。 (単位:GB) このパラメーターは任意の値に設定できます。 このパラメーターを100に設定することを推奨します。
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
選択可能
MaxCompute Tunnelのパブリックエンドポイント。 このパラメーターを設定しないと、トラフィックはMaxComputeが存在するネットワークに対応するTunnelエンドポイントに自動的にルーティングされます。 このパラメーターを設定すると、トラフィックは指定されたエンドポイントにルーティングされ、自動ルーティングは実行されません。
各リージョンとネットワークに対応するトンネルエンドポイントの詳細については、「エンドポイント」をご参照ください。
http://dt.cn-hangzhou.maxcompute.aliyun.com
set.<key>
選択可能
MaxComputeプロジェクトのプロパティ。
MaxComputeプロジェクトのプロパティの詳細については、「プロパティ」をご参照ください。
set.odps.sql.de cimal.odps2=true
説明上記のパラメーターの設定が有効であることを確認してください。 設定が無効であると、プロジェクト接続に失敗します。
MaxComputeクライアントの実行
次のいずれかの方法を使用して、MaxComputeクライアントを起動できます。
方法1: インストールパッケージのスクリプトファイルを使用してMaxComputeクライアントを起動する
MaxComputeクライアントのインストールディレクトリにあるbinフォルダーで、Windowsオペレーティングシステム (OS) 用のodpscmd.bat
ファイルまたはmacOS用のodpscmd
ファイルをダブルクリックして、MaxComputeクライアントを起動します。 次の図に示す情報が返された場合、MaxComputeプロジェクトは接続されています。
方法2: システムのCLIを使用してMaxComputeクライアントを起動する
システムのCLIで、MaxComputeクライアントのインストールディレクトリのbinフォルダーに移動し、Windows OSのodpscmd
コマンドを実行するか、macOSまたはLinux OSのsh odpscmd
コマンドを実行してMaxComputeクライアントを起動します。 次の図に示す情報が返された場合、MaxComputeプロジェクトは接続されています。
Ubuntuでsh odpscmd
コマンドを実行すると、エラーが返されます。 を実行できます。You can run the. /odpscmd
コマンドを実行して、MaxComputeクライアントを起動します。
システムのCLIを使用してMaxComputeクライアントを起動する場合、コマンドを実行するためのパラメーターを指定できます。 詳細は、「スタートアップパラメーターの指定」をご参照ください。
MaxComputeクライアントでの操作の実行
すべてのコマンドに関するヘルプ情報の取得
次のいずれかの方法を使用して、MaxComputeクライアントのコマンドに関するヘルプ情報を取得できます。
MaxComputeクライアントのコマンドに関するヘルプ情報の表示
すべてのコマンドに関するヘルプ情報を表示します。
odps@project_name>help; -- The preceding command is equivalent to the following command: odps@project_name>h;
関連コマンドのヘルプ情報を表示するキーワードを指定します。
例: テーブル操作に関連するコマンドに関するヘルプ情報を取得します。
odps@project_name>help table; -- The following results are returned: 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ジョブの課金方法の詳細については、「概要」をご参照ください。
システムのCLIですべてのコマンドに関するヘルプ情報を表示する
システムのCLIで、MaxComputeクライアントのインストールディレクトリにあるbinフォルダーに移動し、次のコマンドを実行してすべてのコマンドに関するヘルプ情報を表示します。 システムのCLIを使用してMaxComputeクライアントを起動する場合、コマンドで一連のパラメーターを指定できます。 これらのパラメーターの詳細については、「起動パラメーターの指定」をご参照ください。
...\odpscmd\bin>odpscmd -h
現在のログオンユーザーに関する情報の取得
CLIで次のコマンドを実行して、現在のログオンユーザーに関する情報を取得できます。
odps@project_name>whoami;
返された結果の説明:
Name: 現在のログインユーザーのアカウント。
Source IP: MaxComputeクライアントが存在するマシンのIPアドレス。
End_Point: MaxComputeのエンドポイント。
Project: MaxComputeプロジェクトの名前。
Schema: MaxComputeプロジェクトに関するスキーマ情報。
MaxComputeクライアントを終了
CLIで次のコマンドを実行して、MaxComputeクライアントを終了します。
odps@project_name>quit;
-- The preceding command is equivalent to the following command:
odps@project_name>q;
次に何をすべきか
MaxComputeクライアントにログインした後、MaxComputeプロジェクトでSQLコマンドを実行できます。 詳細については、「MaxComputeクライアントの使用」をご参照ください。
MaxComputeクライアントでサポートされているコマンド構文の詳細については、「一般的なコマンド」または「SQLコマンドと関数」をご参照ください。
よくある質問
odps_config.iniファイルの設定後、MaxComputeクライアントを起動すると、次の一般的なエラーが報告される場合があります。
エラーメッセージ:
no java found
考えられる原因
MaxComputeクライアントがデプロイされているマシンには、Java開発環境がインストールされていません。
解決策
MaxComputeクライアントがデプロイされているマシンにJava開発環境をインストールし、環境変数を指定します。
説明バージョン0.28.0以降のMaxComputeクライアントはJDK 1.9をサポートしています。 0.28.0より前のバージョンのMaxComputeクライアントは、JDK 1.8のみをサポートします。
エラーメッセージ:
エラー: メインクラスcom.aliyun.openservices.odps.console.ODPSConsoleが見つかりません
考えられる原因
MaxComputeクライアントインストールパッケージは2回ダウンロードできます。 パッケージが2回目にダウンロードされると、ディレクトリの名前は自動的に
odpscmd_public (1)
に変更されます。 ディレクトリ名にスペースなどの無効な文字が含まれています。 その結果、システムがディレクトリを誤って識別した場合、エラーが返されます。解決策
ディレクトリ名からスペースなどの不正な文字を削除します。
エラーメッセージ:
プロジェクト '<projectname>' へのアクセスに失敗しました: ODPS-0420111: プロジェクトが見つかりません-'<projectname>' 。
考えられる原因
odps_config.ini設定ファイルのプロジェクト名が無効です。
解決策
MaxComputeコンソールにログインします。 上部のナビゲーションバーで、リージョンを選択します。 左側のナビゲーションウィンドウで、[ワークスペース] > [プロジェクト] を選択します。 [プロジェクト] ページで、MaxComputeプロジェクトの名前を取得します。 次に、odps_config.iniファイルを変更します。
エラーメッセージ:
プロジェクト '<projectname>' へのアクセスに失敗しました: ODPS-0420095: アクセス拒否-許可に失敗しました [4002] 、プロジェクト <projectname> に存在しません。
考えられる原因
AccessKeyペアが使用されているAlibaba CloudアカウントまたはRAMユーザーは、MaxComputeプロジェクトに追加されません。
解決策
プロジェクト所有者に連絡して、Alibaba CloudアカウントまたはRAMユーザーをプロジェクトに追加してください。 詳細については、「Alibaba Cloudアカウントの追加 (プロジェクトレベル) 」または「RAMユーザーの追加 (プロジェクトレベル) 」をご参照ください。
エラーメッセージ:
Accessing project '<projectname>' failed: { "Code": "InvalidProjectTable", "message": "The specified project or table name is not valid or missing."}
orAccessing project '<projectname>' failed: connect timed out
考えられる原因
end_point
パラメーターの値が無効です。 たとえば、オンプレミスマシンでMaxComputeクライアントを使用してインターネット経由でMaxComputeプロジェクトに接続する場合、Alibaba cloudのクラウド製品相互接続ネットワークのエンドポイントまたはMaxCompute Tunnelのエンドポイントを入力するとします。解決策
end_pointパラメーターを、接続するプロジェクトのリージョンとネットワーク環境に一致するエンドポイントに設定します。 [エンドポイント] からエンドポイントを取得できます。
説明end_point
パラメーターの値は、MaxComputeのエンドポイントであり、MaxCompute TunnelではなくMaxComputeへのアクセスに使用されます。
エラーメッセージ:
Accessing project '<projectname>' failed: <endpoint>
考えられる原因
end_point
パラメーターの値が無効です。 例えば、http://service.cn-hangzhou.maxcompute.aliyun.com/api
のcnが誤ってch
として入力される。解決策
プロジェクトのリージョンとネットワーク環境に一致するエンドポイントを [エンドポイント] からコピーします。 手動でエンドポイントを入力しないことを推奨します。
起動パラメーターの指定
システムのCLIで、コマンドを実行するための一連のパラメーターを指定できます。 次のコードは、これらのパラメーターの使用方法を示しています。
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
次の表に、起動パラメーターを示します。
パラメーター | 説明 | サンプルコマンド |
| MaxComputeクライアントのすべてのコマンドに関するヘルプ情報を取得します。 |
|
| 設定ファイルodps_config.iniが格納されているディレクトリを指定します。 デフォルトのディレクトリは |
|
| アクセスするMaxComputeプロジェクトの名前を指定します。 |
|
| MaxComputeのエンドポイントを指定します。 MaxComputeのエンドポイントの詳細については、「エンドポイント」をご参照ください。 |
|
| 特定の場所からステートメントを実行します。 | 最初の2つのステートメントを無視し、3番目のステートメントから開始します。 |
| ジョブの実行に失敗した後に許可される再試行の回数を指定します。 |
|
| 読み取るファイルを指定します。 |
|
| 実行するコマンドを指定します。 |
|
odpscmd -e <SQL statement>
コマンドの動的戻り値は、シェルウィンドウで実行されるシェルスクリプトまたはWindowsのコマンドプロンプトで呼び出すことができます。 シェル変数は戻り値を取得し、後続のジョブで戻り値を使用します。 このシナリオでは、フィールド値のみが必要です。 ランタイム情報やヘッダーなどのその他の情報は返されません。 シェル呼び出しを容易にするには、odps_config.iniファイルのuse_instance_tunnelパラメーターをfalseに設定して、InstanceTunnelを無効にする必要があります。 set odps.sql.select.output.format={"needHeader":false,"fieldDelim":""};
コマンドを実行して、ヘッダーの表示を無効にします。
たとえば、nohaderという名前のテーブルには、1列3行のデータが含まれています。 フィールド値は1、2、3です。 次のコマンドを実行して、クエリ結果の標準出力を宛先ハンドルにリダイレクトした後、出力にはフィールド値のみが含まれます。
-- Run the following command in the Command Prompt in Windows:
...\odpscmd\bin>odpscmd -e "set odps.sql.select.output.format={""needHeader"":false,""fieldDelim"":"" ""};select * from noheader;" >D:\test.txt
-- The returned results are stored in the test.txt file in drive D.
-- Run the following command in a shell window:
/Users/.../odpscmd/bin/odpscmd -e "set odps.sql.select.output.format={\"needHeader\":false,\"fieldDelim\":\"\"};select * from noheader;" >/Users/A/temp/test.txt
-- The returned results are stored in the test.txt file in the /Users/A/temp directory.
-- The following results are returned:
1
2
3
バージョン更新
次の表に、MaxComputeクライアントの最新バージョンの更新を示します。 詳細については、特定のバージョンのURLをクリックしてください。
バージョン | 操作タイプ | 説明 |
新機能 |
| |
新機能 |
| |
新機能 | JSONデータ型とTIMESTAMP_NTZデータ型は、MaxComputeでサポートされています。 | |
新機能 |
| |
修正された問題 | log4jへの依存関係は削除されます。 | |
新機能 | プロジェクトデータはスキーマで保存できます。 詳細については、「スキーマ関連の操作」をご参照ください。 | |
新機能 | 複雑なデータ型のデータは、Tunnelコマンドを実行してアップロードまたはダウンロードできます。 | |
拡張機能 |
| |
新機能 | 外部プロジェクトを作成し、Data Lake Formation (DLF) に接続できます。 これは、データレイクハウス機能の実装に役立ちます。
| |
修正された問題 | TIMESTAMPタイプのデータのナノ秒部分が誤って処理される問題が修正されました。 |