サーバー構築不要!スマートフォンアプリ向けの新クラウド

トップ >ドキュメント >REST API リファレンス:共通フォーマット

共通ドキュメント

共通フォーマット

REST API について

ニフクラ mobile backend は REST API を提供しているため、
外部サーバからデータストアや会員管理などすべての機能をご利用いただけます。

共通仕様

ニフクラ mobile backendのREST APIを利用する際の共通仕様は以下のとおりです。

名前 説明
APIのエンドポイント mb.api.cloud.nifty.com
APIのバージョン 2013-09-01
使用するプロトコル HTTPS
文字コード UTF-8

共通リクエストヘッダー

REST APIをリクエストする場合には、以下の共通リクエストヘッダーが必要です。

ヘッダー名 説明
X-NCMB-Application-Key アプリケーションキー
X-NCMB-Signature シグネチャ
X-NCMB-Timestamp タイムスタンプ
X-NCMB-Apps-Session-Token アプリセッショントークン

アプリセッショントークン以外は、APIの認証に使用されますので設定が必須です。
アプリセッショントークンはACL制限を行っているデータにアクセスする場合に設定が必要です。

ただし、以下のAPIについてはリクエスト時の認証は行わず、
ワンタイムトークンなどを利用しているため共通リクエストヘッダーの指定が不要です。

  • メールアドレス確認API
  • 公開ファイル取得API

共通レスポンスヘッダー

サーバーから共通して返却されるHTTPレスポンスヘッダーは、以下のようになります。

ヘッダー名 備考
X-NCMB-Response-Signature シグネチャ
Content-Type レスポンスボディのメディアタイプが返却される
Date 日付が返却される
HTTPステータス 成功時には200が返却され、それ以外はエラーコードが返却される
Connection closeが返却される
Transfer-Encoding chunked

データ型

REST APIでは、文字列、数値、配列、オブジェクトなどのデータを扱うことができるほか、
以下のような特殊なデータ型も利用可能です。

日付

日付型のフォーマットは以下の通りです。
__typeというフィールドでDateを指定し、isoというフィールドでUTC(協定世界時)の日付を指定します。
タイムゾーンにはUTC以外を設定することはできません。
設定上限は「2038-01-18T23:59:59.999Z」です。

{"__type": "Date", "iso": "YYYY-MM-DDTHH:mm:ss.sssZ"}

※ 上記フォーマットは一例です。環境により異なりますのでご注意ください。

ポインタ

既存のオブジェクトに別オブジェクトを参照するポインタを関連付けることができます。
※ポインタ型の参照では、1つのオブジェクトのみ参照することが可能です。

{"__type":"Pointer","className":"「対象クラス名」","objectId":"「対象オブジェクトID」"}

リレーション

リレーションもポインタと同じように別オブジェクトを参照するためのものですが、
同一クラスに限り一対多の登録も可能になっているものです。

例えば、無料会員と有料会員のロールを作成し、
それぞれのロールに複数の会員を所属させていく
(roleクラスのbelongUserにリレーション型で会員オブジェクトを登録していく)ことで、
無料会員と有料会員でアクセスできるコンテンツを制限することができるようになります。

※ポインタ型は1対1の参照を登録するので、ロールのbelongUserやbelongRoleといったフィールドがポインタ型だった場合は、複数の会員や子ロールを所属させることができません。

リレーション型の登録/取得/削除では、フォーマットが異なっているため、注意が必要です。
以下では、ロールへの会員追加・削除を例にリレーション型の登録/取得/削除の説明を行います。

リレーション型の登録時には、
__op(実行するオペレーション)にAddRelation(リレーションの登録)を指定し、
objectsに参照先となるオブジェクトをポインタ型配列の形式で指定します。

curl -X PUT  -H "X-NCMB-Apps-Session-Token:"\
 -H "X-NCMB-Application-Key:6145f91061916580c742f806bab67649d10f45920246ff459404c46f00ff3e56"\
 -H "X-NCMB-Timestamp:2013-12-02T02:44:35.452Z"\
 -H "X-NCMB-Signature: aBgyshghQuAl6/UY5uAzUzQ4VRB1nUJdpSQixUN5qD4="\
 -H "Content-Type: application/json"\
 -d '{"belongUser":{"__op":"AddRelation", "objects":[{"__type":"Pointer", "className":"user", "objectId":"rvI95wlvkZ5q5vOn"}]}}'\
 https://mb.api.cloud.nifty.com/2013-09-01/roles/fA2UG40Xd09KynDp

リレーション型を含むオブジェクトを取得した場合には、__typeにRelationが設定され、
対象のクラス名が設定されている状態で返却されます。

//curlコマンドでのロール取得
curl -X GET -G  -H "X-NCMB-Apps-Session-Token:"\
 -H "X-NCMB-Application-Key:6145f91061916580c742f806bab67649d10f45920246ff459404c46f00ff3e56"\
 -H "X-NCMB-Timestamp:2013-12-02T02:44:35.452Z"\
 -H "X-NCMB-Signature: hNCGJM+ju0RQOdHo+XSe55TUWkJKo2V8RCkKMzXBjXw="\
 -H "Content-Type: application/json"\
 --data-urlencode 'where={"belongUser":{"__type":"Pointer", "className":"user", "objectId":"rvI95wlvkZ5q5vOn"}}'\
 https://mb.api.cloud.nifty.com/2013-09-01/roles

 //コマンドを実行した結果、belongUserがリレーション型であることが分かる
{
   "results":[
      {
         "objectId":"fA2UG40Xd09KynDp",
         "roleName":"testRole",
         "belongRole":null,
         "belongUser":{
            "__type":"Relation",
            "className":"user"
         },
         "createDate":"2014-06-02T02:56:55.577Z",
         "updateDate":"2014-06-02T03:14:51.186Z",
         "acl":{
            "*":{
               "read":true,
               "write":true
            }
         }
      }
   ]
}

