すべてのプロダクト
Search
ドキュメントセンター

MaxCompute:MaxComputeクライアント (odpscmd)

最終更新日:Dec 05, 2024

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クライアントをインストールして設定するには、次の手順を実行します。

  1. GitHubからMaxComputeクライアントインストールパッケージをダウンロードします。

    説明
    • 上記のリンクをクリックすると、表示されるページで最新バージョンのMaxComputeクライアントインストールパッケージodpscmd_public.zipをダウンロードできます。

    • 上記のリンクをクリックしてもパッケージをダウンロードできない場合は、odpscmd_public_0.48.0.zipをクリックしてパッケージをダウンロードします。 ダウンロードの失敗を解決する方法の詳細については、検索エンジンを使用して関連ソリューションを検索することをお勧めします。

  2. ダウンロードしたパッケージを解凍し、bin,conf,lib、およびpluginsフォルダーを作成します。

  3. 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プロジェクトは接続されています。image.png

方法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クライアントを起動します。

image.png

システムの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> に存在しません。

  • エラーメッセージ: Accessing project '<projectname>' failed: { "Code": "InvalidProjectTable", "message": "The specified project or table name is not valid or missing."} or Accessing 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

次の表に、起動パラメーターを示します。

パラメーター

説明

サンプルコマンド

-- 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のエンドポイントを指定します。 MaxComputeのエンドポイントの詳細については、「エンドポイント」をご参照ください。

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

-k

特定の場所からステートメントを実行します。 nが0以下の値に設定されている場合、実行は最初のステートメントから開始されます。 複数のステートメントはセミコロン (;) で区切ります。

最初の2つのステートメントを無視し、3番目のステートメントから開始します。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. CLIで、MaxComputeクライアントのインストールディレクトリにあるbinフォルダーに移動し、次のコマンドを実行します。

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

-e

実行するコマンドを指定します。

odpscmd -e "select * from sale_detail;"

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をクリックしてください。

バージョン

操作タイプ

説明

v0.47.0-public

新機能

  • HTTPコマンド: HTTPコマンドは、ユーザーが現在のユーザーとしてHTTPリクエストを簡単に開始できるように追加されています。

  • セッション持続性変数: セッション持続性を管理するために、keep-Session-variablesスタートアップパラメーターが追加されました。 このパラメーターを使用すると、useコマンドを実行してプロジェクトを切り替えても、以前に設定されたセッション変数は削除されません。 たとえば、set a=bの設定は、プロジェクトを切り替えても保持されます。

  • Tunnelコマンドのアップグレード:

    • -qnオプションがTunnel UploadおよびTunnel Downloadコマンドに追加され、MaxComputeへのアクセスに使用されるTunnelクォータの名前が指定されます。

    • Tunnel Uploadコマンドに -dfpオプションが追加され、アップロードするDATETIMEテキストの形式が指定されます。

    Tunnelコマンドの詳細については、「Tunnelコマンド」をご参照ください。

v0.46.5-public

新機能

  • USE機能は、以前に設定されたセッションレベルのフラグパラメーターを保持するためにサポートされています。

  • Tunnelコマンドのアップグレード

    • Tunnel Upsertコマンドがサポートされています。 詳細については、「Tunnelコマンド」をご参照ください。

    • 行レベルのアクセス制御を持つテーブルをダウンロードすると、データフィルタリングSQL文の実行情報が返されます。

v0.45.1-public

新機能

JSONデータ型TIMESTAMP_NTZデータ型は、MaxComputeでサポートされています。

v0.43.2-public

新機能

  • 外部ボリュームを作成できます。

  • SHOWコマンドを使用して、MaxComputeプロジェクトの特定のルールを満たすすべての組み込み関数または組み込み関数を照会できます。

v0.40.10-public

修正された問題

log4jへの依存関係は削除されます。

v0.40.8-public

新機能

プロジェクトデータはスキーマで保存できます。 詳細については、「スキーマ関連の操作」をご参照ください。

v0.37.5-public

新機能

複雑なデータ型のデータは、Tunnelコマンドを実行してアップロードまたはダウンロードできます。

v0.37.4-public

拡張機能

  • コマンドに関するヘルプ情報が最適化されています。

  • desc extended partitionステートメントは、パーティションのプロパティに関する詳細情報を返します。

v0.36.0-public

新機能

外部プロジェクトを作成し、Data Lake Formation (DLF) に接続できます。 これは、データレイクハウス機能の実装に役立ちます。

修正された問題

TIMESTAMPタイプのデータのナノ秒部分が誤って処理される問題が修正されました。