AppData

概要

ユーザーごとに割り当てられた永続データ API です。

Appdata オブジェクトフィールド

Appdata API にリクエストを行うと、Appdata オブジェクトが返却されます。

値	説明	型	補足
entry	永続データ	tnx:AppdataEntry (unbounded)	key-value 形式のコレクションです

entry フィールド

Appdata Entry オブジェクトの配列として指定して下さい。この際に Appdata Entry オブジェクトフィールドとして指定出来るのは下記になります。

値	説明	型	補足
key	永続データのキー	xs:string	上限 32 byte
value	永続データの値	xs:string	上限 1024 byte

JSON 形式の表現について

次のいずれの表現も同一の物として扱います。

1. 完全表記

  {
    "entry": [
      { "key": "score", "value": "78" },
      { "key": "high_score", "value": "97" }
    ]
  }

2. Appdata Entry のみ簡略表記

  {
    "entry": [
      { "score": "78" },
      { "high_score": "97" }
    ]
  }

3. Appdata, Appdata Entry を簡略表記

  {
    "score": "78",
    "high_score": "97"
  }

特に理由が無ければ 3 の Appdata, Appdata Entry オブジェクト両方とも簡略表記で送信して下さい。

API リクエスト

HTTP メソッド

Authorization Code Grant
- GET - Appdata の取得
- POST - Appdata の作成及び更新
- PUT - Appdata の作成及び更新 (POST 時と同じ挙動)
- DELETE - Appdata の削除
Client Credentials Grant
- GET - Appdata の取得

エンドポイント URL

Sandbox 環境

https://sb-app.mobage.jp/social/api/restful/v2/appdata/{guid}/{selector}/{appid}

本番環境

https://app.mobage.jp/social/api/restful/v2/appdata/{guid}/{selector}/{appid}

URI Template パラメータ

guid

guid パラメータは下記のいずれかの値を指定します。

値	説明	備考
@me	viewer の guid	必須
{guid}	ユーザー ID	必須

guid に有効なユーザー ID を指定する場合、そのアプリケーションをユーザーがインストールしている必要があります。

selector

selector パラメータは @self のみ指定する事ができます。

値	説明	備考
@self	viewer の Appdata のコレクションリソースを表します	必須

appid

appid パラメータは @app のみ指定する事ができます。

値	説明	備考
@app	現在実行中のアプリケーションに対する Appdata のエントリリソースを表します	必須

クエリパラメータ

format

レスポンス形式を指定する事が出来ます。

値	説明	備考
json	"application/json; charset=utf8"	任意、デフォルト値

fields

Appdata における fields 指定は Appdata Entry オブジェクトの key 値になります。従って、Appdata の更新や削除の際に特定の key を指定して操作を行う事ようにしてください。詳細は
OpenSocial RESTful Protocol Specification v0.9 - 9.3 Partial Updates を参照して下さい。

API レスポンス

レスポンスコード

API のレスポンスコードは以下のいずれかになります。

リクエスト HTTP メソッド	レスポンスコード	レスポンスメッセージ	説明
GET	200	OK	Appdata の取得が正常に終了しました
POST/PUT	201	Created	Appdata の生成、更新が成功しました
DELETE	202	Accepted	Appdata の削除が成功しました
GET/POST/PUT/DELETE	400	Bad Request	リクエストデータが不正です
GET/POST/PUT/DELETE	401	Unauthorized	OAuth による認可が失敗しています
GET/POST/PUT/DELETE	403	Forbidden	認証エラー以外の理由でアクセス出来ない場合です
GET/POST/PUT/DELETE	405	Method Not Allowed	メソッドが許可されていません
GET/POST/PUT/DELETE	500	Internal Server Error	API 側の問題による失敗です

注意事項

fields 指定をしない GET は Appdata エントリ全体を指します。必要なキーが事前に分かっている場合は fields 指定を必ず行って下さい。
fields 指定をしない POST/PUT/DELETE は 400 が返ります。操作対象のキーを fields に指定してリクエストを行ってください。
key, value 自体のサイズ制限として、key は 32 byte まで、value は 1024 byte までです。
key-value のペアはアプリケーションをインストールしているユーザーごとに 30 件までです。
Client Credentials Grant でリクエストされた場合に、ユーザーがそのアプリケーションをインストールしていないとレスポンスコードは 400 が返ります。
Appdata の生成または更新が成功した場合に、レスポンスコードは 201 が返ります。
Appdata の削除が成功した場合に、レスポンスコードは 202 が返ります。

サンプル

Appdata の作成

新しく Appdata を作成する例です。

リクエスト形式

POST /social/api/restful/v2/appdata/@me/@self/@app?format=json&fields=max_score,score
Content-Type: application/json; charset=utf8

{
   "max_score":96,
   "score":78
}

または、

POST /social/api/restful/v2/appdata/@me/@self/@app?format=json&fields=max_score,score
Content-Type: application/json; charset=utf8

{
   "entry": [
      { "key":"max_score", "value":96 },
      { "key":"score", "value":78 }
   ]
}

または、

POST /social/api/restful/v2/appdata/@me/@self/@app?format=json&fields=max_score,score
Content-Type: application/json; charset=utf8

{
   "entry": {
      "max_score":96,
      "score":78
   }
}

レスポンス形式

201 Created

指定したキーに該当する Appdata の取得

特定のキーのみ対象とした Appdata の取得です。

リクエスト形式

GET /social/api/restful/v2/appdata/@me/@self/@app?format=json&fields=score

レスポンス形式

200 OK

{
    "entry":{
        "sb.mbga.jp:10000":{
            "score":"78"
        }
    }
}

指定したキーに該当する Appdata の削除

特定のキーのみ対象とした Appdata の削除です。

リクエスト形式

DELETE /social/api/restful/v2/appdata/@me/@self/@app?format=json&fields=score

レスポンス形式

202 Accepted
{
    "score":"78"
}

更新履歴

2016/01/12
- クエリパラメータ、注意事項、サンプルを修正しました。
2015/12/02
- Client Credentials Grant に対応したので、その旨追記しました。