メインコンテンツまでスキップ

Avatar

概要​

アバター画像や swf の URL を取得する API です。


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

値説明型名前空間補足
size大きさxs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatar"large"
view表示xs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatar"entire"
emotion表情xs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatar"defined"
dimension2D/3D の選択xs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatar"defined"
transparent透過xs:Booleanhttp://ns.dena.jp/mbga/gameapi/v1#avatartrue
typeフォーマット形式xs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatar"image"
extensionフォーマット拡張子xs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatar"gif"
motionモーションの AvatarItem#idxs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatartype が flash, extension が swf の場合にのみ利用可能
sceneアバター flash のシーン設定記述xs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatartype が flash, extension が swf の場合にのみ利用可能
fpsframes per secondxs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatartype が flash, extension が swf の場合にのみ利用可能
appIdアプリケーション IDxs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatartype が flash, extension が swf の場合に必須。現在の appId 値または @app のみ指定可能
movieClipMovieClip の名称xs:stringhttp://ns.dena.jp/mbga/gameapi/v1#avatartype が flash, extension が swf の時に Response 時に含まれるパラメータです。
urlアバター画像の URLxs:stringhttp://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 パラメータは下記のいずれかの値を指定します。

値説明備考
@meviewer の guid必須
{-list;guid}
  • guid をセミコロン区切りで複数指定する事が出来ます。
selector​

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

値説明備考
@selfguid パラメータで指定したユーザー自身のアバター画像に対するエントリリソース必須
parameters​

parameters パラメータはアバター画像の形式を決める為の値を入れます。以下の key に対して value を "=" (イコール) 区切りで設定し、それらのペアを ";" (セミコロン) 区切りで繋げた物になります。

key ごとに設定出来る value 値及び、それらのデフォルト値の対応が下記の表になります。

keyvaluedefault説明
sizelargefalse画像大
sizemediumtrue画像中
sizesmallfalse画像小
viewentiretrue全体
viewupperfalse上半身
emotiondefinedtrueユーザーが現在設定しているもの
emotionnormalfalse表情 - 通常
emotionsmilefalse表情 - 笑う
emotioncryfalse表情 - 泣く
emotionangryfalse表情 - 怒る
emotionshyfalse表情 - 照れ
dimensiondefinedtrueユーザーが現在設定しているもの
dimension2dfalse2D アバター
dimension3dfalse3D アバター
transparenttruefalse透過 ON
transparentfalsetrue透過 OFF
typeimagetrue画像形式として取得
typeflashfalseflash形式として取得
extensiongiftruegif 画像として取得
extensionpngfalsepng 画像として取得
extensionswffalseswf として取得
motion{itemId}undedinedswf 時に指定したモーションを適用した状態にします
scene{scene}undefinedswf 時に指定したシーン設定で swf を生成します
appId{appId}undefinedswf 時に現在の appId 値または @app と指定します (必須)

また size, view の組み合わせで取得出来る画像サイズの対応表が下記になります。

sizeviewwidthheight
largeentire120160
largeupper6080
mediumentire6080
mediumupper3040
smallentire3040

size が small の場合に view に upper を指定することは出来ません。

scene 記述子​

scene 記述子は swf データを取得する際にモーションに含まれる36フレームから8フレームを選び出しシーンに振り分ける為の記述になります。scene 記述子は次のような構成になっています。

(scene 記述子) = {-join|-|scene}

各シーン設定を "-" (ハイフン) で区切ります。各シーン設定自体は次のような構成になっています。

{scene} = {label}.{-join|.|frameId}.{endExpression}

各パラメータの意味は下記のようになります。

名称意味
label各シーンにつける名称です。英数字とアンダースコアからなる文字列を指定可能です
frameId36フレームに対するそれぞれのフレームを表す番号です。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 メソッドレスポンスコードレスポンスメッセージ説明
GET200OK正常にデータ取得が完了しました
GET400Bad Requestリクエストデータが不正です
GET401UnauthorizedOAuth による認可が失敗しています
GET403Forbidden認証エラー以外の理由でアクセス出来ない場合です
GET404Not Found存在しないユーザーまたは操作が許可されていないユーザーです
GET405Method Not Allowedメソッドが許可されていません
GET500Internal Server ErrorAPI 側の問題による失敗です

注意事項​

画像形式での取得時に関する注意事項​

  • 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 改修 の対応に関する記述を追加