Class: Gs2::Ranking::Client

Inherits:
Core::AbstractClient
  • Object
show all
Defined in:
lib/gs2/ranking/Client.rb

Overview

GS2-Ranking クライアント

Author:

  • Game Server Services, Inc.

Constant Summary collapse

@@ENDPOINT = 
'ranking'

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(region, gs2_client_id, gs2_client_secret) ⇒ Client

コンストラクタ

Parameters:

  • region (String) —

    リージョン名

  • gs2_client_id (String) —

    GSIクライアントID

  • gs2_client_secret (String) —

    GSIクライアントシークレット



17
18
19
 
# File 'lib/gs2/ranking/Client.rb', line 17

def initialize(region, gs2_client_id, gs2_client_secret)
  super(region, gs2_client_id, gs2_client_secret)
end

Class Method Details

.ENDPOINT(v = nil) ⇒ Object

デバッグ用。通常利用する必要はありません。



22
23
24
25
26
27
28
 
# File 'lib/gs2/ranking/Client.rb', line 22

def self.ENDPOINT(v = nil)
  if v
    @@ENDPOINT = v
  else
    return @@ENDPOINT
  end
end

Instance Method Details

#create_game_mode(request) ⇒ Array

ゲームモードを作成

ゲームモードを作成すると、ゲームモードの設定としてランキングが昇順なのか、降順なのかを設定できます。
レースゲームのようなタイムの値が小さいほど上位のランキングの場合は昇順を、
アクションゲームなどで、スコアの値が大きいほど上位のランキングの場合は降順を選択します。

他に、集計間隔を15分以上、24時間以下で分単位で設定できます。
ランキングを更新したい間隔に合わせて設定することになります。
集計処理毎に費用が発生するため、高頻度であればあるほど利用料金は高くなります。

Parameters:

  • request (Array) —

    • rankingTableName => ランキングテーブル名

    • gameMode => ゲームモード名

    • asc => ソート方向

    • calcInterval => 集計間隔(分)

Returns:

  • (Array) —

    • item

      • gameModeId => ゲームモードID

      • rankingTableId => ランキングテーブルID

      • gameMode => ゲームモード名

      • ownerId => オーナーID

      • asc => ソート方向

      • calcInterval => 集計間隔(分)

      • lastCalcAt => 最終集計日時

      • createAt => 作成日時

      • updateAt => 更新日時



218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
 
# File 'lib/gs2/ranking/Client.rb', line 218

def create_game_mode(request)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('rankingTableName'); raise ArgumentError.new(); end
  if not request['rankingTableName']; raise ArgumentError.new(); end
  body = {}
  if request.has_key?('gameMode'); body['gameMode'] = request['gameMode']; end
  if request.has_key?('asc'); body['asc'] = request['asc']; end
  if request.has_key?('calcInterval'); body['calcInterval'] = request['calcInterval']; end
  query = {}
  return post(
      'Gs2Ranking',
      'CreateGameMode',
      @@ENDPOINT,
      '/ranking/' + request['rankingTableName'] + '/mode',
      body,
      query);
end

#create_ranking_table(request) ⇒ Array

ランキングテーブルを作成

GS2-Ranking を利用するには、まずランキングテーブルを作成する必要があります。
1つのランキングテーブルには複数のゲームモードのランキングを格納することができます。

Parameters:

  • request (Array) —

    • name => ランキングテーブル名

    • description => 説明文

Returns:

  • (Array) —

    • item

      • rankingTableId => ランキングテーブルID

      • ownerId => オーナーID

      • name => ランキングテーブル名

      • description => 説明文

      • createAt => 作成日時

      • updateAt => 更新日時



72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/gs2/ranking/Client.rb', line 72

def create_ranking_table(request)
  if not request; raise ArgumentError.new(); end
  body = {}
  if request.has_key?('name'); body['name'] = request['name']; end
  if request.has_key?('description'); body['description'] = request['description']; end
  query = {}
  return post(
        'Gs2Ranking', 
        'CreateRankingTable', 
        @@ENDPOINT, 
        '/ranking',
        body,
        query);
end

#delete_game_mode(request) ⇒ Object

ゲームモードを削除

Parameters:

  • request (Array) —

    • rankingTableName => ランキングテーブル名

    • gameMode => ゲームモード名



307
308
309
310
311
312
313
314
315
316
317
318
319
320
 
# File 'lib/gs2/ranking/Client.rb', line 307

