People
people.get
ユーザーのプロフィール情報及び、ユーザーの友達一覧を取得する為の API です。
API の定義
| REST Base URI | http://app.mbga-platform.jp/social/api/restful/v2 ( Service ) http://app.sb.mbga-platform.jp/social/api/restful/v2 ( Sandbox ) |
| REST HTTP Method | GET |
| REST URI Fragment | ``` /people/{-list |
| REST Query Parameters | GetPerson-Request-Parameters GetPeople-Request-Parameters |
| Return Object | Person (/people/{userId}/@self または /people/{userId}/@all/{personId}, /people/{userId}/@friends/{personId} の場合) Collection |
認可
| type | permission | description |
|---|---|---|
| ANONYMOUS | false | 未認証でのアクセス |
| SECURITY_TOKEN | false | セキュリティトークンを用いた認証 |
| OAUTH_MOBILE | false | モバイル用で発行された OAuth Token を用いた認証 |
| OAUTH_CONSUMER | true | Consumer Request を用いた認証 |
RESTful API レスポンスコード
| HTTP Status Code | HTTP Status Message | JSON-RPC Error Codes | Meaning |
|---|---|---|---|
| 200 | OK | – | データの取得が成功した場合 |
| 400 | Bad Request | -32700, -32600, -32601, -32602, 400 | クライアント側のリクエストデータが不正です |
| 401 | Unauthorized | 401 | 認証エラーです |
| 403 | Forbidden | 403 | リソースは存在するが認証エラー以外の理由でアクセス出来ない場合です |
| 404 | Not Found | 404 | 存在しないリソースです |
| 405 | Method Not Allowed | 405 | その操作が許可されていない場合です |
| 500 | Internal Server Error | -32603 | API サーバー側のエラーです |
| 503 | Service Unavailable | – | 一時的に API が利用不可となっている場合です |
JSON-RPC エラーコード
エラー時の Error オブジェクトの code フィールドに含まれる値です。
| RPC Code | Meaning |
|---|---|
| -32700 (Parse error) | 不正な JSON format です |
| -32600 (Invalid Request) | 不正な JSON-RPC リクエストです |
| -32601 (Method not found) | 存在しないメソッドまたは利用不能なメソッドです |
| -32602 (Invalid params) | 不正な API リクエストパラメータです |
| -32603 (Internal server error) | API サーバー側のエラーです |
| 400 (Bad Request) | 他のエラーに該当しないクライアント側の不正なリクエストです |
| 401 (Unauthorized) | 認証エラーです |
| 403 (Forbidden) | リソースは存在するが認証エラー以外の理由でアクセス出来ない場合です |
| 404 (Not Found) | 存在しないリソースです |
| 405 (Method Not Allowed) | その操作が許可されていない場合です |
データ型
Get-Person-Request-Parameters
userId, groupId は URI Template Parameters として指定し、それ以外のパラメータは Query String として指定します。
| Name | Type | Description |
|---|---|---|
| userId | UserId, Array | Required |
| groupId | GroupId | Required |
| fields | Array | Optional |
ベースとなるデータ型
- Starndard-Request-Parameters
Get-People-Request-Parameters
userId, groupId, personId は URI Template Parameters として指定し、それ以外のパラメータは Query String として指定します。
| Name | Type | Description |
|---|---|---|
| userId | UserId, Array | Required |
| groupId | GroupId | Required |
| personId | UserId, Array | Optional |
| fields | Array | Optional |
ベースとなるデータ型
- Starndard-Request-Parameters
- Collection-Request-Parameters
Starndard-Request-Parameters
サポートしているフィールド一覧は下記になります。
| Name | Type | Description |
|---|---|---|
| format | String | Optional 'json' のみ指定可能 |
詳しくは 6.1 Standard Request Parameters - OpenSocial Core API Server Specification をご参照下さい。
Collection-Request-Parameters
サポートしているフィールド一覧は下記になります。
| Name | Type | Description |
|---|---|---|
| filterBy | String or Array | Optional, 指定可能なフィールドは Person.id と Person.hasApp |
| filterOp | String or Array | Optional, 指定可能なオペレータは equals のみ |
| filterValue | String or Array | Optional |
| count | Number | Optional 1以上1000以下の整数、デフォルト値は50 |
| sortBy | String | Optional 'id' のみ指定可能 |
| sortOrder | String | Optional 'ascending' or 'descending' |
| startIndex | Number | Optional 1以上の整数値 |
詳しくは 6.2 Collection Request Parameters - OpenSocial Core API Server Specification をご参照下さい。
Person
OpenSocial Social Data Specification 1.0 で規定されている Person オブジェクトのフィールドは下記です。
| Name | Type | Description |
|---|---|---|
| id | UserId | Person の id 値です |
| nickname | String | Person のニックネームです |
| displayName | String | Person の表示名です (Person.nickname と同じ値) |
| aboutMe | String | Person の自己紹介文です |
| birthday | Date | Person の誕生日です |
| interests | Array<PluralField | ユーザーの興味のある事柄です |
| profileUrl | String | Person のプロフィール用URLです (PC) |
| thumbnailUrl | String | Person のサムネイル用URLです (PC) |
| gender | String | Person の性別です |
| hasApp | Boolean | Person がそのアプリケーションをインストールしているかどうかです |
| age | Integer | Person の年齢です |
| addresses | Array<PluralField> | Person の住んでいる場所です (都道府県名) |
Mobageオープンプラットフォーム独自のフィールドは下記です。
Name | Type | Description |
|---|---|---|
jobType | String | Person の職業です |
bloodType | String | Person の血液型です |
isOwner | Boolean | Consumer Request の場合は常に false です |
isViewer | Boolean | Consumer Request の場合は常に false です |
isFamous | Boolean | 仮想ユーザや有名人ユーザであるかどうかです |
isVerified | Boolean | 個人認証が済んでいるかどうかです |
| grade | Integer | ユーザーグレードです以下のいずれかの値になります "1":かんたん会員 "2":通常会員 "3"個人認証済み会員 |
注意事項
- fields パラメータを省略した場合、isOwner, isViewer, id, nickname が選択されます。またこれらのフィールドが選択されていない場合も、レスポンスに含まれます。
- isVerified は個人認証が済んでいるユーザーでも審査部門により不正なユーザーと認定されている場合は、個人認証が済んでいないと判定されます。
- isFamous がtrueのユーザーはMobageで管理された仮想ユーザーになりますのでアプリを利用することはなく、一般ユーザーとは異なる扱いとなります。
サンプルデータ
RESTful API
ユーザーのプロフィール情報を取得する
GET /social/api/restful/v2/people/10091/@self?fields=id,nickname,thumbnailUrl,profileUrl,isVerified
Host: app.sb.mbga-platform.jp
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"isOwner" : false,
"thumbnailUrl" : "http://sb.yahoo-mbga.jp/img_ava/profile/10091/1/xlarge-entire.gif",
"nickname" : "hoge",
"id" : "sb.mbga.jp:10091",
"isVerified" : true,
"isViewer" : false,
"profileUrl" : "http://sb.yahoo-mbga.jp/10091"
}
ユーザーの友達一覧を取得する
GET /social/api/restful/v2/people/10045/@friends?fields=id,nickname,thumbnailUrl,profileUrl
Host: app.sb.mbga-platform.jp
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"entry" : [
{
"isOwner" : false,
"thumbnailUrl" : "http://sb.yahoo-mbga.jp/img_ava/profile/10077/9/xlarge-entire.gif",
"nickname" : "fuga",
"id" : "sb.mbga.jp:10077",
"isViewer" : false,
"profileUrl" : "http://sb.yahoo-mbga.jp/10077"
},
{
"isOwner" : false,
"thumbnailUrl" : "http://sb.yahoo-mbga.jp/img_ava/profile/10093/12/xlarge-entire.gif",
"nickname" : "piyo",
"id" : "sb.mbga.jp:10093",
"isViewer" : false,
"profileUrl" : "http://sb.yahoo-mbga.jp/10093"
}
],
"startIndex" : 1,
"sorted" : false,
"updatedSince" : false,
"itemsPerPage" : 50,
"totalResults" : 2,
"filtered" : false
}
特定のユーザーが友達かどうか判定する
友達の場合は以下のようになります。
GET /social/api/restful/v2/people/10045/@friends/10093
Host: app.sb.mbga-platform.jp
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"isOwner" : false,
"nickname" : "piyo",
"id" : "sb.mbga.jp:10093",
"isViewer" : false
}
友達で無い場合は以下のように 404 Not Found が返って来ます。
GET /social/api/restful/v2/people/10045/@friends/10092
Host: app.sb.mbga-platform.jp
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
{
"Error" : {
"Code" : "404",
"Message" : "Not Found"
}
}
参考資料
OpenSocial Core API Server Specification 1.0
OpenSocial Core Data Specification 1.0
OpenSocial Social API Server Specification 1.0
OpenSocial Social Data Specification 1.0
更新履歴
- 2017/04/06
- 一部レスポンスの記載が間違っていましたので修正
- 2012/11/14
- isFamous フィールドを追加
- 2012/06/14
- isVerified フィールドを追加
- 2011/01/11
- Get-Person-Request-Parameters, Get-People-Request-Parameters の userId の記述を修正