Avatar

概要

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


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

説明

名前空間

補足

size

大きさ

xs:string

http://ns.dena.jp/mbga/gameapi/v1#avatar

"large"|"medium"|"small" (ダブルクオート除く) のいずれか

view

表示

xs:string

http://ns.dena.jp/mbga/gameapi/v1#avatar

"entire"|"upper" (ダブルクオート除く) のいずれか

emotion

表情

xs:string

http://ns.dena.jp/mbga/gameapi/v1#avatar

"defined"|"normal"|"smile"|"cry"|"angry"|"shy" (ダブルクオート除く) のいずれか

dimension

2D/3D の選択

xs:string

http://ns.dena.jp/mbga/gameapi/v1#avatar

"defined"|"2D"|"3D" (ダブルクオート除く) のいずれか

transparent

透過

xs:Boolean

http://ns.dena.jp/mbga/gameapi/v1#avatar

true|false のいずれか

type

フォーマット形式

xs:string

http://ns.dena.jp/mbga/gameapi/v1#avatar

"image"|"flash" (ダブルクオート除く) のいずれか

extension

フォーマット拡張子

xs:string

http://ns.dena.jp/mbga/gameapi/v1#avatar

"gif"|"png"|"swf" (ダブルクオート除く) のいずれか

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}

ユーザー ID

必須

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

PREVIOUS

AppData

NEXT

TextData