Leaderboard API

This page is not available in English.
Please select another language.

リーダーボード情報の取得、スコアランキングの取得、スコアの追加/更新/削除/加算/減算をおこなう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 フィールド

値

説明

単位

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 メソッド

Proxy モデル

Trusted モデル

エンドポイント 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 パラメータは下記のいずれかの値を指定します。

値

説明

備考

@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

 

更新履歴

  • 2014/03/19
    • countの説明を追加
  • 2013/09/26
    • 新規作成

PREVIOUS

Leaderboard

NEXT

TextData

Mobage Developers