AppData

概要

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

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

説明

名前空間

補足

person_id

永続データの所有者を表す guid

xs:string

http://ns.opensocial.org/2008/opensocial

entry

永続データ

tnx:AppdataEntry (unbounded)

http://ns.opensocial.org/2008/opensocial

key-value 形式のコレクションです

entry フィールド

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

説明

名前空間

補足

key

永続データのキー

xs:string

http://ns.opensocial.org/2008/opensocial

上限 32 byte

value

永続データの値

xs:string

http://ns.opensocial.org/2008/opensocial

上限 1024 byte

JSON 形式の表現について

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

1. 完全表記

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

2. AppdataEntry のみ簡略表記

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

3. Appdata, AppdataEntry を簡略表記

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

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

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 指定は AppdataEntry オブジェクトの 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 に対応したので、その旨追記しました。
PREVIOUS

People

NEXT

Avatar