def delete_game_mode(request)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('rankingTableName'); raise ArgumentError.new(); end
  if not request['rankingTableName']; raise ArgumentError.new(); end
  if not request.has_key?('gameMode'); raise ArgumentError.new(); end
  if not request['gameMode']; raise ArgumentError.new(); end
  query = {}
  return delete(
      'Gs2Ranking',
      'DeleteGameMode',
      @@ENDPOINT,
      '/ranking/' + request['rankingTableName'] + '/mode/' + request['gameMode'],
      query);
end

#delete_ranking_table(request) ⇒ Object

ランキングテーブルを削除

Parameters:

  • request (Array) —

    • rankingTableName => ランキングテーブル名



145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/gs2/ranking/Client.rb', line 145

def delete_ranking_table(request)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('rankingTableName'); raise ArgumentError.new(); end
  if not request['rankingTableName']; raise ArgumentError.new(); end
  query = {}
  return delete(
        'Gs2Ranking', 
        'DeleteRankingTable', 
        @@ENDPOINT, 
        '/ranking/' + request['rankingTableName'],
        query);
end

#describe_game_mode(request, pageToken = nil, limit = nil) ⇒ Array

ゲームモードリストを取得

Parameters:

  • request (Array) —

    • rankingTableName => ランキングテーブル名

  • pageToken (String) (defaults to: nil) —

    ページトークン

  • limit (Integer) (defaults to: nil) —

    取得件数

Returns:

  • (Array) —

    • items

      Array

      • gameModeId => ゲームモードID

      • rankingTableId => ランキングテーブルID

      • gameMode => ゲームモード名

      • ownerId => オーナーID

      • asc => ソート方向

      • calcInterval => 集計間隔(分)

      • lastCalcAt => 最終集計日時

      • createAt => 作成日時

      • updateAt => 更新日時

    • nextPageToken => 次ページトークン



177
178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/gs2/ranking/Client.rb', line 177

def describe_game_mode(request, pageToken = nil, limit = nil)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('rankingTableName'); raise ArgumentError.new(); end
  if not request['rankingTableName']; raise ArgumentError.new(); end
  query = {}
  if pageToken; query['pageToken'] = pageToken; end
  if limit; query['limit'] = limit; end
  return get(
      'Gs2Ranking',
      'DescribeGameMode',
      @@ENDPOINT,
      '/ranking/' + request['rankingTableName'] + '/mode',
      query);
end

#describe_ranking_table(pageToken = nil, limit = nil) ⇒ Array

ランキングテーブルリストを取得

Parameters:

  • pageToken (String) (defaults to: nil) —

    ページトークン

  • limit (Integer) (defaults to: nil) —

    取得件数

Returns:

  • (Array) —

    • items

      Array

      • rankingTableId => ランキングテーブルID

      • ownerId => オーナーID

      • name => ランキングテーブル名

      • description => 説明文

      • createAt => 作成日時

      • updateAt => 更新日時

    • nextPageToken => 次ページトークン



44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/gs2/ranking/Client.rb', line 44

def describe_ranking_table(pageToken = nil, limit = nil)
  query = {}
  if pageToken; query['pageToken'] = pageToken; end
  if limit; query['limit'] = limit; end
  return get(
        'Gs2Ranking', 
        'DescribeRankingTable', 
        @@ENDPOINT, 
        '/ranking',
        query);
end

#get_estimate_rank(request) ⇒ Array

スコアを指定しておおよその順位を取得

指定したスコアを取ったと仮定して何位ぐらいになれるのか、といった指標を計算する際に利用します。
原則1000位単位でおおよその順位を応答します。

上位プレイヤーに対しては1000位単位の解像度では情報が不足している場合があると思いますので、
応答が上位プレイヤーだった場合は、更に #get_ranking で上位のスコアを取得して
さらに詳細な順位に絞り込んで情報提供する。というのもユーザ体験をよく出来ると思います。

Parameters:

  • request (Array) —

    • rankingTableName => ランキングテーブル名

    • gameMode => ゲームモード名

    • score => スコア

Returns:

  • (Array) —

    • min => おおよその順位の最小値

    • max => おおよその順位の最大値



460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
 
# File 'lib/gs2/ranking/Client.rb', line 460

def get_estimate_rank(request)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('rankingTableName'); raise ArgumentError.new(); end
  if not request['rankingTableName']; raise ArgumentError.new(); end
  if not request.has_key?('gameMode'); raise ArgumentError.new(); end
  if not request['gameMode']; raise ArgumentError.new(); end
  query = {}
  if request.has_key?('score'); query['score'] = request['score']; end
  return get(
      'Gs2Ranking',
      'GetEstimateRank',
      @@ENDPOINT,
      '/ranking/' + request['rankingTableName'] + '/mode/' + request['gameMode'] + '/ranking/estimate',
      query);
