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

@@ENDPOINT = 
'ranking'
@@VARIATION = 
'a'

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クライアントシークレット



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

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

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



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

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

.VARIATION(v = nil) ⇒ Object

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



32
33
34
35
36
37
38
 
# File 'lib/gs2/ranking/Client.rb', line 32

def self.VARIATION(v = nil)
  if v
    @@VARIATION = v
  else
    return @@VARIATION
  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 => 更新日時



234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
 
# File 'lib/gs2/ranking/Client.rb', line 234

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,
      @@VARIATION,
      '/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 => 更新日時



83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/gs2/ranking/Client.rb', line 83

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, 
        @@VARIATION,
        '/ranking',
        body,
        query);
end

#delete_game_mode(request) ⇒ Object

ゲームモードを削除

Parameters:

  • request (Array) —

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

    • gameMode => ゲームモード名



326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
 
# File 'lib/gs2/ranking/Client.rb', line 326

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,
      @@VARIATION,
      '/ranking/' + request['rankingTableName'] + '/mode/' + request['gameMode'],
      query);
end

#delete_ranking_table(request) ⇒ Object

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

Parameters:

  • request (Array) —

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



159
160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'lib/gs2/ranking/Client.rb', line 159

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, 
        @@VARIATION,
        '/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 => 次ページトークン



192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/gs2/ranking/Client.rb', line 192

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,
      @@VARIATION,
      '/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 => 次ページトークン



54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/gs2/ranking/Client.rb', line 54

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, 
        @@VARIATION,
        '/ranking',
        query);
end

#get_estimate_rank(request) ⇒ Array

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

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

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

Parameters:

  • request (Array) —

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

    • gameMode => ゲームモード名

    • score => スコア

Returns:

  • (Array) —

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

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



483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
 
# File 'lib/gs2/ranking/Client.rb', line 483

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'); body['score'] = request['score']; end
  return get(
      'Gs2Ranking',
      'GetEstimateRank',
      @@ENDPOINT,
      @@VARIATION,
      '/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 => 更新日時



269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/gs2/ranking/Client.rb', line 269

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,
      @@VARIATION,
      '/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 => 順位



445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
 
# File 'lib/gs2/ranking/Client.rb', line 445

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,
      @@VARIATION,
      '/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 => 次ページトークン



367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
 
# File 'lib/gs2/ranking/Client.rb', line 367

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,
      @@VARIATION,
      '/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 => 更新日時



111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/gs2/ranking/Client.rb', line 111

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,
      @@VARIATION,
      '/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 => 更新日時



406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
 
# File 'lib/gs2/ranking/Client.rb', line 406

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,
      @@VARIATION,
      '/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 => 更新日時



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

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,
      @@VARIATION,
      '/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 => 更新日時



138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/gs2/ranking/Client.rb', line 138

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,
      @@VARIATION,
      '/ranking/' + request['rankingTableName'],
      body,
      query);
end