跳到主要内容

Avatar

概要​

获取头像图片和 swf 的 URL 所需的 API。​

Avatar 对象字段​

向Avatar API 发送请求后,会反馈Avatar 对象。

值说明类型补充
size大小xs:string"large"
view显示xs:string"entire"
emotion表情xs:string"defined"
dimension选择2D/3Dxs:string"defined"
transparent透明xs:Booleantrue
type格式形式xs:string"image"
extension格式扩展名xs:string"gif"
motion动作的 AvatarItem#idxs:string仅限当type 为 flash, extension 为 swf 时可使用
scene头像 flash 的场景设置描述xs:string仅限当type 为 flash, extension 为 swf 时可使用
fpsframes per secondxs:string仅限当type 为 flash, extension 为 swf 时可使用
appId应用软件 IDxs:stringtype 为 flash, extension 为 swf 时必须。只能指定当前的 appId 值或 @app
movieClipMovieClip 的名称xs:stringtype 为 flash, extension 为 swf 时, 在Response 时含有的参数。
url头像图片的 URLxs:string–

API请求​

HTTP 方法​

  • Authorization Code Grant

    • GET - 获取头像图片
  • Client Credentials Grant

    • GET - 获取头像图片

      端点 URL​

  • Sandbox 环境

    https://sb-app.mobage.jp/social/api/restful/v2/avatar/{-list|;|guid}/{selector}{-prefix|/|parameters}
  • 正式环境

    https://app.mobage.jp/social/api/restful/v2/avatar/{-list|;|guid}/{selector}{-prefix|/|parameters}

URI Template 参数​

guid​

在guid 参数中,指定下述任意一项的值。

值说明备注
@meviewer 的 guid必须
{-list;guid}
  • 使用分号分隔,可指定多个guid。
selector​

在selector 参数中,指定下述任意一项的值。

值说明备注
@self对guid 参数指定的用户本人头像图片的条目资源必须
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获取图片格式
typeflashfalse获取flash格式得
extensiongiftrue获取gif 图片
extensionpngfalse获取png 图片
extensionswffalse获取swf
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各场景的命名。可指定由英文数字和下划横线组成的字符串
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 方法响应代码响应信息说明
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。
  • 指定@self 以外的selector 参数时,响应代码会反馈 400 Bad Request。
  • 用户未安装此应用软件时,响应代码会反馈 403。

样例​

获取默认头像图片​

获取viewer 默认头像图片的示例。

请求格式​

GET /social/api/restful/v2/avatar/@me/@self

响应格式​

200 OK
Content-Type: application/json; charset=utf8

{
"extension":"gif",
"dimension":"3d",
"view":"entire",
"scene":null,
"appId":null,
"fps":12,
"emotion":"defined",
"url":"http://sb-sp.mbga.jp/img_op/10236/10000000/1.5.0.0.2.gif?guid=ON",
"motion":0,
"transparent":false,
"type":"image",
"size":"medium"
}
 

复杂的指定示例​

  • size - large
  • dimension - defined
  • emotion - shy
  • view - upper
  • transparent - true

按上述进行指定。

请求格式​

GET /social/api/restful/v2/avatar/@me/@self?size=large;dimension=defined;emotion=shy;transparent=true;view=upper

响应格式​

{
"extension":"gif",
"dimension":"3d",
"view":"upper",
"scene":null,
"appId":null,
"fps":12,
"emotion":"shy",
"url":"http://sb-sp.mbga.jp/img_op/10236/10000000/1.5.0.0.2.gif?guid=ON",
"motion":0,
"transparent":true,
"type":"image",
"size":"large"
}
 

更新履历​

  • 2015/12/25
    • 对样例中的请求格式和响应格式进行了修改。
  • 2015/12/02
    • 已支持Client Credentials Grant,故补充。
  • 2014/11/27
    • 对样例中的响应格式进行了修改。