メインコンテンツまでスキップ

Learderboard API

リーダーボード情報の取得、スコアランキングの取得、スコアの追加/更新/削除/加算/減算をおこなうAPIです。

備考

Leaderboard API の使い方
Leaderboard API の詳細な使い方について、下記の各ページをご参照下さい。
ngCore SDK | Native SDK | Unity SDK


Leaderboard オブジェクトフィールド​

リーダーボード情報オブジェクトです。リーダーボード情報の取得で使用されます。各値は Mobage Developers (デベロッパーサイト) で設定することができます。

値

説明

型

Read-Only

名前空間

補足

id

リーダーボードのid

string

Read-Only

http://ns.dena.jp/mbga/gameapi/v2

–

appId

アプリID

string

Read-Only

http://ns.dena.jp/mbga/gameapi/v2

–

title

タイトル

string

Read-Only

http://ns.dena.jp/mbga/gameapi/v2

–

scoreFormat

スコアフォーマット

string

Read-Only

http://ns.dena.jp/mbga/gameapi/v2

フォーマットはスコアを表示するために使用されます。値のリストは、以下の「Leaderboard.scoreFormat の値について」を参照してください。

scorePrecision

スコア小数点以下の桁数

int

Read-Only

http://ns.dena.jp/mbga/gameapi/v2

–

iconUrl

アイコンのURL

string

Read-Only

http://ns.dena.jp/mbga/gameapi/v2

–

allowLowerScore

スコア上書き設定

boolean

Read-Only

http://ns.dena.jp/mbga/gameapi/v2
  • true の場合は既存のスコアよりも高い低いに関わらず常にスコアの更新が可能です。
  • falseの場合は既存のスコアより低いランクになってしまうスコアで更新することができなくなります。

allowNegativeScore

負のスコア設定

boolean

Read-Only

http://ns.dena.jp/mbga/gameapi/v2
  • true の場合は 0 未満のスコアを許可します。
  • false の場合は 0 未満のスコアを許可しません。

allowTiedRank

同点順位設定

boolean

Read-Only

http://ns.dena.jp/mbga/gameapi/v2
  • true の場合は同スコア同ランクで順位付けられたデータが返ります。
  • false の場合は同スコアでも異なるランクで順位付けられたデータが返ります。

reverse

ソート設定

boolean

Read-Only

http://ns.dena.jp/mbga/gameapi/v2
  • true の場合は低スコアがランク上位に入れ替わります。
  • false の場合は、高スコアがランク上位になります。

defaultScore

デフォルトスコア

int

Read-Only

http://ns.dena.jp/mbga/gameapi/v2

–

archived

アーカイブ

boolean

Read-Only

http://ns.dena.jp/mbga/gameapi/v2

true の場合はリーダーボードはクローズされスコア更新できません。閲覧のみになります。

published

生成日時

dateTime

Read-Only

http://ns.dena.jp/mbga/gameapi/v2

GMT

updated

更新日時

dateTime

Read-Only

http://ns.dena.jp/mbga/gameapi/v2

GMT

Leaderboard.scoreFormat の値について​

scoreFormat はデベロッパーサイトでのフォーマット設定に応じて、以下の Numeric Expression Fields もしくは Time Expression Fields の値が返却されます。

Numeric Expression フィールド​

値説明単位
integer整数–
decimal小数–

Time Expression フィールド​

値説明単位
hoursHH.zzz秒
minutesMM.zzz秒
secondsSS.zzz秒
day_secondDD HH:MM:SS.zzz秒
day_minuteDD HH:MM.zzz秒
day_hourDD HH.zzz秒
hour_secondHH:MM:SS.zzz秒
hour_minuteHH:MM.zzz秒
minute_secondMM:SS.zzz秒

scoreFormat と displayValue の関係について​

Leaderboard.scoreFormat によってスコアオブジェクトの displayValue のフォーマットが変化します 。

組み合わせの例​

scoreFormatvaluedisplayValue
decimal100100.0
hours36001
minute_second365060:50

スコアオブジェクトフィールド​

スコアオブジェクトです。スコアランキングの取得、スコアの追加/更新/削除/加算/減算で使用されます。スコアの値の変更は value に対してのみ行います。

