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 形式の表現について
次のいずれの表現も同一の物として扱います。
- 完全表記
{
"entry": [
{ "key": "score", "value": "78" },
{ "key": "high_score", "value": "97" }
]
}
- Appdata Entry のみ簡略表記
{
"entry": [
{ "score": "78" },
{ "high_score": "97" }
]
}
- 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 に対応したので、その旨追記しました。