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 メソッド

Proxy モデル

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

Trusted モデル

エンドポイント URL

Sandbox 環境

http://sb.app.mbga.jp/api/restful/v1/appdata/{guid}/{selector}/{appid}

本番環境

http://app.mbga.jp/api/restful/v1/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 を参照して下さい。

OAuth Signed Request

OAuth Request Body Hash を利用した安全なデータの受け渡しを行う事が出来ます。

Authorized ヘッダまたはクエリパラメータとして xoauth_requestor_i を含める必要があります。モードによってそれぞれ次の値を指定します。

Proxy モード
　　viewer の guid ( Gadgets Server から送られて来た opensocial_viewer_id の値 )

API レスポンス

レスポンスコード

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

リクエスト HTTP メソッド	レスポンスコード	レスポンスメッセージ	説明
GET	200	OK	Appdata の取得が正常に終了しました
POST/PUT/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 は Appdata エントリ全体の生成、更新を意味しますので、既に入っているデータが一旦削除された上で再度送られて来た key-value が保存されます。差分更新の場合、fields 指定を行って下さい。
fields 指定をしない DELETE は Appdata エントリ全体の削除を意味します。特定の key のみ削除したい場合は fields 指定を行って下さい。
key, value 自体のサイズ制限として、key は 32 byte まで、value は 1024 byte までです。
key-value のペアはアプリケーションをインストールしているユーザーごとに 30 件までです。
ユーザーがそのアプリケーションをインストールしていない場合、Trustedモデルでリクエストされた場合に、レスポンスコードは 403 が返ります。
Appdata の生成または更新が成功した場合に、レスポンスコードは 202 が返ります。

サンプル

Appdata の作成

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

リクエスト形式

POST /api/restful/v1/appdata/@me/@self/@app?format=json
Content-Type: application/json; charset=utf8

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

または、

POST /api/restful/v1/appdata/@me/@self/@app?format=json
Content-Type: application/json; charset=utf8

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

または、

POST /api/restful/v1/appdata/@me/@self/@app?format=json
Content-Type: application/json; charset=utf8

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

レスポンス形式

201 Created

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

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

リクエスト形式

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

レスポンス形式

200 OK

{
   "entry" : [
      {
         "score" : "76"
      }
   ],
   "itemsPerPage" : 1,
   "totalResults" : 1
}

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

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

リクエスト形式

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

レスポンス形式

202 Accepted

参考資料

OpenSocial RESTful Protocol Specification v0.9 - 10. Messaging (Optional)
XML Schema Part 2: Datatypes Second Edition
URI Template draft-gregorio-uritemplate-03
OAuth Request Body Hash 1.0 Draft 4
OAuth Consumer Request 1.0 Draft 1

更新履歴

2013/10/01
- OAuth Signed Request (xoauth_requestor_id) に関する記述を削除しました。
2012/08/14
- guid パラメータにユーザー ID を追加
2012/06/28
- ニュース掲載 API 改修の対応に関する記述を追加