IBM Bluemix が提供するサービスの1つに "API Management" と呼ばれるものがあります:
2015090901


このサービスは少し特殊なものです。これ単体で何かのサービス機能を提供するものではなく、特定の組織やグループ向けに Bluemix 上で使える独自 API サービスを生成するためのサービスです。また、この API Management サービスを使って提供される API サービスに関しては、名前のとおりに利用状況を把握したり、利用制限をしたり、といった API の管理機能も利用できるようになります。


少し前に API を Bluemix の公式なサービスとして登録するための手順をこのブログで紹介しました:
API を Bluemix のサービスとして登録するには?

ここで紹介した内容はあくまで公式な Bluemix サービスとして、世界中の全 Bluemix ユーザーを対象に公開する API を登録するための手順を紹介しました。技術的な要件はもちろんですが、無料枠の準備なども含めて営業的なハードルもある内容であると思っています。

一方、今回紹介するこの API Management サービスを使った場合、特定の Bluemix ユーザーだけが対象になりますが、そのユーザーに対して、Bluemix 上の(いわば)プライベートサービスを公開して管理する、ということを目的としています。何のセキュリティもない素の REST API に認証機能を追加したり、利用制限をかけたり、利用状況を監視したりする、といったことを実現します。


ではこの API Management サービスを実際に使って独自 API を Bluemix 開発者向けにサービス提供し、Bluemix 上のアプリケーションから利用し、その利用状況を確認するまでの手順を以下に紹介します。API Management ではおおまかに2段階の手順を行う必要があります:
(1) API の定義
(2) API を公開する条件の設定


まず最初に、この API Management を利用して管理/公開する独自 API を用意します。開発者の方で、既に自分の API をお持ちであればそれを使っていただいても構いません。ここでは以下の公開された為替情報 API を使って一連の流れを紹介することにします:
http://fx.mybluemix.net/

2015090905


上記 URL にブラウザでアクセスするとわかるのですが、ほぼリアルタイムに20種類の為替情報が JSON フォーマットで得ることができる、という俺製の REST API です。ドメインを見ればわかるように Bluemix 上で(Liberty Java の 256MB メモリ1インスタンスで)動いているサービスですが、ここで登録するサービスは Bluemix の外のサービスでも構いません。

で、前提としては「この API を作ったけどまだ未公開で、これを Bluemix ユーザー向け API として公開/提供したい」とします。つまり上記 URL はサービスとしてはできていて、ここにアクセスすれば API としては動くんだけど、まだ管理できないから公開はしていない(誰もこの URL を知らない、或いは認証をかけている)状態であるとします。この API を Bluemix の API Management サービスを使って Bluemix の管理下で運用できるように公開する、というのが今回の目的です。


では、まずは Bluemix にログインして、この API Management サービスを追加します。ダッシュボードの「サービスまたは API の使用」をクリックします:
2015090901


サービスの一覧が表示されるので、「統合」カテゴリ内の "API Management" サービスをクリックします:
2015090902


API Management サービスの説明が表示されます。このサービスは特定のランタイムにバインドして使うものではなく、サービス単体で利用します。そのまま「使用」をクリックして、サービスインスタンスを作成します:
2015090903


サービスインスタンスが生成されると API Management 入門の画面が表示されます(ダッシュボードから作成済みの API Management サービスを選択してもこの画面になります)。この中の "API MANAGER に移動" ボタンをクリックして、サービス管理画面に移動します:
2015090904


サービス管理画面の初期状態の画面がこちらです。まだ API を1つも登録していないので何も表示されていませんが、登録 API があると、この画面から利用状況を確認することができるようになります:
2015090905


では早速先程の為替情報 API をここに新規登録してみます。画面左のメニュー上から3番目の API マークをクリックし、API ページ内の "+API" と書かれた箇所から「作成」を選択します:
2015090906


まずは API そのものの情報を指定します。「タイトル」と「基本パス」は必須入力です。「基本パス」とは、この後登録する API のベースとなる共通 URL パスです。ここでは "/fx" と指定しているので、実際に呼び出す API のエンドポイントは "/fx/****(?a=x&b=Y&...)" という形式になります。最後に「追加」ボタンをクリックします:
2015090907

(注 このタイトルは半角英数字で入力してください。日本語は使えますが、公開時に問題が発生します)



新規に API が追加され、指定した内容が画面に表示されます。続いて具体的な API エンドポイントを追加します。画面下部の「操作」タブから「+操作」をクリックします:
2015090901


今回は最新の為替情報を表示する API 1つを追加します。この例ではパスに "/status" と指定していますが、上記でベースパスとして "/fx" を指定しているので、この API は "/fx/status" というパスで呼び出すことになります。また今回の例では GET メソッドで情報を取り出すだけの API を用意するので、POST メソッドは不要です。POST の×印をクリックして POST メソッドを削除します(GET メソッドだけを残します)。最後に「追加」ボタンをクリックします:
2015090902


"/status" GET メソッドが追加されました。ではこの "/status" GET メソッドの具体的な内容を定義するため、編集ボタンをクリックします:
2015090903


