跳到主要内容

AppData

概要​

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


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

値説明型名前空間補足
person_id永続データの所有者を表す guidxs:stringhttp://ns.opensocial.org/2008/opensocial–
entry永続データtnx:AppdataEntry (unbounded)http://ns.opensocial.org/2008/opensocialkey-value 形式のコレクションです

entry フィールド​

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

値説明型名前空間補足
key永続データのキーxs:stringhttp://ns.opensocial.org/2008/opensocial上限 32 byte
value永続データの値xs:stringhttp://ns.opensocial.org/2008/opensocial上限 1024 byte

JSON 形式の表現について​

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

  1. 完全表記
{
"entry": [
{ "key": "score", "value": "78" },
{ "key": "high_score", "value": "97" }
]
}
  1. AppdataEntry のみ簡略表記
{
"entry": [
{ "score": "78" },
{ "high_score": "97" }
]
}
  1. 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.sp.app.mbga.jp/api/restful/v1/appdata/{guid}/{selector}/{appid}
  • 本番環境

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

URI Template パラメータ​

guid​

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

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

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

selector​

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

値説明備考
@selfviewer の 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 メソッドレスポンスコードレスポンスメッセージ説明
GET200OKAppdata の取得が正常に終了しました
POST/PUT/DELETE202AcceptedAppdata の生成 更新 削除が成功しました
GET/POST/PUT/DELETE400Bad Requestリクエストデータが不正です
GET/POST/PUT/DELETE401UnauthorizedOAuth による認可が失敗しています
GET/POST/PUT/DELETE403Forbidden認証エラー以外の理由でアクセス出来ない場合です
GET/POST/PUT/DELETE405Method Not Allowedメソッドが許可されていません
GET/POST/PUT/DELETE500Internal Server ErrorAPI 側の問題による失敗です

注意事項​

  • 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 改修 の対応に関する記述を追加
  • 概要
  • Appdata オブジェクトフィールド
    • entry フィールド
    • JSON 形式の表現について
  • API リクエスト
    • HTTP メソッド
    • エンドポイント URL
    • クエリパラメータ
    • OAuth Signed Request
  • API レスポンス
    • レスポンスコード
  • 注意事項
  • サンプル
    • Appdata の作成
    • 指定したキーに該当する Appdata の取得
    • 指定したキーに該当する Appdata の削除
  • 参考資料
  • 更新履歴