1. チュートリアル

HTTP / REST API を使って、簡単なユーザ登録・認証、データ作成・取得を行います。 本チュートリアルでは curl を使って REST API を発行し、モバイルバックエンド基盤サーバ(以下 BaaS サーバ)の機能を利用します。

なお、BaaS サーバのセットアップはすでに完了しているものとして説明します。

1.1. テナントの作成

以下の手順は BaaS サーバのシステム管理者権限が必要です。

システム管理者権限がない場合は、システム管理者に依頼してテナント作成と デベロッパ登録を依頼してください。

1.1.1. デベロッパコンソールへのログイン

BaaS サーバのシステム管理者権限でデベロッパコンソールにログインします。

  1. デベロッパーコンソールにアクセスします。URL は https://{server}/console です ({server} は、BaaS サーバのホスト名に読み替えてください。)
  2. システム管理者の E-mail アドレスとパスワードでログインします。

1.1.2. テナントの作成

システム管理者権限で「テナント」を作成します。

テナントとは、複数のアプリケーションを収容することができる データ領域のことと考えてください。アプリケーションのデータベースや、 アプリケーションの認証に使用するユーザ・グループなどの情報は テナント内に格納されます。

同一テナント内に所属するアプリケーション同士は、上記のデータを 共通に使用することができます。

テナントの作成手順は以下のとおりです。

  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 の2つの 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 毎のパスが付きます。

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