ブログトップ 記事一覧 ログイン 無料ブログ開設

Groovyラボ RSSフィード

2015-12-20

APIヘルスチェックのススメ: API Health

これはEnterprise APIs Advent Calendar 2015の12/20のエントリです。(このブログ、ここ数年年末のアドベントカレンダー用のエントリしかない…^^;)

一般向けであれ、特定パートナー向けであれ、Web APIの運用にはサービス監視が重要です。そして、サーバサイドにおける内部的な監視も大切ですが、API利用者に正しくサービスが提供できていることを確認するためには、クライアントから実際にリクエストを送る形態のヘルスチェックは欠かせません。

ApigeeAPI Healthは、このクライアント視点のAPIヘルスチェックを簡単に実現する独立したサービスです。2015年12月現在、ベータ版で提供されており誰でも無料で利用できます。インターネットからアクセス可能ならどんなAPIでも監視対象にすることができます。あらかじめ定義したリクエストを指定した頻度で送信して、エラーの発生やレスポンスタイムの異常があればメールやSlackなどでアラートを送ってくれます。リクエストは世界4地点から送信することが可能で、成功率やレスポンスタイムを発信地点ごとにグラフ表示することなどもできます。

f:id:ksky:20151221013845p:image

使い方は次の通り(詳細は公式ドキュメントを参照):

  1. (もしまだ持っていなければ)Apigeeアカウントを用意する
  2. API Healthダッシュボードにログイン
  3. 左サイドの"+"、または右上の"Add Prove"ボタンでプローブを作成
    • プローブ名とステップ名をつける。プローブは1個以上のステップ(API呼び出し)からなるヘルスチェックの単位。単一のGETリクエストでもいいし、認証トークンを取得してそれを使うような一連の呼び出しシーケンスでもよい
    • ステップのリクエストURIとメソッド、期待するレスポンスコードを設定
    • "Show Advanced"を使うと、呼び出し前に短いスクリプトを実行したり、リクエストのヘッダを設定したりできる。また、レスポンスヘッダやJSONボディの一部を抽出して変数に設定することも可能(アサーションに使ったり次以降のステップで参照できる)
    • 必要なら"Add new step"でステップを追加
  4. プローブの動作を設定
    • チェック頻度: 30秒/1分/5分/15分/30分/1時間のいずれか
    • アラート条件: レスポンスコードや変数のアサーション失敗回数、レスポンスタイムが閾値を超えた回数、異常な遅延
    • 通知先: メール、HipChatSlack
  5. リクエストの発信地を設定(以下の4地点をon/off)
    • Oregon(アメリカ西海岸)
    • Washington DC(アメリカ東海岸)
    • Dublin(アイルランド)
    • Sydney(オーストラリア)

最後に"I'm Done"を押せば定期ヘルスチェックが始まり、設定した条件でアラートを受けたり、ダッシュボードでこれまでのヘルスチェックの結果を参照することができます。

簡単に設定できる便利な無料サービスですので、監視したいAPIがあるすべての方にオススメです。ぜひお試しあれ!

2014-12-25

SlackのWebHookとNTTドコモの雑談対話APIとApigeeで雑談ボットをつくる #apijp

Web API Advent Calendar 2014、最終日のエントリは、最近一部で流行中のチームコミュニケーションツールSlackのネタです。

f:id:ksky:20141226011832j:image

(完成したボットをSlackで試しているところ)

Slackネタはid:i2keyさんの12/13の素敵なエントリ:

ZapierでSlackを佐野ひなこちゃんで埋め尽くす #apijp - Dhaulagiri

ですでに使われてしまいましたが、ここではSlackが提供する別のインテグレーション方法を使って雑談ボットを作ってみます。

Slackには外部プログラムとのさまざまなインテグレーション方法が用意されています。この中のOutgoing WebHooksの機能は、Slackに新しいメッセージが入力されるたびに設定した外部URLを呼び出してくれるというものです。これに、先日のAPI Meetup Tokyo #4ドコモさんが紹介していた雑談対話APIを組み合わせます。

SlackのWebHook呼び出しと雑談対話APIの呼び出し形式は異なるため、間でその調整や変換を行う何かが必要になります。通常なら何らかのスクリプトなどを書くところですが、ここではさりげない(?)宣伝を兼ねてApigee EdgeAPI Proxyの機能を使ってこの接続を実現してみました。

おおまかな処理の流れ

