IBM Bluemix の API Connect サービスを利用して、データベースのテーブルスキーマから CRUD の API を生成する、という手順を試してみました:
以下にその作業内容を紹介します。なお、以下の内容は基本的にはこのドキュメントに書かれている内容を補足しながら実行したものです:
https://new-console.ng.bluemix.net/apis/apiconnect/start
何はともあれ API Connect サービスインスタンスを1つ作成します。なお 2016/07/10 時点では(クラシックエクスペリエンスではなく)新しいUI 画面でないと正しく動かなかったので、以下は新 UI でのスクリーションショットで紹介します。
まず API Connect サービスインスタンスを作成します。新 UI 画面のダッシュボードから「コンソール」を選択し、「API」を選択します:
API に関連するサービスの画面が表示されたら「API Connect」を選択:
API Connect の画面に移動しますが、まだインスタンスが作成されていないので、「作成」ボタンをクリックします:
API Connect サービスの紹介画面が表示されたら、下にスクロールします:
利用プランを選択して「作成」ボタンをクリックします。下図では無料の "Essential" プランを選択しました。共有サーバーで利用できるリソースもあまり多くありませんが、まずはこれで作ってみます:
作成された API Connect サービスインスタンスの画面に移動します。"Sandbox" と表示されていれば成功です。また後でこの画面を使うことになりますが、まずはここまでの作業で API Connect サーバーが1つ用意できました。Bluemix のダッシュボードに戻るには左上の "IBM Bluemix" 部分をクリックします:
さて、API が用意できたら再度この API Connect サービスを使って公開のための設定を行うことになります。既に公開してもよい API があればしばらく読み飛ばしてください。以下はこれから1つのデータベーステーブルを作り、その中身を読み書きするための API を API Connect Developer Toolkit を使って新たに生成するための作業手順を紹介します。
API Connect Developer Toolkit を導入するにはまず Node.js と npm を作業マシンに導入する必要があります。Windows 環境であればこちらからインストーラーをダウンロードして導入します。Linux などの UNIX 環境であればこちらの記事(の nodejs と npm のインストールまで)を参考に Node.js と npm を導入しておいてください:
http://dotnsf.blog.jp/archives/1036420834.html
Node.js および npm が導入できたら、npm を使って API Connect Developer Toolkit を導入します:
なお、この作業マシン上でも API Connect サーバーを起動することになり、一部の作業をウェブブラウザから実行することになります。つまりこの作業マシンには GUI のデスクトップ環境やウェブブラウザが導入されている必要があります。環境に合わせて導入しておいてください。CentOS であれば以下のコマンドで X Window のデスクトップおよび FireFox ウェブブラウザを導入できます:
そして、API Connect Developer Toolkit を使って StrongLoop LoopBack アプリケーションを作成します。以下の例ではホームディレクトリ以下に src サブディレクトリを作り、更にその下に apic コマンドで loopback アプリケーションを作成しています。この通りに実行していただいても構いませんし、別途適宜ディレクトリを変更して実行することもできます:
最初の1回目だけはライセンスに同意していただく手続きが必要です。内容を確認の上、"Yes" を選択してください:
ライセンス同意後、ここからは StrongLoop LoopBack とほぼ同じ手順を実行することになります。まずは API アプリケーションとしての名前を指定します。ここでは "myapp" という名前にしました:
次にアプリケーションを作成するディレクトリ名を指定します。デフォルトではアプリケーション名と同じ名前のディレクトリが指定されます。このままでも構いませんし、変更していただいても構いません:
アプリケーションの種類を聞かれます。今回はサーバー上で動く API をテンプレートなしで作るので、"empty-server" を選択します:
すると入力された内容にそってアプリケーションが作られます・・・・が、私の場合は何故かここでエラーになってしまいました:
エラーになった場合はアプリケーションディレクトリ(この例では myapp)に移動し、"npm install" を実行して手動でインストールします:
ではこの API アプリケーションを具体的に作成していきます。ここからはブラウザでの作業になるので、まずはデスクトップ画面を開き、その中でターミナルウィンドウを開きます。
アプリケーションディレクトリ(この例では myapp)に移動し、"apic edit" と入力します。すると "Express server listening on http://127.0.0.1:9000" と表示され、デスクトップ内にデフォルトブラウザが開いて、この URL が開きます。まず最初に Bluemix にログインする必要があるため、「Bluemix にサインイン」を選択します:
IBM Bluemix のアカウントとパスワードでログインします:
ログインが成功すると「ドラフト API」の画面に移動します。「OK」をクリックします:
IBM API Connect のトップ画面に移動します。以下の様な画面が表示されることを確認してください:
ここからテーブルモデルのスキーマを定義して、そのモデルの CRUD 操作 API を生成するのですが、その前にその情報を格納するデータソース(データベース)を作成する必要があります。「データソース」タブに移動して、まだデータソースが1つも定義されていないことを確認してから「追加」をクリックします:
最初にデータソースの名称を入力します。ここでは "db" とだけ指定して「新規作成」します:
次にこのデータソースのコネクターと localStorage を指定します。前者はデフォルトでもあるインメモリDB(In-memory db)を指定し、localStorage には window.localStrage と入力して、画面右上の保存ボタンで保存します。これでデータソースの定義は決まりました:
続けてモデルを定義します。「モデル」タブに移動して「追加」ボタンをクリックします:
新しく作成するモデルの名称を入力します。この例では "item" という名前のモデルにしました:
続けて新規作成した item モデルに追加設定を加えるため、一覧から選択します:
(モデルの)複数形には "items" 、基本モデルには "PersistedModel" 、そしてデータソースには先程作成した "db" を指定します:
続けてプロパティを追加するために右下の+印をクリックして、以下のようにプロパティを設定します。追加するプロパティは2つで、1つ目は必須の name(string)、2つ目は必須ではない price(number)とします。item(商品)のname(名前)とprice(値段)を設定するためのプロパティだと思ってください。なお、特に指定しなくても id というインデックスプロパティがこれらに加えて追加されます:
プロパティの追加が完了したら、右上の保存ボタンでモデル定義を保存します。またこの状態で CRUD API を有効にするため、画面下の "Stopped" と書かれた左にある三角をクリックして、API アプリケーションを実行します:
しばらくすると HTTP サーバーが起動し、ステータスが "Running" に変わります。同時に API アプリケーションの URL(http://127.0.0.1:4001/)が表示されます:
この状態になると、作成した myapp の API アプリケーションが起動している状態になり、item モデルの読み書きが可能になります。試しにいくつかの API を curl で実行してみましょう(以下青字が入力コマンド、黒字が出力結果)。
まずは item の一覧を取得(GET /api/items)します。まだ何も追加していないので、結果は空配列になっています:
1つの item を追加(POST /api/items)してみます。まずは必須の "name" プロパティをわざと指定せずにデータを POST してエラーになることを確認します:
↑"name" がブランクではダメ、と怒られています。というわけで、改めて正しいデータを指定して追加してみましょう:
↑追加処理が成功したようです。入力データに指定しなかった id 要素が追加され、その値が1になっているようです。
この状態で再度 item の一覧取得を実行すると、追加したデータが含まれた配列で返ってくることを確認します:
また id を指定して要素を取り出す(GET /api/items/{id})こともできます:
↑こちらは結果が1つしか存在しない API なので、結果は配列ではなく、該当する JSON オブジェクトそのものになります。
データを更新(PUT /api/items)することもできます:
そして削除(DELETE /api/items/{id})する API も用意されています:
というわけで、item モデルを定義しただけで、その item モデルを読み書き更新削除する API が自動生成できていることが確認できました。
API Connect 本体の機能をほとんど紹介できてないのですが、長くなったのでとりあえずここまで。
以下にその作業内容を紹介します。なお、以下の内容は基本的にはこのドキュメントに書かれている内容を補足しながら実行したものです:
https://new-console.ng.bluemix.net/apis/apiconnect/start
何はともあれ API Connect サービスインスタンスを1つ作成します。なお 2016/07/10 時点では(クラシックエクスペリエンスではなく)新しいUI 画面でないと正しく動かなかったので、以下は新 UI でのスクリーションショットで紹介します。
まず API Connect サービスインスタンスを作成します。新 UI 画面のダッシュボードから「コンソール」を選択し、「API」を選択します:
API に関連するサービスの画面が表示されたら「API Connect」を選択:
API Connect の画面に移動しますが、まだインスタンスが作成されていないので、「作成」ボタンをクリックします:
API Connect サービスの紹介画面が表示されたら、下にスクロールします:
利用プランを選択して「作成」ボタンをクリックします。下図では無料の "Essential" プランを選択しました。共有サーバーで利用できるリソースもあまり多くありませんが、まずはこれで作ってみます:
作成された API Connect サービスインスタンスの画面に移動します。"Sandbox" と表示されていれば成功です。また後でこの画面を使うことになりますが、まずはここまでの作業で API Connect サーバーが1つ用意できました。Bluemix のダッシュボードに戻るには左上の "IBM Bluemix" 部分をクリックします:
さて、API が用意できたら再度この API Connect サービスを使って公開のための設定を行うことになります。既に公開してもよい API があればしばらく読み飛ばしてください。以下はこれから1つのデータベーステーブルを作り、その中身を読み書きするための API を API Connect Developer Toolkit を使って新たに生成するための作業手順を紹介します。
API Connect Developer Toolkit を導入するにはまず Node.js と npm を作業マシンに導入する必要があります。Windows 環境であればこちらからインストーラーをダウンロードして導入します。Linux などの UNIX 環境であればこちらの記事(の nodejs と npm のインストールまで)を参考に Node.js と npm を導入しておいてください:
http://dotnsf.blog.jp/archives/1036420834.html
Node.js および npm が導入できたら、npm を使って API Connect Developer Toolkit を導入します:
# npm install -g apiconnect
なお、この作業マシン上でも API Connect サーバーを起動することになり、一部の作業をウェブブラウザから実行することになります。つまりこの作業マシンには GUI のデスクトップ環境やウェブブラウザが導入されている必要があります。環境に合わせて導入しておいてください。CentOS であれば以下のコマンドで X Window のデスクトップおよび FireFox ウェブブラウザを導入できます:
# yum groupinstall "Desktop" # yum install firefox
そして、API Connect Developer Toolkit を使って StrongLoop LoopBack アプリケーションを作成します。以下の例ではホームディレクトリ以下に src サブディレクトリを作り、更にその下に apic コマンドで loopback アプリケーションを作成しています。この通りに実行していただいても構いませんし、別途適宜ディレクトリを変更して実行することもできます:
# mkdir ~/src # cd ~/src # apic loopback
最初の1回目だけはライセンスに同意していただく手続きが必要です。内容を確認の上、"Yes" を選択してください:
ライセンス同意後、ここからは StrongLoop LoopBack とほぼ同じ手順を実行することになります。まずは API アプリケーションとしての名前を指定します。ここでは "myapp" という名前にしました:
次にアプリケーションを作成するディレクトリ名を指定します。デフォルトではアプリケーション名と同じ名前のディレクトリが指定されます。このままでも構いませんし、変更していただいても構いません:
アプリケーションの種類を聞かれます。今回はサーバー上で動く API をテンプレートなしで作るので、"empty-server" を選択します:
すると入力された内容にそってアプリケーションが作られます・・・・が、私の場合は何故かここでエラーになってしまいました:
エラーになった場合はアプリケーションディレクトリ(この例では myapp)に移動し、"npm install" を実行して手動でインストールします:
ではこの API アプリケーションを具体的に作成していきます。ここからはブラウザでの作業になるので、まずはデスクトップ画面を開き、その中でターミナルウィンドウを開きます。
アプリケーションディレクトリ(この例では myapp)に移動し、"apic edit" と入力します。すると "Express server listening on http://127.0.0.1:9000" と表示され、デスクトップ内にデフォルトブラウザが開いて、この URL が開きます。まず最初に Bluemix にログインする必要があるため、「Bluemix にサインイン」を選択します:
IBM Bluemix のアカウントとパスワードでログインします:
ログインが成功すると「ドラフト API」の画面に移動します。「OK」をクリックします:
IBM API Connect のトップ画面に移動します。以下の様な画面が表示されることを確認してください:
ここからテーブルモデルのスキーマを定義して、そのモデルの CRUD 操作 API を生成するのですが、その前にその情報を格納するデータソース(データベース)を作成する必要があります。「データソース」タブに移動して、まだデータソースが1つも定義されていないことを確認してから「追加」をクリックします:
最初にデータソースの名称を入力します。ここでは "db" とだけ指定して「新規作成」します:
次にこのデータソースのコネクターと localStorage を指定します。前者はデフォルトでもあるインメモリDB(In-memory db)を指定し、localStorage には window.localStrage と入力して、画面右上の保存ボタンで保存します。これでデータソースの定義は決まりました:
続けてモデルを定義します。「モデル」タブに移動して「追加」ボタンをクリックします:
新しく作成するモデルの名称を入力します。この例では "item" という名前のモデルにしました:
続けて新規作成した item モデルに追加設定を加えるため、一覧から選択します:
(モデルの)複数形には "items" 、基本モデルには "PersistedModel" 、そしてデータソースには先程作成した "db" を指定します:
続けてプロパティを追加するために右下の+印をクリックして、以下のようにプロパティを設定します。追加するプロパティは2つで、1つ目は必須の name(string)、2つ目は必須ではない price(number)とします。item(商品)のname(名前)とprice(値段)を設定するためのプロパティだと思ってください。なお、特に指定しなくても id というインデックスプロパティがこれらに加えて追加されます:
プロパティの追加が完了したら、右上の保存ボタンでモデル定義を保存します。またこの状態で CRUD API を有効にするため、画面下の "Stopped" と書かれた左にある三角をクリックして、API アプリケーションを実行します:
しばらくすると HTTP サーバーが起動し、ステータスが "Running" に変わります。同時に API アプリケーションの URL(http://127.0.0.1:4001/)が表示されます:
この状態になると、作成した myapp の API アプリケーションが起動している状態になり、item モデルの読み書きが可能になります。試しにいくつかの API を curl で実行してみましょう(以下青字が入力コマンド、黒字が出力結果)。
まずは item の一覧を取得(GET /api/items)します。まだ何も追加していないので、結果は空配列になっています:
# curl -XGET http://localhost:4001/api/items
[]
1つの item を追加(POST /api/items)してみます。まずは必須の "name" プロパティをわざと指定せずにデータを POST してエラーになることを確認します:
# curl -H 'Content-Type: application/json' -XPOST http://localhost:4001/api/items -d '{"price":100}' { "error":{ "name":"ValidationError", "status":422, "message":"The `item` instance is not valid. Details: `name` can't be blank (value: undefined).", "statusCode":422, "details":{ "context":"item", "codes":{ "name":["presence"] }, "messages":{ "name":["can't be blank"] } }, "stack":"ValidationError: The `item` instance is not valid. Details: `name` can't be blank (value: undefined).\n .... :
↑"name" がブランクではダメ、と怒られています。というわけで、改めて正しいデータを指定して追加してみましょう:
# curl -H 'Content-Type: application/json' -XPOST http://localhost:4001/api/items -d '{"name":"あいうえお","price":100}' {"name":"あいうえお","price":100,"id":1}
↑追加処理が成功したようです。入力データに指定しなかった id 要素が追加され、その値が1になっているようです。
この状態で再度 item の一覧取得を実行すると、追加したデータが含まれた配列で返ってくることを確認します:
# curl -XGET http://localhost:4001/api/items
[{"name":"あいうえお","price":100,"id":1}]
また id を指定して要素を取り出す(GET /api/items/{id})こともできます:
# curl -XGET http://localhost:4001/api/items/1
{"name":"あいうえお","price":100,"id":1}
↑こちらは結果が1つしか存在しない API なので、結果は配列ではなく、該当する JSON オブジェクトそのものになります。
データを更新(PUT /api/items)することもできます:
# curl -H 'Content-Type: application/json' -XPUT http://localhost:4001/api/items -d '{"id":1,"name":"かきくけこ","price":200}' {"name":"かきくけこ","price":200,"id":1} # curl -XGET http://localhost:4001/api/items [{"name":"かきくけこ","price":200,"id":1}]
そして削除(DELETE /api/items/{id})する API も用意されています:
# curl -XDELETE http://localhost:4001/api/items/1 {"count":1} # curl -XGET http://localhost:4001/api/items []
というわけで、item モデルを定義しただけで、その item モデルを読み書き更新削除する API が自動生成できていることが確認できました。
API Connect 本体の機能をほとんど紹介できてないのですが、長くなったのでとりあえずここまで。
コメント