こんにちは。
SBクラウド ソリューションアーキテクトの吉村です。
この記事は Alibaba Cloud Advent Calendar 2019 １日目の記事になります。
今日は Alibaba Cloud CLI の基本的な使い方と Tips をいくつかご紹介します。
なお、こちらの記事は国際サイト(www.alibabacloud.com)を基準に書いています。
私のローカル環境は Mac です。
目次
- 利用する前に注意点
- 参考情報など
- インストールについて
- OpenAPI Explorer を活用する
- リージョンの指定は --RegionId ではなく --region を利用する
- json の処理を jq で行う
- よく使うAPIリクエストをコマンドエイリアスにする
- --pager オプションで全てのページを表示する
- シェルスクリプトで全てのリージョンを一括で調べる
- まとめ
利用する前に注意点
Alibaba Cloud CLI はGoバージョンとPythonバージョンがあります。
- Go バージョン (ドキュメント)
- Python バージョン(ドキュメント)
Goバージョンが現行で開発されているために、こちらの利用をお勧めします。
2つのバージョンがあることで、
- ドキュメントを読む時に混乱する
- パラメーターの互換性がなかったりすので、エラーになるケースがある
という問題が起こります。
Go バージョンだと aliyun , Python バージョンだと aliyuncli となっているので、Alibaba Cloud CLI の記事を読む時にはどちらのバージョンについて書かれているか確認した上で読みましょう。
また、公式の日本語ドキュメントだと Go バージョンは何も情報がないので、Python バージョンしかないと勘違いしてしまいがちです。
気をつけましょう。
現時点で Alibaba Cloud CLI を調べる際には、国際サイトのドキュメントで確認するようにお願いします。日本語ドキュメントの対応はSBクラウドで頑張っていますので、もうしばらくお待ちください。
大切なことなのでもう1度書きますが、Alibaba Cloud CLI は Go バージョン を利用して、ドキュメントは国際サイトで確認してください。
参考情報など
Alibaba Cloud CLI を利用する際に参考になる情報を整理しておきます。
サイト 内容 Alibaba Cloud help Alibaba Cloud CLI の公式ドキュメント
GitHub Alibaba Cloud CLI の GitHub レポジトリ
OpenAPI Explorer Alibaba Cloud CLI や SDK の API デバックを行うためのツール
AliEaters CLI 支部 Alibaba Cloud ユーザー会 AliEaters で CLI を勉強するコミュニティがあります
その他にも、Qiita で書かれている方や、Alibaba Cloud 国際サイト Blog や 中国サイトBlog にも情報があります。
しかし情報がまだまだ少なかったり、中国語なので分かりにくかったりします。
是非皆さんも自分の知っているノウハウを共有してみてください。
インストールについて
本記事では割愛しますが、GitHub の説明 を参考にしてください。
日本語だと外部の記事ですが Qiita のこちらの記事が参考になります。
qiita.com
OpenAPI Explorer を活用する
Alibaba Cloud CLI を使いこなす上で、OpenAPI Explorer は非常に有効なツールです。
是非とも活用できるようになりましょう。
以下の図のように、APIのリクエストを調べたり、レスポンスエラーのデバッグを行うことができます。
例えば 私が Alibaba Cloud CLI を利用する時には、以下の流れです。
- aliyun help を実行して、使いたいプロダクトのAPI大枠を調べる
- OpenAPI Explorer を開いて、対象のAPIを選択する
- OpenAPI Explorer の Document で各パラメーターを読む
- OpenAPI Explorer でAPIの各パラメーターを入力して、やりたいコマンドを作成
- OpenAPI Explorer の CloudShell で試してみる
具体的に説明すると。
1. aliyun help を実行して、使いたいプロダクトのAPI大枠を調べる
# aliyun help で利用できるプロダクトを調べる $ aliyun --help Alibaba Cloud Command Line Interface Version 3.0.29 (省略) Products: aegis Server Guard agency agency alidns Alibaba Cloud DNS arms Application Real-Time Monitoring Service batchcompute BatchCompute bssopenapi bssopenapi (省略) # 「aliyun プロダクト名 help」 で、特定のプロダクトで利用できるAPIを調べる $ aliyun ecs help Alibaba Cloud Command Line Interface Version 3.0.29 Usage: aliyun Ecs <ApiName> --parameter1 value1 --parameter2 value2 ... Product: Ecs (Elastic Compute Service) Version: 2014-05-26 Link: https://help.aliyun.com/api/ecs Available Api List: AcceptInquiredSystemEvent ActivateRouterInterface AddBandwidthPackageIps (省略) # 「aliyun プロダクト名 APIリクエスト名 help」 で、各プロダクトのAPIリクエストで必要になるパラメーターまで調べる $ aliyun ecs AcceptInquiredSystemEvent help Alibaba Cloud Command Line Interface Version 3.0.29 Product: Ecs (Elastic Compute Service) Link: https://help.aliyun.com/api/ecs/AcceptInquiredSystemEvent.html Parameters: --EventId String Required --RegionId String Required --SourceRegionId String Optional
2. OpenAPI Explorer を開いて、対象のAPIを選択する
CLI のヘルプ情報だけではそのAPIについて調べるのは限界があります。
そこで OpenAPI Explorer で詳しく調べて、効率的にAPIリクエストを作っていきましょう。
OpenAPI Explorer にアクセスする
利用したい対象のAPIを検索する
対象のAPIリクエストで必要なパラメーターが分かります。
今回の例だと*印の2つのパラメーターが必須で必要です。
3. OpenAPI Explorer の Document で各パラメーターを読む
2種類のパラメーターが必要なことが分かりましたが、どんな値を入力すべきかまだ分かりません。
そこで Document で確認をします。
ここには、必要なパラメーターの入力値の説明や例、レスポンスの例が書かれています。
4. OpenAPI Explorer でAPIの各パラメーターを入力して、コマンドを作成
Document の説明を元にAPIリクエストを作っていきましょう。
こちらのフィールドにパラメーターを入力
そうすると、右側にAPIリクエストのコマンドが作成されます。
これで完成です。
なお、各SDKでのAPIリクエストも同時に作成されています。
5. OpenAPI Explorer の CloudShell で試してみる
今できたCLIのAPIリクエストコマンドをコピペして試してもよいですが、CloudShell を利用するとその場で試すことができます。
作成した CLI コマンドの右上に表示されている CloudShell のアイコンをクリック。
画面下にCloudShellが起動します。
ストレージスペースが必要か聞かれますが、不要なので skip を選択。
以下の例ではレスポンスがエラーになってしまいましたが、エラー
の原因を調べながらデバッグできるため便利です。
以上が OpenAPI Explorer を利用した Alibaba Cloud CLI のコマンド作成の手順でした。
リージョンの指定は --RegionId ではなく --region を利用する
Alibaba Cloud のほとんどの API リクエストは、リージョンの指定が必須になっています。
どのリージョンに対してAPIリクエストをするかを指定しないといけません。
リージョンを指定したことがない、という方は指定が省略されているからです。
デフォルトでは、aliyun configure で設定した default region が勝手に入力されます。
例えば以下の例だと、ap-northeast-1(東京)リージョンがデフォルトリージョンになっているため、リージョンを指定しないと東京リージョンにAPIリクエストすることになります。
$ aliyun configure get -p int
{
"name": "int",
"mode": "AK",
"access_key_id": "****************",
"access_key_secret": "****************",
"sts_token": "",
"ram_role_name": "",
"ram_role_arn": "",
"ram_session_name": "",
"private_key": "",
"key_pair_name": "",
"expired_seconds": 0,
"verified": "",
"region_id": "ap-northeast-1",
"output_format": "json",
"language": "en",
"site": "china",
"retry_timeout": 0,
"retry_count": 0
}
そして、実際にリージョンを指定する際には、
--RegionId ではなく --region パラメーターを利用することにご注意ください。
例えばOpenAPI Explorer でシンプルなAPIリクエストである 「DescribeRegions」を参考に見てみましょう。
これはとてもシンプルなAPIリクエストで、Alibaba Cloud のリージョンを調べるものです。
必須パラメーターも特になく、シンプルなリクエストで動きます。
$ aliyun ecs DescribeRegions
{
"RequestId": "1977911B-DB3E-4C27-A9B3-5352FE228D77",
"Regions": {
"Region": [
{
"RegionId": "cn-qingdao",
"RegionEndpoint": "ecs.aliyuncs.com",
"LocalName": "华北 1"
},
{
(省略)
一方で、OpenAPI Explorer で自動生成されたコマンドはこのようになっています。
aliyun ecs DescribeRegions --RegionId cn-hangzhou
これを CloudShell で実行すると、エラーになります。
エラーの内容は、
--RegionId パラメーターは間違っているから、ドキュメント読んでください。
というものです。
実は自動生成してくれた --RegionId パラメーターは間違っていて、リージョンを指定する場合は --region パラメーターが正解になります。
--Region を --region に変えてあげると、リクエストが成功してレスポンスが返ってきます。
json の処理を jq で行う
Alibaba Cloud CLI のレスポンスは json 形式になります。
大量のデータが返ってくると目で読むのは辛いので、他のパブリッククラウドと同じく jq で処理をするのが一般的です。
jq については私が書くよりも他の人が書いている記事がいっぱいあるので、検索して jq をインストールしましょう。
ちなみに、CloudShell には最初から jq がインストールされているので使えます。
よく使うAPIリクエストをコマンドエイリアスにする
先程のリージョン確認するコマンドはよく利用すると思います。
上海リージョンのリージョンIDって何だっけ？
と思った時にすぐに確認がしたいです。
頻繁に調べるものは自分の環境でサクッと出せるようにしておくと便利です。
例えば以下の例を見てみてください。
# DescribeRegions の結果から、jq で、リージョンの名前(日本語)とリージョンIDを抽出する $ aliyun ecs DescribeRegions --AcceptLanguage ja | jq -r -c '.Regions.Region[]| [.LocalName, .RegionId]' ["中国北部（青島）","cn-qingdao"] ["中国北部（北京）","cn-beijing"] ["中国北部（張家口）","cn-zhangjiakou"] ["中国北部（フフホト）","cn-huhehaote"] ["中国東部（杭州）","cn-hangzhou"] ["中国東部（上海）","cn-shanghai"] ["中国南部（深セン）","cn-shenzhen"] ["中国西南部（成都）","cn-chengdu"] ["中国（香港）","cn-hongkong"] ["日本（東京）","ap-northeast-1"] ["シンガポール","ap-southeast-1"] ["オーストラリア（シドニー）","ap-southeast-2"] ["マレーシア（クアラルンプール）","ap-southeast-3"] ["ジャカルタ（インドネシア）","ap-southeast-5"] ["インド（ムンバイ）","ap-south-1"] ["米国（バージニア）","us-east-1"] ["米国（シリコンバレー）","us-west-1"] ["イギリス (ロンドン)","eu-west-1"] ["UAE（ドバイ）","me-east-1"] ["ドイツ（フランクフルト）","eu-central-1"]
このコマンドは頻繁に使いそうですね。
それなら、bash にエイリアスで登録しておくと便利です。
# .bashrc に alias を書く $ vi ~/.bashrc #以下のように、aliyun-regions コマンドエイリアスを追記 ## aliyun-cli bin alias aliyun-regions="aliyun ecs DescribeRegions --AcceptLanguage ja | jq -r -c '.Regions.Region[]| [.LocalName, .RegionId]'" # .bashrc を終了して、再読み込み $ source ~/.bashrc # bash で aliyun-regions が出てくる $ aliyun-regions
便利になりますね。
--pager オプションで全てのページを表示する
Alibaba Cloud CLI のレスポンスの一部には、ページの概念があります。
ページのデフォルトでは1ページ当たり10個のオブジェクトが返ってくるので、11個目以降のオブジェクトは返ってこないです。
例えば以下の VPC を調べるコマンドを例に見てみましょう。
$ aliyun vpc DescribeVpcs
{
"PageNumber": 1,
"Vpcs": {
"Vpc": [
{
"VpcName": "****-vpc",
"Description": "",
"IsDefault": false,
"CenStatus": "Detached",
"NatGatewayIds": {
"NatGatewayIds": []
},
(省略)
},
"TotalCount": 59,
"PageSize": 10,
"RequestId": "23ED183E-209D-4161-B7CF-32E15DEFF28C"
}
上のレスポンス結果では、VPCは全部で59個あるけど、1ページ目の10個のみ表示している事が分かります。
しかし、これだと一気に調べたい時には不便です。
そこで、一気に調べたい時には、 --pager オプションを利用します。
--pager オプションは表示するページ番号を指定したり、1ページ当たりの表示するオブジェクト数を指定したりするのですが、そのまま --pager だけの場合には全てを表示することになります。
先程の例で見てみましょう。
$ aliyun vpc DescribeVpcs --pager
{
"Vpcs": {
"Vpc": [
{
"CenStatus": "Detached",
"CidrBlock": "192.168.0.0/16",
"CreationTime": "2019-11-18T06:26:57Z",
"Description": "",
"Ipv6CidrBlock": "",
"IsDefault": false,
"NatGatewayIds": {
"NatGatewayIds": []
},
(省略)
今度はページ数やページ辺りの個数の制限がなく、全てのオブジェクトが返ってきました。
シェルスクリプトで全てのリージョンを一括で調べる
最後の Tipsです。
先程の DescribeRegions のようにどこのリージョンでも同じレスポンスが返ってくるものなら良いですが、DescribeVpcs のように各リージョン毎にレスポンスが異なる場合には全てのリージョンを１つずつ調べないといけません。
しかし、それは面倒です。
そういう場合にはシェルスクリプトをうまく利用しましょう。
まずは1つのリージョンでVPCを調べるコマンドを作ります。
# ap-northeast-1(東京)リージョンのVPCを全部表示して、jqで、VPC名とVPC ID を抽出 $ aliyun vpc DescribeVpcs --region ap-northeast-1 --pager | jq -r -c '.Vpcs.Vpc[]|[.VpcName, .VpcId]'
--region の 部分を繰り返しで実行すれば、全リージョンを一気に調べられそうです。
以下の形でできます。
# 全リージョンを調べて変数に入れる。先程のコマンドで --region の指定を変数にして実行。これを繰り返す。
$ for region in $( aliyun ecs DescribeRegions | jq -r '.Regions.Region[].RegionId' )
do
echo "#$region"
reg=$( echo $region )
echo '---'
for vpc in $( aliyun vpc DescribeVpcs --region $reg --pager | jq -r -c '.Vpcs.Vpc[]?|[.VpcName, .VpcId]' )
do
echo $vpc
done
echo ''
done
#cn-qingdao
---
#cn-beijing
---
["****-vpc","vpc-****"]
["****-vpc","vpc-****"]
#cn-zhangjiakou
---
(省略)
このように表示されます。
例えば自分のVPCだけ調べたい時にはこれで条件を grep などで抽出すれば、簡単そうですね。
また、こういう場合には bash のエイリアスにするのではなく、シェルスクリプトのファイルにして保存しておくのが便利そうですね。
まとめ
以上です。
今回は Alibaba Cloud CLI の基本的な使い方をご紹介しました。
次回は便利なコマンド集をご紹介するか、aliyun-cli の GitHub に Pull リクエストするなど試したいです。
明日の Alibaba Cloud Advent Calendar もお楽しみに！