元々はよい感じに試行を行って『Swagger で広がる Mackerel の世界』のような景気の良いタイトルにしようと思ったのですが、なかなか辛みもあったので弱気なタイトルになりました。本記事は Mackerel Advent Calendar 2018 の4日目の記事です。
さて、Mackerelは近年のSaaSでは標準装備となっているHTTPで呼び出せるAPIの提供が行われています。
Mackerelの機能は公式の mackerel-agent も含めてほぼすべてがこのAPIを活用しています。
（Webコンソールは違う様子です。そもそも認証がAPI Keyではないですからね）
このHTTPで呼び出せるAPIには定義の仕様が存在しており、その中の一つがSwaggerです。 現在はSwaggerの後継のOpenAPI Specificationが最新なのですが、周辺エコシステムの整備状況から2018年末現在ではSwaggerを使用するのが現実的な状況です。
さて、そのSwaggerによるMackerel APIの仕様定義があるとどうなるのか？ を見てみたいと思います。
サンプルはSwaggerを良い感じに活用している気がする Azure の Logic Apps です。
定義は自分がMackerelを使うときのサンプルにしている『アラートの数をサービスメトリックに投稿する』事ができる最低限のAPIに対して行いました。
open-api-spec-sandbox/mackerel-api.yml at master · 7474/open-api-spec-sandbox · GitHub
Logic Apps の HTTP + Swagger コネクタを試す
Logic AppsはMicrosoftがAzure上で提供している各種コネクタを繋げてアプリケーションを作っていくことができるツール（ワークフローエンジンというのかな）です。
そのコネクタの一つに『HTTP + Swagger』というコネクタがあり、これはSwagger仕様を使用することで、そこで定義されている処理と簡単にコネクトできるものです。 が、結論から言ってこのコネクタの使用はあきらめました。その過程に興味がない方は次の『カスタムコネクタ』の項に飛んでください。
定義取得時のCORSが真面目すぎる
当初、GitHubに定義ファイルを置いたらRawファイルを余裕で取得できるだろうと考えていました。 が、これがうまく行かない。
このHTTP + Swaggerコネクタは定義ファイルのURLを入力すると、そのブラウザからクロスオリジンのリクエストを指定したURLに行ってファイル内容を取得するのですが、GitHubやGitHub Pagesからは4xx系のレスポンスが返ってきてしまい、素直には取得できませんでした。
これはコネクタの提供側も認識しているようで、そういう時はAzureにファイルをホスティングするといいよ！ といういい感じの解決策が提示されていました。
このコネクタのCORSリクエストは相当にまじめで、自分が付与するカスタムヘッダもホスティングする側に許可するようにOPTIONリクエストを行っています。したがって、最低限のCORSリクエストを固定的に行っているようなサーバへのCORSリクエストは失敗します。
真面目過ぎる！
雑に対応するならCORSのOPTIONのリクエスト時に以下辺りのヘッダを出力してやればよいです。私はこれで乗り切りました。
add_header Access-Control-Allow-Headers 'Origin, Authorization, Accept, Content-Type, content-type,x-ms-client-request-id,x-ms-user-agent';
API Key認証に対応していない
さて、適当に定義ファイルをホスティングしてCORSを解決したならば、ファイル内で定義されている処理が列挙されます。
いい感じです。まずはアラートを取得しましょう。
呼び出しにはAPI Keyでの認証が必要なのでその設定の仕方は……
トリガーとアクションの種類のリファレンス - Azure Logic Apps | Microsoft Docs
なるほど。HTTPヘッダに素朴に認証キーを設定する手法はサポートされてないようでした。残念！
カスタムコネクタを数クリックで作って試す
さて、気を取り直して次に行きましょう。HTTP + Swaggerコネクタで簡易に済まして『スゴイ！ すぐ繋がる！』という感動をお届けしたかったのですが、少しだけ手間をかけます。
Logic Appsには自分で独自の『カスタムコネクタ』を追加することができ、目的に応じたコネクタを使用することができます。なんとこちらもSwagger仕様から生成することができます。
まずカスタムコネクタリソースを作って、Swagger仕様のファイルを指定して、ウィザードをポチポチと進めて、完成。時間にして5分未満でしょうか？
早速Logic Appsに配置しましょう。題材は先にも書いた『アラートの数をサービスメトリックに投稿する』です。
↑のような（30分おきに GET /alerts してその数を POST /~~/tsdb する）Logic Appを作って↓のようなメトリックが投稿されました。
余裕！ GUI操作でちょちょいのちょいっとMackerel APIを使った処理をすることができました！
Swaggerいかす。Logic Apps万歳。カスタムコネクタ楽勝！ Mackerelの共有グラフの埋め込みいい感じ！！
なんだかMicrosoftの回し者の様な記事ですが、Mackerelのように素直なAPIが提供されているサービスは、Swaggerのような標準仕様を通じて世界が広がる、ということを伝えたかったのでした。
その例が最近弄っていたLogic Appsであっただけなのです。多少なりとも活用可能性の参考になりましたら幸いです。
余談
Mackerel APIのリファレンスはどうもAPI Blueprintっぽいので、Swaggerの定義に変換できるのではないかと考えています。
自分はシャイなので「Mackerel APIのBlueprintってありますか？」のような質問をできなかったのですけれど、どうせなら完全なカスタムコネクタを作りたいので省力で定義を作るために聞いてみたいと思います。そのうちに。
それでは。