リレーション型で紐付けされた方のオブジェクトを取得する場合には、$relatedToオペランドを使用して、
紐付けられた方のオブジェクト検索を行います。今回の場合、会員のオブジェクトがロールに紐付けされているので、
会員検索時に、「roleクラスにあるobjectIdがfA2UG40Xd09KynDpのオブジェクトにて、
belongUserというキーに紐付いている会員」という検索条件を設定します。

//$relatedToオペランドを使用した会員検索のcurlコマンド
curl -X GET -G  -H "X-NCMB-Apps-Session-Token:"\
 -H "X-NCMB-Application-Key:6145f91061916580c742f806bab67649d10f45920246ff459404c46f00ff3e56"\
 -H "X-NCMB-Timestamp:2013-12-02T02:44:35.452Z"\
 -H "X-NCMB-Signature: 8TE7W/N8YegXxJLJGV1N7FpaMdSxi943edYI71r+9B8="\
 -H "Content-Type: application/json"\
 --data-urlencode 'where={"$relatedTo":{"object":{"__type":"Pointer", "className":"role","objectId":"fA2UG40Xd09KynDp"},"key":"belongUser"}}'\
 https://mb.api.cloud.nifty.com/2013-09-01/users


//curlコマンドで得られる結果
{
   "results":[
      {
         "objectId":"rvI95wlvkZ5q5vOn",
         "userName":"testUser",
         "authData":null,
         "mailAddress":null,
         "mailAddressConfirm":null,
         "createDate":"2014-06-02T02:56:25.350Z",
         "updateDate":"2014-06-02T03:17:47.389Z",
         "acl":{
            "rvI95wlvkZ5q5vOn":{
               "read":true,
               "write":true
            },
            "*":{
               "read":true,
               "write":true
            }
         }
      }
   ]
}

ある会員をロールから削除する場合など、リレーション型で紐付けされたオブジェクトへの参照を削除する場合は、
__op(実行するオペレーション)でRemoveRelation(リレーションの削除)を指定します。

//リレーションの削除を行うcurlコマンド
curl -X PUT  -H "X-NCMB-Apps-Session-Token:"\
 -H "X-NCMB-Application-Key:6145f91061916580c742f806bab67649d10f45920246ff459404c46f00ff3e56"\
 -H "X-NCMB-Timestamp:2013-12-02T02:44:35.452Z"\
 -H "X-NCMB-Signature: aBgyshghQuAl6/UY5uAzUzQ4VRB1nUJdpSQixUN5qD4="\
 -H "Content-Type: application/json"\
 -d '{"belongUser":{"__op":"RemoveRelation", "objects":[{"__type":"Pointer", "className":"user", "objectId":"rvI95wlvkZ5q5vOn"}]}}'\
 https://mb.api.cloud.nifty.com/2013-09-01/roles/fA2UG40Xd09KynDp

位置情報

緯度/経度で位置情報を示します。
※指定可能な範囲は、経度:-180~180、緯度:-90~90となっています。

{"__type":"GeoPoint","longitude":「経度」,"latitude":「緯度」}

位置情報型が指定されたフィールドに対して、その他の型のデータで登録/更新を実施すると「E403006」のエラーが返却されます。
その他のデータ型が指定されたフィールドに対して、位置情報型データで登録/更新を実施した場合も同様です。

フィールドの削除について

値にnullを指定してレコード(オブジェクト)を更新することで、そのフィールドの値を削除することができます。

オブジェクトID(objectId)について

各クラスのオブジェクトを管理するために自動生成された一意な文字列です.
操作対象のオブジェクトを一意に特定するために利用します.
例)更新API、削除API、取得APIのパスの構成要素として利用します.

パーミッション(ACL)について

mobile backendには、クラスのパーミッションとレコード(オブジェクト)のパーミッションがあります。
これらのパーミッションは、会員やロールに対して権限を追加していくACLの形式で設定されます。
設定できる権限の種類は以下の通りです。

ACLの種類 設定可能な値
クラスのACL
(ダッシュボードから設定可能)
get(取得), find(検索), update(更新), create(作成), delete(削除), add fields(フィールド追加)
レコードのACL
(ダッシュボードとアプリから設定可能)
read(読み込み), write(書き込み・削除)

ACL未指定時の初期値は、システム側であらかじめ設定されている以下のデフォルト値になります。
  会員を登録する場合 : 会員本人のみが読み・書き可能
  上記以外の場合   : 個別設定なし(フルアクセス可能)

オブジェクトのACLに対して、nullや{} (空オブジェクト)を指定した場合はフルアクセス可能となりますのでご注意ください。

ACLの記載例
会員にオブジェクトのACLを指定する
{ "acl" : { "4suSlFT5xx" : { "read" : true , "write": true } } }

ロールにACLを指定する
{ "acl" : { "role:admin" : { "read" : true , "write": true } } }

ある会員にのみ、書き込み権限を指定する
{ "acl" : { "*" : { "read" : true } , "4suSlFT5xx" : { "read" : true , "write" : true } } }

ある会員に、読み込みのみの権限を指定する
{ "acl" : { "*" : { "read" : true , "write" : true } , "4suSlFT5xx" : { "read" : true } } }

お探しの内容が見つからなかった場合はユーザーコミュニティ もご活用ください。(回答保証はいたしかねます)
なお、 Expertプラン以上のお客様はテクニカルサポートにてご質問を承らせて頂きます。

推奨画面サイズ1024×768px以上

ページの先頭へ