AppData
This page is not available in English.
Please select another language.
概要
ユーザーごとに割り当てられた永続データ 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 改修 の対応に関する記述を追加