Linode API
Linode は開発者フレンドリーなクラウドであり、CLI や API で制御できます。Linode API を使う上で、Postman を使うと簡単に動作確認できるので紹介します。
Linode とは
Linode についてはこちらを参照してください。
Postman とは
Postman は API を構築し利用するためのプラットフォームです。API のテストや検証の管理が容易に行なえます。Web 版とアプリケーション版があり、無償で始められます。
Linode API の Postman コレクション
Linode API のセットは Postman コレクションの形で共有されています。こちらを使えば、視覚的にも容易に API の動作確認ができます。
https://www.postman.com/api-evangelist/workspace/linode/overview
自分の環境を作成するためのフォーク
フォークとは、コピーのようなものです。プライベート環境にフォークすれば、自分専用の環境を用意できます。コード管理でいえば、新しいブランチができ、個別に管理できるようなものです。Postman ではコレクション、環境などをフォークすることができます。実行する前に Postman のアカウントを取得してください。
フォーク元を選択
地球儀のようなマークがある共有されているワークスペース (Linode) からコレクション(Linode)に対して Create a fork します。同じ名前がつけられているので混乱するかもしれませんが、すぐに慣れると思います。
フォーク先のワークスペースの選択
自身のプライベートな環境にフォークされるワークスペースを選択します。ワークスペースは事前に作成しておく必要があります。
プライベートなコレクションの作成完了
次に認証情報の設定をします。
Linode ポータルからトークンを取得する
Linode ポータルにログインすると、API トークンを発行できます。
Linode API の Getting Started にトークンについて書かれていますので参照してください。
Create Token すると Personal Access Token （トークン）が作成されます。このトークンはその後、見えなくなりますので、セキュアに記録しておきましょう。
Postman にトークンを設定する
Postman では設定を階層で管理できます。共通設定を親に設定しておき、子は引き継ぐ設定をすると管理が楽になります。親の階層にトークンを設定します。各エンドポイントに対して個別に設定することも可能です。
Type に OAuth 2.0 を選択、Access Token に Linode Portal で取得したトークンを入力します。
Linode API を使ってみる
本例では、事前に作成済みのLinode仮想マシンインスタンスがすでにあるので、API で情報を取得できるか確認してみます。もし、仮想マシンを作成していない場合は、regions > List Regions などの誰でも実行できる Linode のリージョン情報の取得を試みるとよいと思います。
Linode > instances > List Linodes
Authorization の設定
Authorization の設定は親から引き継ぐので、Inherit auth from p... (p はおそらく Parent の P だと思います）を選択します。一番上の階層でトークンの設定をしていますので、その間の中間の親に対しても同様に Inherit の設定をしておく必要があります。設定を Save しておかないと反映されずに、あれっと思うこともありますので、設定の保存をするように気をつけてください。
Send を押してリクエストを送信
API エンドポイントに対して、リクエストを送ります。{{baseUrl}} は親の Variables (変数）ですでに https://api.linode.com/v4 などと設定されています。
次のように JSON ファイルが見えたら成功です。
本例では GET メソッドを使っていますが、Postman は Post メソッドなどの扱いも簡単にできるのが便利です。
グローバル変数を使ってトークンの扱いをセキュアにする
トークンの扱いは常に注意するべきです。上記の設定ではトークンの文字列が容易にディスプレイに表示されてしまいますので、Postman のグローバル環境変数を使ってよりセキュアに表示します。
Postman には環境変数の概念があり、いくつかのスコープで変数が設定できます。変数のタイプで、Secret タイプを設定できます。グローバル環境変数を使うと、下図のように Collections とは別に管理することができます。
Linode Environment という名前の Global 環境変数を作成し、その中で linode_access_token という名前で Variable (変数）を作成します。 Initial Value には Linode Portal から取得した API Token の文字列が入っていますが、Type を default から secret にすることで トークンの文字列がマスクされます。
文字列を表示させるためには、目に斜め線が入ったアイコンをクリックするというひと手間が増えます。
コレクションを共有してもグローバル環境変数の値は共有はされないと思っていたのですが、コレクションの Export/Import では変数の文字列がインポート先に表示されるようですので、Export したファイルの共有は注意が必要です。
コレクションの Authorization でグローバル変数をセットする
先程までは Access Token にトークンの生の文字列を入れていましたが、グローバル変数に変えます。{{linode_access_token}} のように設定した変数を {{}} で囲みます。
Global 環境変数の選択
Postman UI の右上に環境変数を選択するドロップダウンリストがあります。Global 環境変数を作成すると選択できるようになります。
マウスをグローバル変数の上にもってくると変数がポップアップします。secret として定義された変数は目のアイコンをクリックすることで文字列が表示できます。
グローバル変数の使って API をコールする
先程までは Authorization ヘッダーの文字列が常に表示されている状態でしたが、今は {{linode_access_token}} という文字列が見えて、ポップアップしてから目のアイコンをクリックしないとトークンの文字列が見えないようになりました。
実際にはリクエストを実行したあと、文字列がそのまま表示されてしまうようですが、グローバル環境変数を切り替えると直後にまたリセットされます。
まとめ
Postman を利用すると Linode API の動作を容易に学べます。
関連記事
アカマイ・テクノロジーズ合同会社が管理している Qiita ページでは Linode など開発者向けの記事を記載しております。