"/status" の具体的な内容を定義する画面が表示されます。今回は http://fx.mybluemix.net/ を単純に呼び出した結果をこのメソッドの結果として定義するようにします。このような場合は「実装」タブの「プロキシー」を選択し、プロキシー URL に "http://fx.mybluemix.net/" を指定します。最後に画面右上の「保存」ボタンをクリックして、この変更内容を保存します:
2015090904


これで API の定義は完成しました。API Management サービスを使って API を公開するには、API 利用者が参照できるような公開プランを定義する必要があります。続いてこの API のための公開プランを作成します。メニューの上から2番目の「プラン」セクションを選択し、「+プラン」をクリックします:
2015090905


新規プランの作成ダイアログが表示されます。API のタイトル(この例では "FX")等を指定して「追加」ボタンをクリックします:
2015090906


"FX" プランが作成できました。このプランの中で許可するエンドポイントを追加するため、画面下部の「+操作」をクリックします:
2015090907


「操作の追加」ダイアログが表示されます。今回は "/status" GET メソッド1つだけしか用意していないので1つしか表示されませんが、このプランで公開したい操作にチェックを入れて「追加」ボタンをクリックします:
2015090908


"FX" プラン内に "/status" GET メソッドが追加されました。このまま使ってもいいのですが、折角なので管理っぽい機能を1つ追加してみましょう。このまま使うと利用制限なしに使えてしまいますが、1分間に利用できる呼び出し回数に制限を付けてみます。"/status" GET メソッド行のレート制限変更ボタンをクリックします:
2015090901


「レート制限」ダイアログが表示されます。ここで1分間に呼び出せる回数として "10" を指定して「適用」をクリックします:
2015090902


指定した内容にレート制限が変更されたことを確認します。これで "/status" GET メソッドには1分間に 10 回しか呼び出せない制約が付けられたことになります:
2015090903


ここまでの内容を Bluemix ユーザー向けに公開しますが、公開対象を変更する画面についても確認しておきます。画面左のメニュー上から5番目の「開発者」を選択します。デフォルト状態では自分と同じ Bluemix 組織に属しているユーザーに対してのみ、この API が公開されるような設定になっている点を確認します。他の組織や他のユーザーにこの API を公開する場合は、この画面から開発者を追加します:
2015090904


では、改めて今回作成した API を Bluemix ユーザーに公開します。画面左メニューから「プラン」を選び、公開するプラン(今回の例では "FX" )をクリックします:
2015090905


まずこのサービスを Sandbox 環境にステージングします。画面上部の「ステージ」ボタンをクリックします:
2015090906


ステージングに成功したことを確認します:
2015090907


続いて画面左メニューから「管理」画面を選び、ステージング状態になったサービスの歯車アイコンから「公開」を選択します:
2015090908


公開範囲を指定するダイアログが表示されるので、内容を確認して「公開」ボタンをクリックします:
2015090901


しばらく待つと「公開済み」ステータスに変更されます。これで定義した API が Bluemix 利用者(の自分と同じ組織に属しているユーザー)に公開されました:
2015090902


この状態で一度 Bluemix からログアウトして、ログインし直します:
2015090903


Bluemix に再ログインすると API Management で追加された FX サービスが「カスタムAPI」カテゴリに追加されている(見えるようになっている)はずです:
2015090901


もちろん、Bluemix 上に作ったランタイムのサービスとして追加することも可能です。試しに追加してみます:
2015090902


このカスタム API サービスを追加したランタイムの環境変数を見ると、この API を使うためのクレデンシャル情報を取得することができます:
2015090903


この内容は以下の様な内容になっています、この "credentials" として書かれた3つの内容は後で使うのでメモしておきます:
  :
  :
    "credentials": {
            "client_id": "(client_id の値)",
            "client_secret": "(client_secret の値)",
            "url": "(url の値)"
    }
  :
  :

この情報を使うと、目的の API にアクセスすることができます。例えば "/status" の情報にアクセスするにはウェブブラウザを使って、上記 "credentials" 情報に含まれる情報を使った以下の URL にアクセスしてみます:
  ("url" の値)/status?client_id=(client_id の値)&client_secret=(client_secret の値)

(パラメータとして client_id と client_secret の値を指定して呼び出す)
2015090904


当初の目的通りに、期待通りの API が、API Management サービスの管理下で(本来の URL を公開することなく)作成/実行できました。この API を使ったアプリケーションを開発して Bluemix 上で動かす、ということも可能ですが、制限を加えているので1分間に10回しか呼びさせないようになっているはずです。

また、Bluemix の API Management サービスのポータル画面を確認すると、この API の利用状況を確認することもできます:
2015090906


以上が API Management サービスの使い方についてひと通りの実践を紹介した形になります。既存の(或いはこれから作成する)ウェブサービスを管理して Bluemix サービスに統合するためのサービス、という位置付けであることがお分かりいただけるでしょうか?

興味ある方は是非実際にご自身でウェブサービス API を作って、上記の手順を試していただきたいと思います。自分が作った API の利用制限や認証、利用状況監視などを外付けで実現できるというのはなんとも不思議な気分です。 自分でウェブサービスを作るような立場でない方も、本エントリで紹介している為替 API を使って試してみていただいても構いません。ただ 256 MB メモリ×1インスタンスの比較的貧弱なサーバーで動かしているサービスなので、ご利用はお手柔らかに。。