跳到主要内容

People

概要​

获取用户个人简介信息和用户好友列表所需的API。

People 对象字段​

向People API 发送 GET 请求后,会反馈People 对象。只能获取URI Template 参数的 fields 参数中指定的字段。
值说明类型补充
id用户 IDxs:string–
nickname昵称xs:string–
displayName与nickname 同义xs:string–
aboutMe自我介绍xs:string–
birthday生日xs:date–
interests兴趣xs:string用户任意输入文本
profileUrl个人简介信息 URLxs:string–
thumbnailUrl缩略图 URLxs: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参数中,指定下述任意一项的值。

值说明备注
@meviewer 的 guid必须
{guid}用户 ID必须

要指定guid中存在的用户 ID,需要用户已安装此应用软件。

selector​

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

值说明备注
@self对guid 参数指定的用户本人个人简介信息的条目资源必须
@friendsguid 参数指定的用户好友类集资源必须
@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说明
equalsfilterBy中指定的字段与filterValue中指定的值是否一致?

要指定filterOp,需要已指定filterBy, filterValue。

filterValue​

selector为 @friends 或 @all 时,可使用filterValue。
指定filterValue后,可对响应反馈的person对象类集添加搜索条件。可在filterValue值中对搜索条件的关键字指定评价值。

目前可指定的filterValue值如下表所示。

filterValue说明
true真值
false假值

要指定filterValue,需要已指定filterBy, filterOp。

API 响应​

响应代码​

API 的响应代码为以下中的任意一项。

请求 HTTP 方法响应代码响应信息说明
GET200OK数据获取正常完成
GET400Bad Request请求数据不当
GET401UnauthorizedOAuth 验证失败
GET403Forbidden由于认证错误以外的原因导致不能访问的情况
GET404Not Found资源不存在
GET405Method Not Allowed方法不允许
GET500Internal Server ErrorAPI 端的问题导致失败

注意事项​

注意
  • 在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
    • 修改样例中的响应格式