end

#get_game_mode(request) ⇒ Array

ゲームモードを取得

Parameters:

  • request (Array) —

    • rankingTableName => ランキングテーブル名

    • gameMode => ゲームモード名

Returns:

  • (Array) —

    • item

      • gameModeId => ゲームモードID

      • rankingTableId => ランキングテーブルID

      • gameMode => ゲームモード名

      • ownerId => オーナーID

      • asc => ソート方向

      • calcInterval => 集計間隔(分)

      • lastCalcAt => 最終集計日時

      • createAt => 作成日時

      • updateAt => 更新日時



252
253
254
255
256
257
258
259
260
261
262
263
264
265
 
# File 'lib/gs2/ranking/Client.rb', line 252

def get_game_mode(request)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('rankingTableName'); raise ArgumentError.new(); end
  if not request['rankingTableName']; raise ArgumentError.new(); end
  if not request.has_key?('gameMode'); raise ArgumentError.new(); end
  if not request['gameMode']; raise ArgumentError.new(); end
  query = {}
  return get(
      'Gs2Ranking',
      'GetGameMode',
      @@ENDPOINT,
      '/ranking/' + request['rankingTableName'] + '/mode/' + request['gameMode'],
      query);
end

#get_my_rank(request) ⇒ Array

自分の順位を取得

自分の順位を取得できます、応答される値は集計時点での正確な値となります。

accessToken には Gs2::Auth::Client::login() でログインして取得したアクセストークンを指定してください。

Parameters:

  • request (Array) —

    • rankingTableName => ランキングテーブル名

    • gameMode => ゲームモード名

    • accessToken => アクセストークン

Returns:

  • (Array) —

    • index => インデックス

    • rank => 順位



423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
 
# File 'lib/gs2/ranking/Client.rb', line 423

def get_my_rank(request)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('rankingTableName'); raise ArgumentError.new(); end
  if not request['rankingTableName']; raise ArgumentError.new(); end
  if not request.has_key?('gameMode'); raise ArgumentError.new(); end
  if not request['gameMode']; raise ArgumentError.new(); end
  if not request.has_key?('accessToken'); raise ArgumentError.new(); end
  if not request['accessToken']; raise ArgumentError.new(); end
  header = {
    'X-GS2-ACCESS-TOKEN' => request['accessToken']
  }
  query = {}
  return get(
      'Gs2Ranking',
      'GetMyRank',
      @@ENDPOINT,
      '/ranking/' + request['rankingTableName'] + '/mode/' + request['gameMode'] + '/ranking/rank',
      query,
      header);
end

#get_ranking(request, offset = nil, limit = nil) ⇒ Array

ランキングを取得

ランキングを取得します。
ランキングにはユーザID、スコア、メタデータといった基本情報のほかに、インデックスと順位が付加されています。
インデックスは先頭を1とした位置情報で、順位は同一スコアのユーザを同一順位として計算された値です。
ランキングの性質上、同一スコアでも別順位として扱いたい場合は順位の代わりにインデックスを利用することで実現できます。

ランキングデータはランダムアクセスができますので、#get_my_rank で自分の順位を取得して、
その前後のランキンデータを取得する。というような処理も実現できます。

Parameters:

  • request (Array) —

    • rankingTableName => ランキングテーブル名

    • gameMode => ゲームモード名

  • offset (Integer) (defaults to: nil) —

    取得開始オフセット

  • limit (Integer) (defaults to: nil) —

    取得件数

Returns:

  • (Array) —

    • items

      Array

      • index => インデックス

      • rank => 順位

      • userId => ユーザID

      • score => スコア

      • meta => メタ情報

      • updateAt => 更新日時

    • nextPageToken => 次ページトークン



347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
 
# File 'lib/gs2/ranking/Client.rb', line 347

def get_ranking(request, offset = nil, limit = nil)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('rankingTableName'); raise ArgumentError.new(); end
  if not request['rankingTableName']; raise ArgumentError.new(); end
  if not request.has_key?('gameMode'); raise ArgumentError.new(); end
  if not request['gameMode']; raise ArgumentError.new(); end
  query = {}
  if offset; query['offset'] = offset; end
  if limit; query['limit'] = limit; end
  return get(
      'Gs2Ranking',
      'GetRanking',
      @@ENDPOINT,
      '/ranking/' + request['rankingTableName'] + '/mode/' + request['gameMode'] + '/ranking',
      query);
end

#get_ranking_table(request) ⇒ Array

ランキングテーブルを取得

Parameters:

  • request (Array) —

    • rankingTableName => ランキングテーブル名