値説明型Read-Only
userIdユーザー IDstringRead-Only
valueスコアの値int
displayValueフォーマットルールの値stringRead-Only
rankスコアランクintRead-Only

API リクエスト​

HTTP メソッド​

Proxy モデル​

Trusted モデル​

エンドポイント URL​

  • Sandbox 環境

    http://sb.sp.app.mbga.jp/social/api/restful/v2/leaderboards/{appId}/{leaderboardId}/{userId}/{selector}
  • 本番環境

    http://sp.app.mbga.jp/social/api/restful/v2/leaderboards/{appId}/{leaderboardId}/{userId}/{selector}

エンドポイント URL​

  • Sandbox 環境

    http://sb.sp.mbga-platform.jp/social/api/restful/v2/leaderboards/{appId}/{leaderboardId}/{userId}/{selector}
  • 本番環境

    http://sp.mbga-platform.jp/social/api/restful/v2/leaderboards/{appId}/{leaderboardId}/{userId}/{selector}

URI Template パラメータ​

appId​

appId パラメータは下記のいずれかの値を指定します。

値説明備考
@app現在実行中のアプリケーション ID必須
leaderboardId​

leaderboardId パラメータは下記のいずれかの値を指定します。

値説明備考
{leaderboardId}リーダーボードを指定する値 (leaderboards.id フィールド値) を入力します。リーダーボード情報取得時は任意、その他は必須
userId​

userId パラメータは下記のいずれかの値を指定します。

値説明備考
@meviewer の userId必須
{userId}ユーザー ID必須
selector​

selector パラメータは下記のいずれかの値を指定します。

値説明備考
@selfuserId パラメータで指定したユーザースコアに対するエントリリソース必須
@friendsuserId パラメータで指定したユーザーの友達のコレクションリソース必須
@all@friends と同義必須
@aroundmeuserId パラメータで指定したユーザーのランクに近いランクのユーザ情報のコレクションリソース必須

クエリパラメータ​

下記のクエリパラメータを指定する事が出来ます。

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 メソッドレスポンスコードレスポンスメッセージ説明
GET200OKデータ の取得が正常に終了しました
POST/PUT/DELETE202Acceptedデータ の更新または削除が成功しました
GET/POST/PUT/DELETE400Bad Requestリクエストデータが不正です
GET/POST/PUT/DELETE401UnauthorizedOAuth による認可が失敗しています
GET/PUT/DELETE403Forbidden認証エラー以外の理由でアクセス出来ない場合です
GET/PUT/DELETE404Not Foundデータ が存在しないか、物理的に削除されています
POST/PUT409Conflictスコア値が更新/加減できない場合です
GET/POST/PUT/DELETE429Too Many Requestsリクエスト数が制限を超えた場合です
GET/POST/PUT/DELETE500Internal Server ErrorAPI 側の問題による失敗です
GET/POST/PUT/DELETE503Service UnavailableAPI 側の制限を超えて一時的に利用できない場合です

サンプル​

リーダーボード一覧の取得​

現在実行中のアプリケーション 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

更新履歴​

  • 2014/03/19
    • countの説明を追加
  • 2013/09/26
    • 新規作成
  • Leaderboard オブジェクトフィールド
  • Leaderboard.scoreFormat の値について
    • Numeric Expression フィールド
    • Time Expression フィールド
    • scoreFormat と displayValue の関係について
  • スコアオブジェクトフィールド
  • API リクエスト
  • API レスポンス
    • レスポンスコード
  • サンプル
    • リーダーボード一覧の取得
    • 指定リーダーボード情報の取得
    • 複数の指定リーダーボード情報の取得
    • トップスコアリストの取得
    • 指定ユーザーの友達のスコアリストの取得
    • 指定ユーザーのスコア取得
    • 指定ユーザーのランクに近いランクのユーザ情報の取得
    • 指定ユーザーのスコアの追加/更新
    • 指定ユーザーの既存のスコアを加算する
    • 指定ユーザーの既存のスコアを減算する
    • 指定ユーザーのスコアの削除
  • 更新履歴