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.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 パラメータは下記のいずれかの値を指定します。

説明

備考

@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/12/11
    • 新規作成

 

PREVIOUS

People

NEXT

Avatar