👀

Postmanを使ってREST APIで物理サーバーを操作する（実践編）

2022/08/29に公開

rest

はじめに

最近（といってももはやここ10年弱くらい）の物理サーバーがREST APIで操作できるようなっているのご存知でしたか？メーカー側も世の中のトレンドにあわせて便利に使ってもらえるように製品開発を進めているわけです。なのでサーバーの電源オン・オフなどの操作も昔からあるIPMIやSSH経由のSM-CLP(SMASH)だけでなく、CurlコマンドやPostmanで実行したりPythonなどで通常のWeb APIを扱うのと同じ感覚でスクリプトを書いたりもできたりします。

今後数回の投稿でサーバーのリモート管理の話を情報共有していこうかなと思います。

投稿一覧

第1回: BMC(Basebord Management Controller)全般について
第2回: サーバー管理用REST API (DMTF Redfish)の基本的な使い方と、Redfishを使うときに便利なPostmanの変数・スクリプトの使い方
第3回: PostmanとREST API(Redfish)を使ったサーバーの具体的な操作やスキーマの見方など（本投稿です）
第4回（予定）: ファームウェア更新やBIOS設定変更、イベントやテレメトリーなど

クエリーパラメーター

Redfishではクエリーパラメーターも使えます。実際に何のクエリーパラメーターが使えるかは実装次第で、サービスルートのProtocolFeaturesSupportedというオブジェクトに記載されています。下記の画面出力例ではExcerptやExpand、FilterやOnlyMemberやSelectなどが利用できることがわかります。

よく使うものの中で、たとえば$expand=.を使用するとGETリクエストの対象のリソースだけでなく、リンク先のデータもインラインで一緒に返ってくるレスポンスを要求できます。PostmanとかでインタラクティブにRedfishを使ったりしている分にはリンクをクリックする回数が減らせて楽ですね。

下記のスクリーンショットは左がクエリーパラメーターなしで、右が$expand=.を使った例です。左側はUpdateServiceが80行目なのに、右側では560行目になっています。これは各リンクが展開された状態でレスポンスが返ってきたからです。

フロントパネルのLEDでLチカしてみる

サーバーのフロントパネルのLEDでLチカしてみたいと思います。たくさんサーバーがあるデータセンタ内で作業対象のサーバーを特定するために使ったりしますね。動画ではまずLEDを点灯状態から点滅させ、その後また点灯状態にもどしています。

https://youtu.be/Mhl8TtfXyVo

この操作では/redfish/v1/Chassis/System.Embedded.1というエンドポイントに対して下記ペイロードをPATCHしています。ベーシック認証を設定するか、あらかじめセッションを開いておいてリクエストヘッダーにX-AUth-Tokenを設定するのは前回確認した通りです。

{
    "IndicatorLED": "LEDの状態"
}

どこのエンドポイントに対して、どんなJSONペイロードを、どのHTTPメソッドで実行するか

どのようにAPIを投げるかはベンダーのマニュアルを検索すると良いでしょう。また、少し慣れてくればいちいちマニュアルを見なくても、自分の操作したい対象がサービスルート直下の3つの大分類（/redfish/v1/Chassis、 /redfish/v1/Systems、 /redfish/v1/Manager）のどれに属してそうかというところから辿っていってエンドポイントを見つけたり、スキーマを確認してどんな状態・操作が実装されているか、どのHTTPメソッドが利用できるかを確認することもできます。

今回実行したLチカの場合は、サーバーのフロントパネルに物理的に付いているLEDの操作なので /redfish/v1/Chassis配下に該当するリソースがあるだろうなという考えて探すとすぐに/redfish/v1/Chassis/System.Embedded.1エンドポイントにLEDが見つかります。

また、LEDの状態はなんとなく点灯や点滅、オフなどの状態がありそうだな〜と想像できるのですが、JSONのペイロードを記述するにはどういう状態がサポートされているか、各状態が何と表されるのか、理解していないと書けないのでスキーマを確認します。（開発環境なら試してみてエラーになったら調べるというのも全然アリですが）

スキーマの確認方法ですが、レスポンスボディーの一番上にある"@odata.context"プロパティーから、XMLスキーマ(OData CSDL)のリンク集である/redfish/v1/$metadata#Chassis.Chassisに移動します。

ずらっと並んだXMLスキーマの中からChassisを検索すると /redfish/v1/Schemas/Chassis_v1.xmlというスキーマファイルが見つかります。

このスキーマファイルを開いたらLEDを検索します。すると以下のようなことがわかります。

状態には不明(Unknown)、点灯(Lit)、点滅(Blinking)、オフ(Off)があること
必ずしも上記の状態全てが実装されていない場合があること
状態を遷移させるにはPATCHまたはPUTを使うこと
ユーザー操作では不明(Unknown)状態には遷移させられないこと

Redfishでリソースの状態を遷移させたり構成を変更する場合はPATCHを使うことが多いのですが、上記のスキーマではPATCHとPUTの両方が記載されています。
なので一応PUTを試してみると案の定ステータスコード405で「PUTは許可されていません」という趣旨のエラーメッセージが返ってきます。
スキーマはあくまでRedfishの仕様を記述したものなので、どちらが使えるかは実装次第なわけですね。

ちあみにスキーマはXMLだけでなくJSONスキーマも利用できます。確認方法はサービスルート(/redfish/v1)にJSONスキーマへのリンク(/redfish/v1/JsonSchemasエンドポイント)があるのでそこから辿ります。

/redfish/v1/JsonSchemasのレスポンスボディー先頭の"@odata.context"プロパティーから("/redfish/v1/$metadata#JsonSchemaFileCollection.JsonSchemaFileCollection")に移動します。

スキーマファイルのURIがずらっとならんでいるので、いま確認したいChassisを検索すると幾つか見つかります。検索結果の中に今回のマシンで実装されているv1_13.0に対応するスキーマ(/redfish/v1/JsonSchemas/Chassis.v1_13_0)があるので、そちらをクリックします。

すると実際のスキーマファイルへのURI("/redfish/v1/Schemas/Chassis.v1_13_0.json")が確認できます。"PublicationUri"は発行元のDMTFが管理しているスキーマファイル原本へのリンクです。当たり前ですが両者の内容は全く同じです。（URIが絡む項目以外）