Returns:

  • (Array) —

    • item

      • rankingTableId => ランキングテーブルID

      • ownerId => オーナーID

      • name => ランキングテーブル名

      • description => 説明文

      • createAt => 作成日時

      • updateAt => 更新日時



99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/gs2/ranking/Client.rb', line 99

def get_ranking_table(request)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('rankingTableName'); raise ArgumentError.new(); end
  if not request['rankingTableName']; raise ArgumentError.new(); end
  query = {}
  return get(
      'Gs2Ranking',
      'GetRankingTable',
      @@ENDPOINT,
      '/ranking/' + request['rankingTableName'],
      query);
end

#put_score(request) ⇒ Array

スコアを登録

スコアの登録は一時的にバッファリングされ、定期的にランキングデータとして書き込まれます。
そのため、スコア登録直後にランキング集計が開始された場合は、集計結果に含まれない可能性があります。

accessToken には Gs2::Auth::Client::login() でログインして取得したアクセストークンを指定してください。

Parameters:

  • request (Array) —

    • rankingTableName => ランキングテーブル名

    • gameMode => ゲームモード名

    • score => スコア

    • meta => メタ情報

    • accessToken => アクセストークン

Returns:

  • (Array) —

    • item

      • rankingTableId => ランキングテーブルID

      • gameMode => ゲームモード名

      • userId => ユーザID

      • score => スコア

      • meta => メタ情報

      • updateAt => 更新日時



385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
 
# File 'lib/gs2/ranking/Client.rb', line 385

def put_score(request)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('rankingTableName'); raise ArgumentError.new(); end
  if not request['rankingTableName']; raise ArgumentError.new(); end
  if not request.has_key?('gameMode'); raise ArgumentError.new(); end
  if not request['gameMode']; raise ArgumentError.new(); end
  if not request.has_key?('accessToken'); raise ArgumentError.new(); end
  if not request['accessToken']; raise ArgumentError.new(); end
  body = {}
  if request.has_key?('score'); body['score'] = request['score']; end
  if request.has_key?('meta'); body['meta'] = request['meta']; end
  header = {
    'X-GS2-ACCESS-TOKEN' => request['accessToken']
  }
  query = {}
  return post(
      'Gs2Ranking',
      'PutScore',
      @@ENDPOINT,
      '/ranking/' + request['rankingTableName'] + '/mode/' + request['gameMode'] + '/ranking',
      body,
      query,
      header);
end

#update_game_mode(request) ⇒ Array

ゲームモードを更新

Parameters:

  • request (Array) —

    • rankingTableName => ランキングテーブル名

    • gameMode => ゲームモード名

    • calcInterval => 集計間隔(分)

Returns:

  • (Array) —

    • item

      • gameModeId => ゲームモードID

      • rankingTableId => ランキングテーブルID

      • gameMode => ゲームモード名

      • ownerId => オーナーID

      • asc => ソート方向

      • calcInterval => 集計間隔(分)

      • lastCalcAt => 最終集計日時

      • createAt => 作成日時

      • updateAt => 更新日時



284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
 
# File 'lib/gs2/ranking/Client.rb', line 284

def update_game_mode(request)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('rankingTableName'); raise ArgumentError.new(); end
  if not request['rankingTableName']; raise ArgumentError.new(); end
  if not request.has_key?('gameMode'); raise ArgumentError.new(); end
  if not request['gameMode']; raise ArgumentError.new(); end
  body = {}
  if request.has_key?('calcInterval'); body['calcInterval'] = request['calcInterval']; end
  query = {}
  return put(
      'Gs2Ranking',
      'UpdateGameMode',
      @@ENDPOINT,
      '/ranking/' + request['rankingTableName'] + '/mode/' + request['gameMode'],
      body,
      query);
end

#update_ranking_table(request) ⇒ Array

ランキングテーブルを更新

Parameters:

  • request (Array) —

    • rankingTableName => ランキングテーブル名

    • description => 説明文

Returns:

  • (Array) —

    • item

      • rankingTableId => ランキングテーブルID

      • ownerId => オーナーID

      • name => ランキングテーブル名

      • description => 説明文

      • createAt => 作成日時

      • updateAt => 更新日時



125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/gs2/ranking/Client.rb', line 125

def update_ranking_table(request)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('rankingTableName'); raise ArgumentError.new(); end
  if not request['rankingTableName']; raise ArgumentError.new(); end
  body = {}
  if request.has_key?('description'); body['description'] = request['description']; end
  query = {}
  return put(
      'Gs2Ranking',
      'UpdateRankingTable',
      @@ENDPOINT,
      '/ranking/' + request['rankingTableName'],
      body,
      query);
end