People
概要
获取用户个人简介信息和用户好友列表所需的API。
People 对象字段
向People API 发送 GET 请求后,会反馈People 对象。只能获取URI Template 参数的 fields 参数中指定的字段。
| 值 | 说明 | 类型 | 补充 |
|---|---|---|---|
| id | 用户 ID | xs:string | – |
| nickname | 昵称 | xs:string | – |
| displayName | 与nickname 同义 | xs:string | – |
| aboutMe | 自我介绍 | xs:string | – |
| birthday | 生日 | xs:date | – |
| interests | 兴趣 | xs:string | 用户任意输入文本 |
| profileUrl | 个人简介信息 URL | xs:string | – |
| thumbnailUrl | 缩略图 URL | xs:string | – |
| gender | 性别 | xs:string | "male" or "female" or "undisclosed" |
| addresses | 地区 | tns:Address | 个人简介中的都道府县 |
| jobType | 职业 | xs:string | 用户任意输入文本 |
| bloodType | 血型 | xs:string | "A" |
| hasApp | 是否已安装应用软件? | xs:boolean | – |
| isVerified | 是否已完成个人认证? | xs:boolean | – |
| isFamous | 是虚拟用户或名人用户吗? | xs:boolean | – |
| grade | 用户等级 | xs:int | 是 "1":简易会员 |
端点URL
Sandbox 环境
https://sb-app.mobage.jp/social/api/restful/v2/people/{guid}/{selector}{-prefix|/|pid}
正式环境
https://app.mobage.jp/social/api/restful/v2/people/{guid}/{selector}{-prefix|/|pid}
API请求
HTTP 方法
- Authorization Code Grant
- GET - 获取个人简介信息、获取好友列表、获取好友个人简介信息
- Client Credentials Grant
- GET - 获取个人简介信息、获取好友列表、获取好友个人简介信息
URI Template 参数
guid
在guid参数中,指定下述任意一项的值。
| 值 | 说明 | 备注 |
|---|---|---|
| @me | viewer 的 guid | 必须 |
| {guid} | 用户 ID | 必须 |
要指定guid中存在的用户 ID,需要用户已安装此应用软件。
selector
在selector参数中,指定下述任意一项的值。
| 值 | 说明 | 备注 |
|---|---|---|
| @self | 对guid 参数指定的用户本人个人简介信息的条目资源 | 必须 |
| @friends | guid 参数指定的用户好友类集资源 | 必须 |
| @all | 与@friends 同义 | 必须 |
pid
selector为 @friends 或 @all 时,可指定pid参数。
| 值 | 说明 | 备注 |
|---|---|---|
| {guid} | 有效的实际用户 ID | 任意 |
查询参数
可指定下述查询参数。
format
可指定响应格式。
| 值 | 说明 | 备注 |
|---|---|---|
| json | "application/json; charset=utf8" | 任意、默认值 |
fields
可指定想要获取的个人简介属性信息。关于可指定的字段名, 请参见People对象字段。
要指定多个时,使用不带空格的逗号 (,) 分隔指定。
省略fields参数时,获取下述全部属性信息。
为提高性能,请尽量只获取必要的属性。
count
获取类集资源的响应时,可指定最多可获取的条目资源条数。在Selector中已指定@friends, @all时,可指定此项。
默认值为50条,最多可指定1000条。
startIndex
指定类集资源的开始值。省略时,自动指定1。例如,发送共100条好友信息页面,每页显示8条,想要获取第2页的信息时,count值指定 8,startIndex值指定9。
filterBy
selector为 @friends 或 @all 时,可使用filterBy。
指定filterBy后,可对响应反馈的person对象类集添加搜索条件。在filterBy值中,指定搜索条件的关键字段。
目前可指定的filterBy值如下表所示。
| filterBy | 说明 |
|---|---|
| hasApp | 是否已安装应用软件? |
要指定filterBy,需要已指定filterOp, filterValue。
filterOp
selector为 @friends 或 @all 时,可使用filterOp。
指定filterOp后,可对响应反馈的person对象类集添加搜索条件。在filterOp值中,指定对搜索条件的关键字和值的评价方式。
目前可指定的 filterOp值如下表所示。
| filterOp | 说明 |
|---|---|
| equals | filterBy中指定的字段与filterValue中指定的值是否一致? |
要指定filterOp,需要已指定filterBy, filterValue。
filterValue
selector为 @friends 或 @all 时,可使用filterValue。
指定filterValue后,可对响应反馈的person对象类集添加搜索条件。可在filterValue值中对搜索条件的关键字指定评价值。
目前可指定的filterValue值如下表所示。
| filterValue | 说明 |
|---|---|
| true | 真值 |
| false | 假值 |
要指定filterValue,需要已指定filterBy, filterOp。
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 端的问题导致失败 |
注意事项
- 在selector 中指定 @friend, @all 并获取好友列表时,为防止超载,好友列表可能会在最长10分钟左右之内不刷新。
- 即使是已通过个人认证的用户,如果被审查部门认定为不当用户,那么会被判定为isVerified 未通过个人认证。
- 用户未进行 aboutMe / jobType / bloodType 等设置时,反馈值为 null。
- 用户在mobage个人简介设置中选择“不显示”生日时,不反馈birthday值。选择“不显示”年龄时,公历格式为 "0000-12-31"。
- guid 中指定的用户不存在时,响应代码反馈 404。
- 用户未安装此应用软件时,在fields 指定为hasApp 的请求中,反馈响应代码200 和逻辑值。
- isFamous 为true的用户是受Mobage管理的虚拟用户,因此不会使用此应用,与普通用户区别对待。
样例
viewer 个人简介信息的获取
以application/json 格式获取id, nickname, profileUrl, thumbnailUrl 字段的viewer 个人简介信息。
请求格式
GET /api/restful/v2/people/@me/@self?fields=id,nickname,profileUrl,thumbnailUrl&format=json
响应格式
200 OK
{
"nickname" : "Mobage太郎",
"thumbnailUrl" : "http://sb-sp.mbga.jp/img_u/10000/0.0.gif",
"id" : "sb.mbga.jp:10000",
"hasApp" : true,
"profileUrl" : "http://sb-sp.mbga.jp/_u?u=10000"
}
不指定字段,获取viewer 个人简介信息的样例响应。
请求格式
GET /api/restful/v2/people/@me/@self?format=json
响应格式
200 OK
{
"nickname" : "Mobage太郎",
"id" : "sb.mbga.jp:10000"
}
viewer 好友信息的获取
以application/json 格式,获取id, nickname, profileUrl, thumbnailUrl 字段的viewer 好友信息。
请求格式
GET /api/restful/v2/people/@me/@friends?fields=id,nickname,profileUrl,thumbnailUrl,hasApp&format=json&count=10&startIndex=1
响应格式
200 OK
{
"entry" : [
{
"nickname" : "好友A",
"thumbnailUrl" : "http://sb-sp.mbga.jp/img_u/10001/0.0.gif",
"id" : "sb.mbga.jp:10001",
"hasApp": true,
"profileUrl" : "http://sb-sp.mbga.jp/_u?u=10001"
},
{
"nickname" : "好友B",
"thumbnailUrl" : "http://sb-sp.mbga.jp/img_u/10002/0.0.gif",
"id" : "sb.mbga.jp:10002",
"hasApp": false,
"profileUrl" : "http://sb-sp.mbga.jp/_u?u=10002"
},
{
"nickname" : "好友C",
"thumbnailUrl" : "http://sb-sp.mbga.jp/img_u/10003/0.0.gif",
"id" : "sb.mbga.jp:10003",
"hasApp" : true,
"profileUrl" : "http://sb-sp.mbga.jp/_u?u=10003"
}
],
"startIndex" : 1,
"itemsPerPage" : 10,
"totalResults" : 3
}
更新履历
- 2015/12/02
- 已支持Client Credentials Grant ,故补充。
- 2014/11/27
- 修改样例中的响应格式