MaxCompute:odpscmd を使用した MaxCompute への接続

課金

MaxCompute クライアントを使用してプロジェクトに接続する操作は無料ですが、クライアント経由で実行される操作は MaxCompute の課金対象となります。たとえば、SQL クエリを送信すると計算リソースが消費され、データを書き込むとストレージ領域が使用されます。これにより、計算およびストレージコストが発生します。MaxCompute の課金に関する詳細については、「課金対象項目と課金方法」をご参照ください。

odpscmd のインストールと構成

odpscmd v0.27.0 以降は MaxCompute 2.0 のデータ型をサポートしています。これらのデータ型を使用することを推奨します。サポートされているデータ型の一覧については、「データ型 (V2.0)」をご参照ください。

操作手順

1. odpscmd インストールパッケージ (GitHub) をダウンロードします。

   説明

   • リリースページにアクセスし、最新バージョンの odpscmd インストールパッケージ (odpscmd_public.zip) をダウンロードします。

   • GitHub のリンクからパッケージをダウンロードできない場合は、odpscmd インストールパッケージ (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	はい	Alibaba Cloud アカウントまたは RAM ユーザーの AccessKey ID。AccessKey ID は AccessKey 管理 ページから取得します。	N/A
   access_key	はい	AccessKey ID に対応する AccessKey Secret。	N/A
   end_point	はい	MaxCompute サービスのエンドポイント。 ご利用の MaxCompute プロジェクトが配置されているリージョンおよびネットワーク接続タイプに基づいてエンドポイントを構成する必要があります。リージョンおよびネットワークタイプ別のエンドポイントの一覧については、「エンドポイント」をご参照ください。 重要 エンドポイントは MaxCompute サービスに接続し、トンネルエンドポイントは MaxCompute Tunnel サービスに接続します。ここでは MaxCompute サービスのエンドポイントを指定してください。 エンドポイントの構成が誤っていると、アクセスエラーが発生します。	http://service.cn-hangzhou.maxcompute.aliyun.com/api
   log_view_host	いいえ	LogView URL。このパラメーターの構成を推奨します。構成しない場合、ジョブ失敗の原因を迅速に特定できなくなる可能性があります。 この URL を使用して、ジョブのランタイム情報を詳細に表示し、エラーをトラブルシューティングできます。固定値は http://logview.odps.aliyun.com です。	http://logview.odps.aliyun.com
   https_check	いいえ	MaxCompute プロジェクトへのアクセスリクエストを HTTPS で暗号化するかどうかを指定します。有効な値： True：HTTPS を有効にします。 False：HTTP を使用します。 デフォルト値は False です。	True
   data_size_confirm	いいえ	入力データサイズの最大値 (単位：GB)。上限はありません。推奨値：100。	100
   update_url	いいえ	このパラメーターは将来の使用のために予約されています。	N/A
   use_instance_tunnel	いいえ	InstanceTunnel を使用して SQL 実行結果をダウンロードするかどうかを指定します。有効な値： True：InstanceTunnel を使用して SQL 実行結果をダウンロードします。 False: InstanceTunnel を使用して SQL 実行結果をダウンロードしないでください。 デフォルト値は False です。	True
   instance_tunnel_max_record	いいえ	SQL 実行結果の最大レコード数。use_instance_tunnel が True に設定されている場合、このパラメーターを構成する必要があります。最大値は 10,000 です。	10000
   tunnel_endpoint	いいえ	Tunnel サービスのパブリックエンドポイント。 このパラメーターを構成しない場合、Tunnel は自動的に MaxCompute サービスのネットワークに対応するトンネルエンドポイントにリクエストをルーティングします。 トンネルエンドポイントを構成した場合、Tunnel はその値を使用し、自動ルーティングを行いません。 リージョンおよびネットワークタイプ別のトンネルエンドポイントの一覧については、「エンドポイント」をご参照ください。	http://dt.cn-hangzhou.maxcompute.aliyun.com
   set.<key>	いいえ	MaxCompute プロジェクトのプロパティを設定します。 プロパティの詳細については、「プロパティ一覧」をご参照ください。	set.odps.sql.decimal.odps2=true

   上記の情報を正しく構成してください。構成ミスにより、プロジェクトへの接続が失敗する可能性があります。

MaxCompute クライアントの起動

1. MaxCompute プロジェクトの作成を行います。

2. RAM ユーザーとして MaxCompute クライアントを使用する場合は、Alibaba Cloud アカウントを使用して RAM ユーザーを対象の MaxCompute プロジェクトに追加します。ユーザーの追加方法の詳細については、「他のユーザーへの権限付与」をご参照ください。

3. 次のいずれかの方法で MaxCompute クライアントを起動します。

   スクリプトファイル

   MaxCompute クライアントのインストールディレクトリにある bin ディレクトリで、Windows の場合は odpscmd.bat を、macOS の場合は odpscmd をダブルクリックして MaxCompute クライアントを起動します。次の出力が表示されると、MaxCompute プロジェクトへの接続が成功しています。

   odpscmd
   Aliyun ODPS Command Line Tool
   Version 0.4xxx
   @Copyright 2020 Alibaba Cloud Computing Co., Ltd. All rights reserved.
   Connecting to http://service.xxx.maxcompute.aliyun.com/api, project: xxx
   Executing predefined SET command: SET odps.sql.hive.compatible=true
   OK
   Endpoint: http://service.xxx.maxcompute.aliyun.com/api
   Project: xxx
   Schema: default
   Quota: default in region N/A
   Timezone: Asia/Shanghai
   Connected!

   コマンドラインウィンドウ

   コマンドラインウィンドウで、MaxCompute クライアントのインストールディレクトリにある bin ディレクトリに移動します。Windows では odpscmd を、Linux または macOS では sh odpscmd を実行して 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

シェルまたは Windows コマンドラインで、odpscmd -e <SQL_statement> を使用して、動的な戻り値をシェル変数にキャプチャし、後続のジョブで使用できます。このシナリオでは、戻り値にランタイム詳細やヘッダーなどの余分な情報が含まれてはなりません。シェルスクリプトを容易にするために、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 に保存されます。
--シェル：
/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

バージョン履歴

次の表に、odpscmd の最近の更新内容を示します。詳細については、特定のバージョンのリンクをクリックしてください。

odpscmd のバージョンおよびリリースノートの完全な一覧については、GitHub をご参照ください。