1. チュートリアル¶
HTTP / REST API を使って、簡単なユーザ登録・認証、データ作成・取得を行います。 本チュートリアルでは curl を使って REST API を発行し、モバイルバックエンド基盤サーバ(以下 BaaS サーバ)の機能を利用します。
なお、BaaS サーバのセットアップはすでに完了しているものとして説明します。
1.1. テナントの作成¶
以下の手順は BaaS サーバのシステム管理者権限が必要です。
システム管理者権限がない場合は、システム管理者に依頼してテナント作成と デベロッパ登録を依頼してください。
1.1.1. デベロッパコンソールへのログイン¶
BaaS サーバのシステム管理者権限でデベロッパコンソールにログインします。
- デベロッパーコンソールにアクセスします。URL は https://{server}/console です ({server} は、BaaS サーバのホスト名に読み替えてください。)
- システム管理者の E-mail アドレスとパスワードでログインします。
1.1.2. テナントの作成¶
システム管理者権限で「テナント」を作成します。
テナントとは、複数のアプリケーションを収容することができる データ領域のことと考えてください。アプリケーションのデータベースや、 アプリケーションの認証に使用するユーザ・グループなどの情報は テナント内に格納されます。
同一テナント内に所属するアプリケーション同士は、上記のデータを 共通に使用することができます。
テナントの作成手順は以下のとおりです。
- デベロッパーコンソールにシステム管理アカウントでログインします。
- 「管理」⇒「テナント管理」より、「追加」をクリックしてテナントを追加してください。
テナントに管理者を追加するには以下のようにします。
テナント追加後に「テナントID」が表示されます。 API呼び出し時には「テナントID」または「テナント名」が必要になりますので、メモしておいてください。 以降の説明ではこれを {tenant} として表記します。
注意
v7.0 より、テナント名をテナントIDの代わりに利用することができるようになりました。
1.2. アプリケーションの作成¶
「アプリケーション」とは、NEC BaaS を利用するアプリケーションの単位のことです。 BaaS サーバを利用するためには、必ず事前にアプリケーションを登録しておく必要があります。
1.2.1. アプリケーションの作成¶
デベロッパーコンソールにログインしてください。
「テナント」からテナントを選択すると、アプリケーション一覧画面に遷移します。 「追加」をクリックして、テナントにアプリケーションを追加してください。
アプリケーションIDとアプリケーションキーの値をメモしてください。 これは以降の API 呼び出しで必要です。
以下の説明では、アプリケーションID を {app_id}, アプリケーションキーを {app_key} として説明します。
1.2.2. REST API の基本¶
REST API は HTTP ベースの API です。 curl などを使って動作確認を行うことができます。
API 呼び出しの例を示します（この例はユーザ作成の例です)
curl -X POST \
-H "X-Application-Id: {app_id}" \
-H "X-Application-Key: {app_key}" \
-H "Content-Type: application/json" \
-d '{"email":"foo@example.com", "password":"PASS"}' \
https://{server}/api/1/{tenant}/users
-X オプションで HTTP のメソッド (GET/POST/PUT/DELETE) を指定します。 使用するメソッドは API によって異なりますが、それぞれ CRUD (Create/Read/Update/Delte) 操作に対応付けられます。
- GET : 取得系 (Read)
- POST : 作成系 (Create)
- PUT : 更新系 (Update)
- DELETE : 削除系 (Delete)
-H オプションで X-Application-Id と X-Application-Key の２つの HTTPヘッダを指定する必要があります。 ここには、上記管理画面で割り当てられたアプリケーションのIDとキーを指定 してください。
API で HTTP の POST/PUT などを使う場合は、リクエストボディに JSON データを埋め込んで ください。以下の点に注意してください。
- Content-Type を正しく設定すること。application/json。
- curl を使う場合、-d オプションで、送信するデータボディを指定する。
HTTP GET を使う場合は、URL にパラメータを付ける必要があります。 curl の -G, --data-urlencode オプションを使用してください。
最後の引数は URL です。 API のエンドポイントは https://{server}/api/1/{tenant} で、 この後ろに API 毎のパスが付きます。
また、Swagger UIを使用して、APIの動作確認をすることもできます。 詳細は、 Open API Specification v3 とSwagger-UI を参照して下さい。
1.3. チュートリアル1 : ユーザ管理機能¶
1.3.1. サインアップ¶
ユーザを作成します。なお、ユーザはテナント内で共通です。
curl -X POST \
-H "X-Application-Id: {app_id}" \
-H "X-Application-Key: {app_key}" \
-H "Content-Type: application/json" \
-d '{"uername":"foo","email":"foo@example.com", "password":"PASS"}' \
https://{server}/api/1/{tenant}/users
JSON フォーマットでユーザ情報(username, email, password) を指定します。
成功すると、200 OK が返り、BODY でユーザ情報が返却されます。
{
"_id": "52116f01ac521e1742000001",
"username": "foo",
"email": "foo@example.com",
"createdAt": "2013-08-27T04:37:30.000Z",
"updatedAt": "2013-08-27T04:37:30.000Z"
}
1.3.2. ログイン¶
curl -X GET \
-H "X-Application-Id: {app_id}" \
-H "X-Application-Key: {app_key}" \
-G \
--data-urlencode 'username=foo' \
--data-urlencode 'password=PASS' \
https://{server}/api/1/{tenant}/login
username と password を指定してログインします。
ログインが成功すると、200 OK が返り、BODY でパラメータが返却されます。
{
"_id":"52116f01ac521e1742000001",
"sessionToken":"eyJ1c2VyX2lkIjp7IiRvaWQiOiAiNTIxMTZmMDFhYzUyMWUxNzQyMDAwMDAxIn0sImV4cGlyZSI6MTM3Njg3ODIzOX0=--5d44532510f4ad2236ec39a403dde3c3f704c5cd",
"expire":1376878239
}
パラメータは以下の通りです。
- _id: ユーザID
- sessionToken: セッショントークン。以後の API 呼び出しでは、X-Session-Token ヘッダにこの値を入れること。
- expire: セッションの有効期限。unix time。
ログイン失敗時は 401 Unauthorized エラーとなります。
1.4. チュートリアル2 : オブジェクトストレージ¶
JSON 形式でオブジェクトを保存、読み出しすることができます。
オブジェクトは「バケット」毎に分類されます。 バケットとは、SQL データベースでいうところの「テーブル」に該当する概念で、 同一種類のオブジェクトの集合です。
1.4.1. バケットの作成¶
ここでは 'scores' という名前のバケットを作成します。
curl -X PUT \
-H "X-Application-Id: {app_id}" \
-H "X-Application-Key: {app_key}" \
-H "Content-Type: application/json" \
-d '{}' \
https://{server}/api/1/{tenant}/buckets/object/scores
1.4.2. オブジェクトの作成¶
curl -X POST \
-H "X-Application-Id: {app_id}" \
-H "X-Application-Key: {app_key}" \
-H "Content-Type: application/json" \
-d '{"name":"Foo", "score":90}' \
https://{server}/api/1/{tenant}/objects/scores
ここでは scores バケットに JSON オブジェクトを書き込んでいます。
正常にオブジェクトが書き込まれると、200 OK が返り、以下のように登録した オブジェクトが返却されます。
{
"_id":"52117490ac521e5637000001",
"name": "Foo",
"score":90,
"ACL": { "r":["g:anonymous"], "w":["g:anonymous"] },
"createdAt": "2014-06-27T05:19:16.000Z",
"updatedAt": "2014-06-27T05:19:16.000Z"
}
- _id : フィールドにはオブジェクトを一意に識別する ID が指定されます。
- ACL : には、このオブジェクトのアクセス制御リストが格納されます。
- 上記例では、誰でも(anonymous)読み書き可能な権限となります。
- createdAt: オブジェクトの作成日時です。
- updatedAt: オブジェクトの更新日時です。
1.4.3. オブジェクトの取得¶
curl -X GET \
-H "X-Application-Id: {app_id}" \
-H "X-Application-Key: {app_key}" \
https://{server}/api/1/{tenant}/objects/scores/52117490ac521e5637000001
オブジェクトIDを指定することでデータを読み出します。 以下のように結果が得られます。
{
"_id":"52117490ac521e5637000001",
"name": "Foo",
"score":90,
"ACL": { "r":["g:anonymous"], "w":["g:anonymous"] },
"createdAt": "2014-06-27T05:19:16.000Z",
"updatedAt": "2014-06-27T05:19:16.000Z"
}
1.4.4. クエリ¶
以下のようにすると、すべてのオブジェクトのリストを読み出します。
curl -X GET \
-H "X-Application-Id: {app_id}" \
-H "X-Application-Key: {app_key}" \
https://{server}/api/1/{tenant}/objects/scores
結果は、以下のように、results 内に、配列でオブジェクトが格納された形で得られます。
{"results":[{...}, {...}, {...}]}
1.4.5. 条件指定クエリ¶
条件指定は where= パラメータで行います。
curl -X GET \
-H "X-Application-Id: {app_id}" \
-H "X-Application-Key: {app_key}" \
-G \
--data-urlencode 'where={"name":"Foo"}' \
https://{server}/api/1/{tenant}/objects/scores
where には JSON でパラメータを指定します。
特定のキーに対して完全一致させたい場合は、以下のように JSON で指定します。
{"name": "Foo"}
比較を行う場合は、以下の演算子を利用できます。
- $lt, $gt : Less Than / Greater Than
- $lte, $gte : Less or Equal / Greater of Equal
- $ne : Not equal to
例) score が 70 超のものを選択したい場合
{"score": {"$gt": 70}}
その他の演算子。これらは MongoDB のクエリがそのまま使用できます。
- $in
- $all
- /^m/
- $exists
- $not
- $or
- $and
1.4.6. 削除¶
DELETE メソッドで、オブジェクトの URI を指定して削除を行います。
curl -X DELETE \
-H "X-Application-Id: {app_id}" \
-H "X-Application-Key: {app_key}" \
https://{server}/api/1/{tenant}/objects/scores/52117490ac521e5637000001