Technical information

外部との連携 Kompira REST APIを利用して外部からジョブフローを実行する

監視ツールなどの外部システムからKompiraに登録されているジョブフローを直接実行したい場合があります。例えば障害発生時にサーバーやネットワークなどの状況を調べたり、障害プロセスを再起動させるなど、一次対応を行う場合などがあります。
今回はKompiraのREST APIの機能を利用して、外部からジョブフローを呼び出してみましょう。

事前準備

APIを利用するためには認証用のトークンが必要になります。以下の画面よりREST APIの機能を有効にして、トークンを取得します。
設定 -> ユーザー管理 -> (ログイン中のアカウント名) -> 「編集」ボタンをクリック

Activate REST API
一番下の「REST API 有効化」を選択した状態で「保存」ボタンをクリックします。

API Token
「REST APIトークン」の「トークンを表示する」をクリックして、表示された文字列が認証用のトークン(Token)ですので、これをメモしておきます。(「メモ帳」などにコピーしておきましょう)

ジョブフローの作成

ノード情報”server1″に登録されたサーバー機のApache httpdのプロセスをリスタートします。(ここではserviceコマンドを利用していますが、お使いのサーバー機のバージョン、ディストリビューションに合わせて変更してください。)
ここでは”/root/restart_process”という名前のジョブフローを作成します。

このジョブフローを実行して、「起動しました」「起動に失敗しました」の表示が出るところまで確認してください。

APIのエンドポイント

Kompira REST APIのエンドポイントは、通常のKompiraオブジェクトへのリソースパスと同じになります。すなわちルートエンドポイントは
http[s]://<Kompiraサーバー>/
となり、上記のジョブフローの場合には
http[s]://<Kompiraサーバー>/root/restart_process
となります。

ブラウザからのアクセスと API リクエストを区別するために、HTTP リクエストの Accept ヘッダに

を含めるか、クエリ文字列に

を含める必要があります。

APIのユーザ認証

認証はトークン認証と、セッション認証方式の2種類が許可されます。ここではトークン認証を利用します。以下のようにリクエストのAuthorizationヘッダにトークン鍵を含めます。

または、HTTP リクエストのクエリ文字列に以下のようにトークン鍵を含める方法もあります。

APIでのジョブフローの起動

実際にAPIにリクエストを送ってみましょう。POSTメソッドで送信する必要がありますので、APIのクライアントツールやブラウザのプラグイン(たとえばFirefoxの”RESTClient”など)を使ってください。
ここではターミナルのcurlコマンドで実行します。

リクエストのURLは

となります。

応答は起動したジョブフローのプロセスIDです。
画面上部の「プロセス一覧」>「全てのプロセス」>(該当するID) の画面で、実行結果を確認する事が出来ます。

process result detail

ちなみにAPIへのリクエストをGETメソッドで送信すると、ジョブフローの情報をJSON形式で取得できます。

上記のように、外部のシステムから指定するジョブフローに対応するパス名+”.execute”で起動させる事が出来ます。

応用例: 通知メールからの呼び出し

エラー通知を受け取った場合に、状況確認後に急いで一次対応が必要になる場合を考え、メール文中のボタンをクリックする事でジョブフローを起動してみます。(※運用自動化の観点からは、通知メールを送る段階で該当する処理を実行すべきところです。) HTMLメールのフォーム(form)を使って呼び出しURLを作ります。トークンなどをヘッダーに含める事が出来ないため、URLのパラメータとして引き渡します。

通知メールを送るジョブフローを以下のように作成します。

受信メールの例です。(Gmailの場合)
link on Gmail

この「httpdをリブート」ボタンをクリックして、先のcurlコマンドの場合と同様にプロセスIDが表示されれば起動OKです。
(※メールクライアントによっては、URLをクリックしてもGETメソッドでリクエストが送信される場合がありますので、ご注意ください。)