Leaderboard
概要
リーダーボード情報の取得、スコアランキングの取得、スコアの追加/更新/削除/加算/減算をおこなう API です。
Leaderboard オブジェクトフィールド
リーダーボード情報オブジェクトです。リーダーボード情報の取得で使用されます。各値は Mobage Developers Japan(デベロッパーサイト) で設定することができます。
値 | 説明 | 型 | Read-Only | 補足 |
|---|---|---|---|---|
id | リーダーボードのid | string | Read-Only | – |
appId | アプリID | string | Read-Only | – |
title | タイトル | string | Read-Only | – |
scoreFormat | スコアフォーマット | string | Read-Only | フォーマットはスコアを表示するために使用されます。値のリストは、以下の「Leaderboard.scoreFormat の値について」を参照してください。 |
scorePrecision | スコア小数点以下の桁数 | int | Read-Only | – |
iconUrl | アイコンのURL | string | Read-Only | – |
allowLowerScore | スコア上書き設定 | boolean | Read-Only |
|
allowNegativeScore | 負のスコア設定 | boolean | Read-Only |
|
allowTiedRank | 同点順位設定 | boolean | Read-Only |
|
reverse | ソート設定 | boolean | Read-Only |
|
defaultScore | デフォルトスコア | int | Read-Only | – |
archived | アーカイブ | boolean | Read-Only | true の場合はリーダーボードはクローズされスコア更新できません。閲覧のみになります。 |
published | 生成日時 | dateTime | Read-Only | GMT |
updated | 更新日時 | dateTime | Read-Only | GMT |
Leaderboard.scoreFormat の値について
scoreFormat は Mobage Developers Japan(デベロッパーサイト)でのフォーマット設定に応じて、以下の Numeric Expression Fields もしくは Time Expression Fields の値が返却されます。
Numeric Expression フィールド
| 値 | 説明 | 単位 |
|---|---|---|
| integer | 整数 | – |
| decimal | 小数 | – |
Time Expression フィールド
| 値 | 説明 | 単位 |
|---|---|---|
| hours | HH.zzz | 秒 |
| minutes | MM.zzz | 秒 |
| seconds | SS.zzz | 秒 |
| day_second | DD HH:MM:SS.zzz | 秒 |
| day_minute | DD HH:MM.zzz | 秒 |
| day_hour | DD HH.zzz | 秒 |
| hour_second | HH:MM:SS.zzz | 秒 |
| hour_minute | HH:MM.zzz | 秒 |
| minute_second | MM:SS.zzz | 秒 |
scoreFormat と displayValue の関係について
Leaderboard.scoreFormat によってスコアオブジェクトの displayValue のフォーマットが変化します 。
組み合わせの例
| scoreFormat | value | displayValue |
|---|---|---|
| decimal | 100 | 100.0 |
| hours | 3600 | 1 |
| minute_second | 3650 | 60:50 |
スコアオブジェクトフィールド
スコアオブジェクトです。スコアランキングの取得、スコアの追加/更新/削除/加算/減算で使用されます。スコアの値の変更は value に対してのみ行います。
| 値 | 説明 | 型 | Read-Only |
|---|---|---|---|
| userId | ユーザー ID | string | Read-Only |
| value | スコアの値 | int | |
| displayValue | フォーマットルールの値 | string | Read-Only |
| rank | スコアランク | int | Read-Only |
APIリクエスト
HTTP メソッド
Authorization Code Grant
- GET
- PUT
- POST
- DELETE
Client Credentials Grant
-
GET
-
PUT
-
POST
-
DELETE
-
エンドポイント URL
-
-
Sandbox 環境
https://sb-app.mobage.jp/social/api/restful/v2/leaderboards/{appId}/{leaderboardId}/{userId}/{selector} -
本番環境
https://app.mobage.jp/social/api/restful/v2/leaderboards/{appId}/{leaderboardId}/{userId}/{selector}URI Template パラメータ
appId
appId パラメータは下記のいずれかの値を指定します。
| 値 | 説明 | 備考 |
|---|---|---|
| @app | 現在実行中のアプリケーション ID | 必須 |
leaderboardId
leaderboardId パラメータは下記のいずれかの値を指定します。
| 値 | 説明 | 備考 |
|---|---|---|
| {leaderboardId} | リーダーボードを指定する値 (leaderboards.id フィールド値) を入力します。 | リーダーボード情報取得時は任意、その他は必須 |
userId
userId パラメータは下記のいずれかの値を指定します。
| 値 | 説明 | 備考 |
|---|---|---|
| @me | viewer の userId | 必須 |
| {userId} | ユーザー ID | 必須 |
selector
selector パラメータは下記のいずれかの値を指定します。
| 値 | 説明 | 備考 |
|---|---|---|
| @self | userId パラメータで指定したユーザースコアに対するエントリリソース | 必須 |
| @friends | userId パラメータで指定したユーザーの友達のコレクションリソース | 必須 |
| @all | @friends と同義 | 必須 |
| @aroundme | userId パラメータで指定したユーザーのランクに近いランクのユーザ情報のコレクションリソース | 必須 |
クエリパラメータ
下記のクエリパラメータを指定する事が出来ます。
format
レスポンス形式を指定する事が出来ます。
| 値 | 説明 | 備考 |
|---|---|---|
| json | "application/json; charset=utf8" | 任意、デフォルト値 |
fields
取得したいスコア情報、リーダーボード情報を指定する事が出来ます。指定可能なフィールド名については Score オブジェクトフィールド、Leaderboardオブジェクトフィールドを参照して下さい。複数指定する場合はスペース無しのカンマ (,) 区切りで指定します。fields パラメータを省略した場合、全てのフィールドが取得できます。
count
コレクションリソースとしてレスポンスを取得する際に、最大何件のエントリリソースを取得するかを指定出来ます。selector に @all または @aroundme を指定した場合に指定出来ます。
デフォルト値は 50 件で、最大 1000 件まで指定出来ます。
パフォーマンス向上の為に、必要な件数のみを取得するようにして下さい。
startIndex
コレクションリソースの開始値を指定します。省略時は 1 が指定されます。
sortBy
sortBy と sortOrder を指定すると、レスポンスとして返って来るオブジェクトのコレクションに対してソート条件を加える事が出来ます。
sortBy 値はソートのキーとなるフィールドを指定する事が出来ます。指定可能な sortBy 値は以下になります。sortBy を指定する場合、sortOrder も指定されている必要があります。
| sortBy | 説明 |
|---|---|
| rank | スコアランク |
| value | スコアの値 |
sortOrder
sortOrder はコレクションの取得時にのみ使う事が出来ます。
sortBy と sortOrder を指定すると、レスポンスとして返って来るオブジェクトのコレクションに対してソート条件を加える事が出来ます。
sortOrder 値はソート時の昇順、降順を指定する事が出来ます。指定可能な sortOrder 値は以下の表になります。sortOrder を指定する場合、sortBy も指定されている必要があります。
| sortOrder | 説明 |
|---|---|
| ascending | 昇順 |
| descending | 降順 |
APIレスポンス
レスポンスコード
API のレスポンスコードは以下のいずれかになります。
| リクエスト HTTP メソッド | レスポンスコード | レスポンスメッセージ | 説明 |
|---|---|---|---|
| GET | 200 | OK | データ の取得が正常に終了しました |
| POST/PUT/DELETE | 202 | Accepted | データ の更新または削除が成功しました |
| GET/POST/PUT/DELETE | 400 | Bad Request | リクエストデータが不正です |
| GET/POST/PUT/DELETE | 401 | Unauthorized | OAuth による認可が失敗しています |
| GET/PUT/DELETE | 403 | Forbidden | 認証エラー以外の理由でアクセス出来ない場合です |
| GET/PUT/DELETE | 404 | Not Found | データ が存在しないか、物理的に削除されています |
| POST/PUT | 409 | Conflict | スコア値が更新/加減できない場合です |
| GET/POST/PUT/DELETE | 429 | Too Many Requests | リクエスト数が制限を超えた場合です |
| GET/POST/PUT/DELETE | 500 | Internal Server Error | API 側の問題による失敗です |
| GET/POST/PUT/DELETE | 503 | Service Unavailable | API 側の制限を超えて一時的に利用できない場合です |
サンプル
リーダーボード一覧の取得
現在実行中のアプリケーション ID に紐づいているリーダーボードの一覧を取得します。
リクエスト形式
GET /api/restful/v2/leaderboards/@app
レスポンス形式
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"entry": [
{
"id": "1334",
"appId": "12000129",
"title": "Best time ranking",
"scoreFormat": "minute_second",
"scorePrecision": 0,
"iconUrl": "http://example.com/time_ranking.png",
"allowLowerScore": false,
"reverse": false,
"archived": false,
"defaultScore": null,
"published": "2012-02-14 21:00:12T",
"updated": "2012-02-14 21:00:12T"
},
{
"id": "1373",
"appId": "12000129",
"title": "The number of win ranking",
"scoreFormat": "integer",
"scorePrecision": 0,
"iconUrl": "http://example.com/win_ranking.png",
"allowLowerScore": false,
"reverse": true,
"archived": false,
"defaultScore": 0,
"published": "2012-02-14 21:00:12T",
"updated": "2012-02-14 21:00:12T"
}
],
"totalResults": 2,
"itemsPerPage": 50,
"startIndex": 1,
"sorted": false
}
指定リーダーボード情報の取得
指定のリーダーボードの情報を Leaderboard ID から取得します。
リクエスト形式
GET /leaderboards/@app/1334
レスポンス形式
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"id": "1334",
"appId": "12000129",
"title": "Best time ranking",
"scoreFormat": "minute_second",
"scorePrecision": 0,
"iconUrl": "http://example.com/time_ranking.png",
"allowLowerScore": false,
"reverse": false,
"archived": false,
"defaultScore": null,
"published": "2012-02-14 21:00:12T",
"updated": "2012-02-14 21:00:12T"
}
複数の指定リーダーボード情報の取得
複数の指定のリーダーボードの情報を Leaderboard ID から取得します。
リクエスト形式
GET /api/restful/v2/leaderboards/@app/1334,1373
レスポンス形式
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"entry": [
{
"id": "1334",
"appId": "12000129",
"title": "Best time ranking",
"scoreFormat": "minute_second",
"scorePrecision": 0,
"iconUrl": "http://example.com/time_ranking.png",
"allowLowerScore": false,
"reverse": false,
"archived": false,
"defaultScore": null,
"published": "2012-02-14 21:00:12T",
"updated": "2012-02-14 21:00:12T"
},
{
"id": "1373",
"appId": "12000129",
"title": "The number of win ranking",
"scoreFormat": "integer",
"scorePrecision": 0,
"iconUrl": "http://example.com/win_ranking.png",
"allowLowerScore": false,
"reverse": true,
"archived": false,
"defaultScore": 0,
"published": "2012-02-14 21:00:12T",
"updated": "2012-02-14 21:00:12T"
}
],
"totalResults": 2,
"itemsPerPage": 50,
"startIndex": 1,
"sorted": false
}
トップスコアリストの取得
指定するリーダーボードにおいて、上位 50 のユーザースコアを取得する。
リクエスト形式
GET /api/restful/v2/leaderboards/@app/1334/@me/@all?sortBy=rank&sortOrder=asscending&count=50&startIndex=1
レスポンス形式
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"entry": [
{
"userId": "10028",
"value": 128,
"displayValue": "2:08",
"rank": 1,
},
{
"userId": "10029",
"value": 130,
"displayValue": "2:10",
"rank": 2,
},
/* ... */
],
"totalResults": 2,
"itemsPerPage": 50,
"startIndex": 1,
"sorted": true
}
指定ユーザーの友達のスコアリストの取得
指定するリーダーボードにおいて、ユーザーの友達スコアを取得する。
リクエスト形式
GET /api/restful/v2/leaderboards/@app/1334/@me/@friends?sortBy=rank&sortOrder=ascending
レスポンス形式
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"entry": [
{
"userId": "10028",
"value": 128,
"displayValue": "2:08",
"rank": 1,
},
{
"userId": "10029",
"value": 130,
"displayValue": "2:10",
"rank": 2,
},
],
"totalResults": 2,
"itemsPerPage": 50,
"startIndex": 1,
"sorted": true
}
指定ユーザーのスコア取得
指定するリーダーボードにおいて、指定ユーザーのスコアを取得することができます。
リクエスト形式
GET /api/restful/v2/leaderboards/@app/1334/10128/@self
レスポンス形式
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"userId": "10128",
"value": 128,
"displayValue": "2:08",
"rank": 1
}
指定ユーザーのランクに近いランクのユーザ情報の取得
指定するリーダーボードにおいて、取得する近いランクのユーザー情報についての事例は以下になります。
-
指定ユーザーのランクが 100 かつ count 設定が 20 の場合は、90 から 109 のランクのユーザー情報が取得される。
-
指定ユーザーのランクが 100 と count 設定が 21 の場合は、90 から 110 のランクのユーザーランク情報が取得される。
-
指定ユーザーのランクが 6 と count 設定が 50 の場合は、1 から 50 のユーザーのランク情報が取得される。
警告
ただし、同点順位設定で「同スコアを同じ順位として扱う」にチェックが入っている(allowTiedRank = true) 場合は、必ずしも上記のような 90 から 110 のランクのランキングが取れるわけではなく、count 設定分の人数が取得されます。例えば、1, 2, 3, 4, 4, 4, 7, 8, 8, 10 というランキングで、自分が 7 、count 設定が 5 の場合、4, 4, 7, 8, 8 のランクのユーザー情報が取得できます。 :::
リクエスト形式
GET /api/restful/v2/leaderboards/@app/aaa111/10128/@aroundme?count=3&sortBy=value&sortOrder=descending
レスポンス形式
{
"entry" : [
{
"value" : 300,
"displayValue" : "300.00",
"userId" : "10768",
"rank" : 3
},
{
"value" : 200,
"displayValue" : "200.00",
"userId" : "10128",
"rank" : 2
},
{
"value" : 100,
"displayValue" : "100.00",
"userId" : "10444",
"rank" : 1
}
],
"startIndex" : 1,
"sorted" : true,
"itemsPerPage" : 3,
"totalResults" : 6
}
指定ユーザーのスコアの追加/更新
指定リーダーボードとユーザーのスコアの追加または更新します。スコアの追加(新規登録)、スコアを更新(スコアの上書き)ともに PUT で行います。
スコアの追加/更新には必ずクエリパラメータに fiels=value を指定してください。
「常に上書きする」にチェックを入れない (allowLowerScore = false) 場合、かつソート設定が「降順」(reverse = false)の場合には、ユーザーの現在のスコア以下の値に更新することができません。
「常に上書きする」にチェックを入れない (allowLowerScore = false) 場合、かつソート設定が「昇順」(reverse = true)の場合には、ユーザーの現在のスコア以上の値に更新することができません。
「負のスコアを許可する」にチェックを入れない (allowNegativeScore = false) 場合には、負のスコアを指定すると409のエラーコードでレスポンスを返します。
リクエスト形式
PUT /api/restful/v2/leaderboards/@app/1334/@me/@self?fields=value
Content-Type: application/json; charset=utf-8
{
"value": 100
}
レスポンス形式
202 Accepted
Content-Type: application/json; charset=utf-8
{
"rank": 57,
"value": 100,
"userId": "mbga.jp:1192",
"displayValue": "1:40",
}
スコア更新時のエラー
「常に上書きする」にチェックを入れない (allowLowerScore = false) 場合、かつソート設定が「降順」(reverse = false)の場合には、指定ユーザーの既存スコアよりも低いスコアで更新しようとした場合に返されるエラーレスポンスを記載します。
「常に上書きする」にチェックを入れない (allowLowerScore = false) 場合、かつソート設定が「昇順」(reverse = true)の場合には、指定ユーザーの既存スコアよりも高いスコアで更新しようとした場合にも同様のエラーが返ります。
リクエスト形式
PUT /api/restful/v2/leaderboards/@app/1334/@me/@self?fields=value
Content-Type: application/json; charset=utf-8
{
"value": 80
}
レスポンス形式
409 Conflict
Content-Type: "application/json; charset=utf-8"
{
"Error" : {
"Code" : "409",
"Message" : "Conflict (The leaderboard (leaderboard_name) doesn't allow a worse score (appId: 1200xxxx, current_score: 100, new_score: 80))"
}
}
指定ユーザーの既存のスコアを加算する
指定ユーザーの既存のスコアに対して、スコアの加算を行うことができます。
「常に上書きする」にチェックを入れない (allowLowerScore = false) 場合、かつソート設定が「昇順」(reverse = true)の場合は、409 のエラーコードでレスポンスを返します。
リクエスト形式
POST /api/restful/v2/leaderboards/@app/1334/@me/@self/increment
Content-Type: application/json; charset=utf-8
{
"value": 100
}
レスポンス形式
202 Accepted
Content-Type: application/json; charset=utf-8
{
"rank": 14,
"value": 1100,
"userId": "12345",
"displayValue": "1100"
}
指定ユーザーの既存のスコアを減算する
指定ユーザーの既存のスコアに対して、スコアの減算を行うことができます。
「常に上書きする」にチェックを入れない (allowLowerScore = false) 場合、かつソート設定が「降順」(reverse = false)の場合は、409 のエラーコードでレスポンスを返します。
「負のスコアを許可する」にチェックを入れない (allowNegativeScore = false) 場合に、減算結果が 0 未満(負の値)になるスコア減算を行っても、スコアは必ず 0 になります。
リクエスト形式
POST /api/restful/v2/leaderboards/@app/1334/@me/@self/decrement
Content-Type: application/json; charset=utf-8
{
"value": 100
}
レスポンス形式
202 Accepted
Content-Type: application/json; charset=utf-8
{
"rank": 29,
"value": 900,
"userId": "12345",
"displayValue": "900"
}
指定ユーザーのスコアの削除
指定ユーザーのスコア情報を削除することができます。
リクエスト形式
DELETE /api/restful/v2/leaderboards/@app/1334/@me/@self
Content-Type: application/json; charset=utf-8
レスポンス形式
202 Accepted
Content-Type: application/json; charset=utf-8