f:id:ksky:20141226011833p:image

  1. 指定された条件に合致するメッセージが入力されると、設定しておいたApigee ProxyのURLにSlackがメッセージテキストなどをPOSTする
  2. Apigeeがフォームデータを受け取り、メッセージテキスト(text)やユーザ名(user_name)などを取り出す
  3. ユーザ名が"slackbot"の場合、発言者は(自分を含む)ボットなので何もせず200で空のレスポンスを返して処理を終える。これを行わないと自分の発言に対してもWebHook呼び出しが起こるため無限ループが発生する(1回やらかしました)
  4. 以前の会話のコンテキストIDがキャッシュにあれば読み出す
  5. 必要なデータをJSON形式にしてドコモAPIにPOSTする
  6. ドコモAPIが返すJSONデータを受け取り、ボットの発言(utt)やコンテキストID(context)を取り出す
  7. コンテキストIDはSlackのchannel_idをキーとしてキャッシュに保存しておく
  8. ボットの発言をWebHookの返信形式のJSONにまとめ直してSlackに返す

Apigeeでの実装

これらはクラウド型のApigee無償版ですべて実現できます。

f:id:ksky:20141226011834p:image

(ボット開発中のApigee画面)

Apigeeでの実装上のポイントは以下の通り:

(「ポリシー」というのはApigee用語であらかじめ用意された処理部品のこと)

まとめ

Slackに限らず、最近はさまざまなサービスでWebHookが提供されるようになってきています。Apigeeの持つインタフェース変換機能を使えば、自分でPOSTを受けるサーバやスクリプトを用意することなく、さまざまな別のAPIに接続することができます。(ここでは扱いませんでしたが複数APIマッシュアップも可能)

Apigeeは本来API提供者にAPI管理レイヤを提供するもので、ここに書いたツール的な用法は本質的な使い方ではありません。しかしWebHook用の接続ツールとしては特に有用性が高いかもしれないと感じました。

ちなみに書いている途中で、非常によく似た内容のブログ記事を見つけたので、本エントリのタイトルは敬意を表してこちらにあわせてみました。:-)

Safx: TypetalkのWebhookとNTTドコモの雑談対話APIとGoogle Apps Scriptで雑談ボットをつくる

SlackではなくnulabさんのTypetalk、ApigeeではなくGoogle Apps Scriptを使われていますが、仕組み的にはほとんど同じです。一部参考にさせていただきました、感謝!

2014-12-08

apibでコマンドラインからAPIを負荷テスト #apijp

これはWeb API Advent Calendar 2014、8日目のエントリです。ツールの小ネタ第二弾です。

APIのテストには、目的に応じてcurlコマンドやPostman、そしてJMeterab(Apache Bench)などさまざまなツールを使います。今回はabによく似た(そしてより進化した)シンプルなコマンドランベースの負荷・性能テストツールであるapib(API Bench)を紹介します。

特徴

  • keep-aliveやchunked encodingを含む、HTTP 1.1の正確なサポート
  • 複数のI/Oスレッドを使いマルチコアを活用
  • 大きなオブジェクトのPOSTやPUTをサポート
  • OAuth 1.0の署名をサポート
  • 実行結果はファイル出力可能(自動化のための連携が容易)

など。

インストール

MacならHomebrewで一発です:

brew install apib

それ以外のプラットフォームではGitHubからソースを取得してビルドする必要があります。

実行例

同時接続数10で30秒間、連続で目一杯リクエストを送る:

$ apib -c 10 -d 30 <ターゲットURL>
(5 / 30) 51.958 0% cpu
(10 / 30) 54.582 0% cpu
(15 / 30) 54.378 0% cpu
(20 / 30) 54.787 0% cpu
(25 / 30) 54.577 0% cpu
(30 / 30) 54.387 0% cpu
Duration:             30.012 seconds
Attempted requests:   1624
Successful requests:  1624
Non-200 results:      0
Connections opened:   10
Socket errors:        0

Throughput:           54.111 requests/second
Average latency:      184.049 milliseconds
Minimum latency:      175.175 milliseconds
Maximum latency:      384.165 milliseconds
Latency std. dev:     15.330 milliseconds
50% latency:          181.145 milliseconds
90% latency:          190.309 milliseconds
98% latency:          192.284 milliseconds
99% latency:          192.580 milliseconds

Client CPU average:    0%
Client CPU max:        0%
Client memory usage:    0%

