Avatar
概要
アバター画像や swf の URL を取得する API です。
Avatar オブジェクトフィールド
| 値 | 説明 | 型 | 名前空間 | 補足 |
|---|---|---|---|---|
| size | 大きさ | xs:string | http://ns.dena.jp/mbga/gameapi/v1#avatar | "large" |
| view | 表示 | xs:string | http://ns.dena.jp/mbga/gameapi/v1#avatar | "entire" |
| emotion | 表情 | xs:string | http://ns.dena.jp/mbga/gameapi/v1#avatar | "defined" |
| dimension | 2D/3D の選択 | xs:string | http://ns.dena.jp/mbga/gameapi/v1#avatar | "defined" |
| transparent | 透過 | xs:Boolean | http://ns.dena.jp/mbga/gameapi/v1#avatar | true |
| type | フォーマット形式 | xs:string | http://ns.dena.jp/mbga/gameapi/v1#avatar | "image" |
| extension | フォーマット拡張子 | xs:string | http://ns.dena.jp/mbga/gameapi/v1#avatar | "gif" |
| motion | モーションの AvatarItem#id | xs:string | http://ns.dena.jp/mbga/gameapi/v1#avatar | type が flash, extension が swf の場合にのみ利用可能 |
| scene | アバター flash のシーン設定記述 | xs:string | http://ns.dena.jp/mbga/gameapi/v1#avatar | type が flash, extension が swf の場合にのみ利用可能 |
| fps | frames per second | xs:string | http://ns.dena.jp/mbga/gameapi/v1#avatar | type が flash, extension が swf の場合にのみ利用可能 |
| appId | アプリケーション ID | xs:string | http://ns.dena.jp/mbga/gameapi/v1#avatar | type が flash, extension が swf の場合に必須。現在の appId 値または @app のみ指定可能 |
| movieClip | MovieClip の名称 | xs:string | http://ns.dena.jp/mbga/gameapi/v1#avatar | type が flash, extension が swf の時に Response 時に含まれるパラメータです。 |
| url | アバター画像の URL | xs:string | http://ns.dena.jp/mbga/gameapi/v1#avatar | – |
API リクエスト
HTTP メソッド
Proxy モデル
- GET - アバター画像の取得
エンドポイント URL
-
Sandbox 環境
http://sb.sp.app.mbga.jp/api/restful/v1/avatar/{-list|;|guid}/{selector}{-prefix|/|parameters} -
本番環境
http://sp.app.mbga.jp/api/restful/v1/avatar/{-list|;|guid}/{selector}{-prefix|/|parameters}
URI Template パラメータ
guid
guid パラメータは下記のいずれかの値を指定します。
| 値 | 説明 | 備考 |
|---|---|---|
| @me | viewer の guid | 必須 |
| {-list | ; | guid} |
- guid をセミコロン区切りで複数指定する事が出来ます。
selector
selector パラメータは下記のいずれかの値を指定します。
| 値 | 説明 | 備考 |
|---|---|---|
| @self | guid パラメータで指定したユーザー自身のアバター画像に対するエントリリソース | 必須 |
parameters
parameters パラメータはアバター画像の形式を決める為の値を入れます。以下の key に対して value を "=" (イコール) 区切りで設定し、それらのペアを ";" (セミコロン) 区切りで繋げた物になります。
key ごとに設定出来る value 値及び、それらのデフォルト値の対応が下記の表になります。
| key | value | default | 説明 |
|---|---|---|---|
| size | large | false | 画像大 |
| size | medium | true | 画像中 |
| size | small | false | 画像小 |
| view | entire | true | 全体 |
| view | upper | false | 上半身 |
| emotion | defined | true | ユーザーが現在設定しているもの |
| emotion | normal | false | 表情 - 通常 |
| emotion | smile | false | 表情 - 笑う |
| emotion | cry | false | 表情 - 泣く |
| emotion | angry | false | 表情 - 怒る |
| emotion | shy | false | 表情 - 照れ |
| dimension | defined | true | ユーザーが現在設定しているもの |
| dimension | 2d | false | 2D アバター |
| dimension | 3d | false | 3D アバター |
| transparent | true | false | 透過 ON |
| transparent | false | true | 透過 OFF |
| type | image | true | 画像形式として取得 |
| type | flash | false | flash形式として取得 |
| extension | gif | true | gif 画像として取得 |
| extension | png | false | png 画像として取得 |
| extension | swf | false | swf として取得 |
| motion | {itemId} | undedined | swf 時に指定したモーションを適用した状態にします |
| scene | {scene} | undefined | swf 時に指定したシーン設定で swf を生成します |
| appId | {appId} | undefined | swf 時に現在の appId 値または @app と指定します (必須) |
また size, view の組み合わせで取得出来る画像サイズの対応表が下記になります。
| size | view | width | height |
|---|---|---|---|
| large | entire | 120 | 160 |
| large | upper | 60 | 80 |
| medium | entire | 60 | 80 |
| medium | upper | 30 | 40 |
| small | entire | 30 | 40 |
size が small の場合に view に upper を指定することは出来ません。
scene 記述子
scene 記述子は swf データを取得する際にモーションに含まれる36フレームから8フレームを選び出しシーンに振り分ける為の記述になります。scene 記述子は次のような構成になっています。
(scene 記述子) = {-join|-|scene}
各シーン設定を "-" (ハイフン) で区切ります。各シーン設定自体は次のような構成になっています。
{scene} = {label}.{-join|.|frameId}.{endExpression}
各パラメータの意味は下記のようになります。
| 名称 | 意味 |
|---|---|
| label | 各シーンにつける名称です。英数字とアンダースコアからなる文字列を指定可能です |
| frameId | 36フレームに対するそれぞれのフレームを表す番号です。0-35 までを指定出来ます |
| endExpession | シーンの繰り返し設定です。"loop" または "stop" を指定可能です |
例えば、
s1.10.11.stop-s2.13.15.loop
ならば、シーンラベル s1 はフレーム 10, 11 から成り、繰り返しはありません。続いてシーンラベル s2 はフレーム 13, 15 から成り、13, 15 と繰り返されます。
view が upper の場合は省略可能ですが、entire の場合は指定しなければなりません。
クエリパラメータ
下記のクエリパラメータを指定する事が出来ます。
format
レスポンス形式を指定する事が出来ます。
| 値 | 説明 | 備考 |
|---|---|---|
| json | "application/json; charset=utf8" | 任意、デフォルト値 |
API レスポンス
レスポンスコード
API のレスポンスコードは以下のいずれかになります。
| リクエスト HTTP メソッド | レスポンスコード | レスポンスメッセージ | 説明 |
|---|---|---|---|
| GET | 200 | OK | 正常にデータ取得が完了しました |
| GET | 400 | Bad Request | リクエストデータが不正です |
| GET | 401 | Unauthorized | OAuth による認可が失敗しています |
| GET | 403 | Forbidden | 認証エラー以外の理由でアクセス出来ない場合です |
| GET | 404 | Not Found | 存在しないユーザーまたは操作が許可されていないユーザーです |
| GET | 405 | Method Not Allowed | メソッドが許可されていません |
| GET | 500 | Internal Server Error | API 側の問題による失敗です |
注意事項
画像形式での取得時に関する注意事項
- dimension が 2D の場合 (2D アバターを取得する場合)、transparent パラメータに true (透過 ON) を指定する事は出来ません。
- dimension が 3D の場合 (3D アバターを取得する場合)、view が upper (上半身) の時にアニメーション GIF/PNG として取得することができません。
swf 形式での取得時に関する注意事項
- size が small の場合に view に upper を指定することは出来ません。
- swf を指定した場合は dimension は 3d のみです。
- view が upper (上半身) の時には motion の {itemId} 値を省略した際には現在ユーザーが指定している motion が設定されます。entire を指定した際には、motion の {itemId} 値の指定は必須となります。
- view が upper (上半身) の時には scene 記述子を省略する事が可能です。省略時の scene は "s1.0.stop" と指定した事になります。entire を指定した際には scene 記述子は必須です。
- movieClip の名称は自動的に採番されます。Response データに含まれる movieClip フィールド値を参照して下さい。
共通の注意事項
- defined 値を指定したパラメータはレスポンスデータに規定値として設定されている値が返されます。
- 3D アバターデータが存在しないユーザーに対して dimension を 3D と明示的に指定した場合、400 Bad Request が返されます。
- guid を複数指定する場合の最大件数は 1000 件です。但しパフォーマンス面を考慮して必要最低限の guid のみ指定して下さい。
- 存在しないユーザーまたは退会ユーザーのアバター画像等をリクエストした場合 404 Not Found が返されます。
- selector パラメータを@self 以外で指定された場合 レスポンスコードは 400 Bad Request が返されます。
- ユーザーがそのアプリケーションをインストールしていない場合に レスポンスコードは 403 が返されます。
- Smartphone Web本番環境ではキャッシュ経由のアバター画像URLとしてava-app-a.sp.mbga.jpドメインのurl値が返されます。
- Feature Phone本番環境ではキャッシュ経由のアバター画像URLとしてava-app-a.mbga.jpドメインのurl値が返されます。
サンプル
デフォルトのアバター画像の取得
viewer のデフォルトのアバター画像を取得する例です。
リクエスト形式
GET /api/restful/v1/avatar/@me/@self
レスポンス形式
200 OK
Content-Type: application/json; charset=utf8
{
"startIndex" : 1,
"itemsPerPage" : 1,
"totalResults": 1,
"avatar" : {
"extension" : "gif",
"dimension" : "2d",
"view" : "entire",
"scene" : null,
"appId" : null,
"fps" : 12,
"emotion" : "shy",
"url" : "http://sb-sp.mbga.jp/img_op/10236/10000000/10.0.0.0.11.gif?guid=ON",
"motion" : 0,
"transparent" : false,
"type" : "image",
"size" : "medium"
}
}
サンプル画像
複雑な指定の例
- size - large
- dimension - defined
- emotion - shy
- view - upper
- transparent - true
で指定した場合です。
リクエスト形式
GET /api/restful/v1/avatar/@me/@self/size=large;dimension=defined;emotion=shy;transparent=true;view=upper
レスポンス形式
{
"startIndex" : 1,
"itemsPerPage" : 1,
"totalResults" : 1,
"avatar" : {
"extension" : "gif",
"dimension" : "2d",
"view" : "upper",
"scene" : null,
"appId" : null,
"fps" : 12,
"emotion" : "shy",
"url" : "http://sb-sp.mbga.jp/img_op/10236/10000000/1.5.0.0.11.gif?guid=ON",
"motion" : 0,
"transparent" : false,
"type" : "image",
"size" : "large"
}
}
サンプル画像
複数のアバター画像を取得する
リクエスト形式
GET /api/restful/v1/avatar/10236;18407/@self/size=large;view=upper;dimension=2d;emotion=angry?format=json
レスポンス形式
200 OK
Content-Type: application/json
{
"entry" : {
" sb.sp.app.mbga.jp:18407" : {
"extension" : "gif",
"dimension" : "2d",
"view" : "upper",
"scene" : null,
"appId" : null,
"fps" : 12,
"emotion" : "angry",
"url" : "http://sb-sp.mbga.jp/img_op/18407/10000000/1.3.1.0.5.gif?guid=ON",
"motion" : 0,
"transparent" : false,
"type" : "image",
"size" : "large"
},
"sb.sp.app.mbga.jp:10236" : {
"extension" : "gif",
"dimension" : "2d",
"view" : "upper",
"scene" : null,
"appId" : null,
"fps" : 12,
"emotion" : "angry",
"url" : "http://sb-sp.mbga.jp/img_op/10236/10000000/1.3.1.0.11.gif?guid=ON",
"motion" : 0,
"transparent" : false,
"type" : "image",
"size" : "large"
}
},
"startIndex" : 1,
"itemsPerPage" : 50,
"totalResults" : 2
}
モーションアバターの取得
viewer のモーションアバターを取得する例です。
リクエスト形式
GET /api/restful/v1/avatar/@me/@self/dimension=3d;extension=swf;scene=s1.0.7.14.21.28.35.loop;motion=3513000001;type=flash;appId=@app
レスポンス形式
200 OK
Content-Type: application/json; charset=utf8
{
"startIndex" : 1,
"itemsPerPage" : 1,
"totalResults" : 1,
"avatar" : {
"extension" : "swf",
"emotion" : "normal",
"movieClip" : "a1",
"scene" : "s1.0.7.14.21.28.35.loop",
"size" : "medium",
"view" : "entire",
"dimension" : "3d",
"appId" : "@app",
"fps" : 12,
"url" : "http://sb-sp.mbga.jp/swf_op/18407/1/12000150/3513000001/10.9.0.0.1.swf?sc=s1%2C0%2C7%2C14%2C21%2C28%2C35%2Cloop&fps=12&nm=a1",
"transparent" : false,
"motion" : "3513000001",
"type" : "flash"
}
}
サンプル画像
![]()
参考資料
XML Schema Part 2: Datatypes Second Edition
URI Template draft-gregorio-uritemplate-03
更新履歴
-
2013/11/14
- API 改修によりurlフィールド(アバター画像URL)の値にsignパラメータがパラメータが付加されなくなりました。
-
2012/06/28
- ニュース掲載 API 改修 の対応に関する記述を追加