Avatar
概要
アバター画像や swf の URL を取得する API です。
Avatar オブジェクトフィールド
Avatar API にリクエストを行うと、Avatar オブジェクトが返却されます。
| 値 | 説明 | 型 | 補足 |
|---|---|---|---|
| size | 大きさ | xs:string | "large" |
| view | 表示 | xs:string | "entire" |
| emotion | 表情 | xs:string | "defined" |
| dimension | 2D/3D の選択 | xs:string | "defined" |
| transparent | 透過 | xs:Boolean | true |
| type | フォーマット形式 | xs:string | "image" |
| extension | フォーマット拡張子 | xs:string | "gif" |
| motion | モーションの AvatarItem#id | xs:string | type が flash, extension が swf の場合にのみ利用可能 |
| scene | アバター flash のシーン設定記述 | xs:string | type が flash, extension が swf の場合にのみ利用可能 |
| fps | frames per second | xs:string | type が flash, extension が swf の場合にのみ利用可能 |
| appId | アプリケーション ID | xs:string | type が flash, extension が swf の場合に必須。現在の appId 値または @app のみ指定可能 |
| movieClip | MovieClip の名称 | xs:string | type が flash, extension が swf の時に Response 時に含まれるパラメータです。 |
| url | アバター画像の URL | xs: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 パラメータは下記のいずれかの値を指定します。
| 値 | 説明 | 備考 |
|---|---|---|
| @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 が返されます。
サンプル
デフォルトのアバター画像の取得
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"
}
更新履歴
- 2018/12/04
- サンプルを修正しました。
- 2015/12/25
- サンプルにあるリクエスト形式、レスポンス形式を修正しました。
- 2015/12/02
- Client Credentials Grant に対応したので、その旨追記しました。
- 2014/11/27
- サンプルにあるレスポンス形式を修正しました。