Total bytes sent:      0.13 megabytes
Total bytes received:  0.17 megabytes
Send bandwidth:        0.03 megabits / second
Receive bandwidth:     0.05 megabits / second

apibにはメソッドやヘッダの指定、認証設定など他にも多くのオプションがあります。詳しくは、apib -hでヘルプを見たり、こちらを参照してください。

注意!

かんたんに大量のトラフィックを生成しますので、ターゲットはくれぐれも慎重に選んでください(通常は自分で開発・管理しているサーバ)。うかつに他人のサーバに負荷をかけると攻撃とみなされることがあります!

2014-12-07

らくらくシーケンス図:WebSequenceDiagrams #apijp

これはWeb API Advent Calendar 2014、7日目のエントリです。知っている方も多いと思いますが、ツールの小ネタで。

Web APIを扱っていると、認証やマッシュアップのフローの記述など、簡単なシーケンス図を書きたくなる場合がよくあります。こんなときにオススメなのが、カナダのHanov Solutions社が提供する便利なWebサービスWebSequenceDiagrams

次のようなシンプルなテキストを書くだけで:

title GWでのmashup

アプリ->GW: POST 郵便番号
GW->サービスA: GET /郵便番号
サービスA->GW: 住所(JSON)
GW->サービスB: POST 住所
サービスB->GW: 緯度経度(XML)
GW->アプリ: 緯度経度(JSON)

次のようなイメージを生成してくれます:

f:id:ksky:20141207232044p:image

基本的に無償で使えますし、生成した図は直接リンクして使うこともPNGイメージとしてexportすることもできて非常に便利です。スタイルもいくつか用意されています。例:

f:id:ksky:20141207232045p:image

ちゃんとAPIも用意されているので他のツールや言語と組み合わせるのも簡単。有償のプレミアム版では図の編集に追従するリンクの生成、より高度な記法やPDF/SVGでのexportなどもサポートされます。

シンプルですが非常に使い勝手の良いツールで、あなたのAPIツール箱にそろえておきたい優れものの一つです。

2014-12-01

REST APIを記述せよ!Swagger紹介 #apijp

Web API Advent Calendar 2014、初日はSwaggerを紹介します。

SwaggerはReverbによって開発された、RestfulなAPIを記述する標準仕様です。APIを機械可読な形で記述することは、ドキュメント生成やツール開発、さまざまな形での自動化に非常に重要です。好き嫌いはともかく、SOAPにはWSDLという統一標準がありましたが、RESTには本質的にそういった標準がないため、類似するさまざまな仕様が開発されてきました。Swaggerはその中でも最も有望なものの一つだと思います。

1. 特徴

  • 記述はJSONでシンプル。ミニマム定義の例:
{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "petstore"
    },
    "paths": {
        "/users": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Describe the 200 response in more detail"
                    }
                }
            }
        }
    }
}

Swaggerのサイトにはブラウザ上で試せるSwagger Editorというものが用意されており、左側にAPI記述を書くと、右側に生成されるドキュメントのプレビューを見ることができます(下図)。これを少し試すとSwaggerの雰囲気がすぐつかめると思います。(APIの記述はJSONではなくYAMLなので気をつけてください)

f:id:ksky:20141201221558j:image

2. バージョンについて

2014/09/08に最新のSwagger 2.0がリリースされました。2.0は、これまでの1.x(最新は1.2)系とは互換性がないので注意が必要です(マイグレーションガイドはこちら)。2.0がまだ出たばかりなので、web上で見つかる日本語のSwagger記事はほとんど1.x系のものです。注意してください。

3. Swagger対応の便利ツール

Postman
みんな大好きAPIテストクライアントの定番、PostmanにもSwaggerインポート機能があります(Swagger 1.2対応)。
Mockable
REST/SOAPなモックサーバを簡単に立ち上げられる期待のサービス、MockableでもSwaggerインポートをサポート予定です(現時点では未実装)。
Apigee 127
APIモデル定義をベースに、Node.jsでの実装スケルトンを生成したり、キャッシュやレートリミット、OAuthなどのAPI管理機能を簡単に実現できるオープンソースプロジェクト、Apigee 127でもSwagger 2.0が基盤技術として採用されています。

まとめ

Swaggerは現在メジャーバージョンの移行期にあるため、ツールやサポートに若干の混乱はありますが、2.0への移行完了後がとても楽しみな技術です。Web API好きならば今のうちに試してみる価値はありますよ!