Class: Gs2::Inbox::Client

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

Overview

GS2-Inbox クライアント

Author:

  • Game Server Services, Inc.

Constant Summary

@@ENDPOINT = 
'inbox'
@@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/inbox/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/inbox/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/inbox/Client.rb', line 32

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

Instance Method Details

#create_inbox(request) ⇒ Array

受信ボックスを作成

GS2-Inbox を利用するにはまず受信ボックスを作成します。
受信ボックスを作成後、受信ボックスにメッセージを送信することでメッセージを届けることができます。
1つの受信ボックスで、複数のユーザのメッセージを扱うことができますので、ユーザ数分の受信ボックスを作成する必要はありません。

Parameters:

  • request (Array) —

    • name => 受信ボックス名

    • serviceClass => サービスクラス

    • autoDelete => 自動削除設定

    • cooperationUrl => 連携用URL

Returns:

  • (Array) —

    • item

    • inboxId => 受信ボックスID

    • ownerId => オーナーID

    • name => 受信ボックス名

    • serviceClass => サービスクラス

    • autoDelete => 自動削除設定

    • cooperationUrl => 連携用URL

    • createAt => 作成日時



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/gs2/inbox/Client.rb', line 88

def create_inbox(request)
  if not request; raise ArgumentError.new(); end
  body = {}
  if request.has_key?('name'); body['name'] = request['name']; end
  if request.has_key?('serviceClass'); body['serviceClass'] = request['serviceClass']; end
  if request.has_key?('autoDelete'); body['autoDelete'] = request['autoDelete']; end
  if request.has_key?('cooperationUrl'); body['cooperationUrl'] = request['cooperationUrl']; end
  query = {}
  return post(
        'Gs2Inbox', 
        'CreateInbox', 
        @@ENDPOINT, 
        @@VARIATION,
        '/inbox',
        body,
        query);
end

#delete_inbox(request) ⇒ Object

受信ボックスを削除

Parameters:

  • request (Array) —

    • inboxName => 受信ボックス名



204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/gs2/inbox/Client.rb', line 204

def delete_inbox(request)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('inboxName'); raise ArgumentError.new(); end
  if not request['inboxName']; raise ArgumentError.new(); end
  query = {}
  return delete(
        'Gs2Inbox', 
        'DeleteInbox', 
        @@ENDPOINT, 
        @@VARIATION,
        '/inbox/' + request['inboxName'],
        query);
end

#delete_message(request) ⇒ Object

メッセージを削除

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

Parameters:

  • request (Array) —

    • inboxName => 受信ボックス名

    • messageId => メッセージID

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



411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
 
# File 'lib/gs2/inbox/Client.rb', line 411

def delete_message(request)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('inboxName'); raise ArgumentError.new(); end
  if not request['inboxName']; raise ArgumentError.new(); end
  if not request.has_key?('messageId'); raise ArgumentError.new(); end
  if not request['messageId']; raise ArgumentError.new(); end
  if not request.has_key?('accessToken'); raise ArgumentError.new(); end
  if not request['accessToken']; raise ArgumentError.new(); end
  query = {}
  header = {
    'X-GS2-ACCESS-TOKEN' => request['accessToken']
  }
  return delete(
        'Gs2Inbox', 
        'DeleteMessage', 
        @@ENDPOINT, 
        @@VARIATION,
        '/inbox/' + request['inboxName'] + '/message/' + request['messageId'],
        query,
        header);
end

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

受信ボックスリストを取得

Parameters:

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

    ページトークン

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

    取得件数

Returns:

  • (Array) —

    • items

      Array

      • inboxId => 受信ボックスID

      • ownerId => オーナーID

      • name => 受信ボックス名

      • serviceClass => サービスクラス

      • autoDelete => 自動削除設定

      • cooperationUrl => 連携用URL

      • createAt => 作成日時

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



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

def describe_inbox(pageToken = nil, limit = nil)
  query = {}
  if pageToken; query['pageToken'] = pageToken; end
  if limit; query['limit'] = limit; end
  return get(
        'Gs2Inbox', 
        'DescribeInbox', 
        @@ENDPOINT, 
        @@VARIATION,
        '/inbox',
        query);
end

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

メッセージリストを取得

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

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

Parameters:

  • request (Array) —

    • inboxName => 受信ボックス名

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

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

    ページトークン

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

    取得件数

Returns:

  • (Array) —

    • items

      Array

      • messageId => メッセージID

      • inboxId => 受信ボックスID

      • userId => 受信ユーザID

      • message => メッセージ本文

      • cooperation => 開封時に連携用URLを呼び出すか

      • date => 受信日時

      • read => 既読状態



297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
 
# File 'lib/gs2/inbox/Client.rb', line 297

def describe_message(request, pageToken = nil, limit = nil)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('inboxName'); raise ArgumentError.new(); end
  if not request['inboxName']; raise ArgumentError.new(); end
  if not request.has_key?('accessToken'); raise ArgumentError.new(); end
  if not request['accessToken']; raise ArgumentError.new(); end
  query = {}
  if pageToken; query['pageToken'] = pageToken; end
  if limit; query['limit'] = limit; end
  header = {
    'X-GS2-ACCESS-TOKEN' => request['accessToken']
  }
  return get(
        'Gs2Inbox', 
        'DescribeMessage', 
        @@ENDPOINT, 
        @@VARIATION,
        '/inbox/' + request['inboxName'] + '/message',
        query,
        header);
end

#describe_service_class ⇒ Array

サービスクラスリストを取得

Returns:

  • (Array) —

    サービスクラス



109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/gs2/inbox/Client.rb', line 109

def describe_service_class()
  query = {}
  result = get(
      'Gs2Inbox',
      'DescribeServiceClass',
      @@ENDPOINT,
      @@VARIATION,
      '/inbox/serviceClass',
      query);
  return result['items'];
end

#get_inbox(request) ⇒ Array

受信ボックスを取得

Parameters:

  • request (Array) —

    • inboxName => 受信ボックス名

Returns:

  • (Array) —

    • item

      • inboxId => 受信ボックスID

      • ownerId => オーナーID

      • name => 受信ボックス名

      • serviceClass => サービスクラス

      • autoDelete => 自動削除設定

      • cooperationUrl => 連携用URL

      • createAt => 作成日時



134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/gs2/inbox/Client.rb', line 134

def get_inbox(request)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('inboxName'); raise ArgumentError.new(); end
  query = {}
  return get(
      'Gs2Inbox',
      'GetInbox',
      @@ENDPOINT,
      @@VARIATION,
      '/inbox/' + request['inboxName'],
      query);
end

#get_inbox_status(request) ⇒ Array

受信ボックスのステータスを取得

Parameters:

  • request (Array) —

    • inboxName => 受信ボックス名

Returns:

  • (Array) —

    • status => 状態



153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/gs2/inbox/Client.rb', line 153

def get_inbox_status(request)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('inboxName'); raise ArgumentError.new(); end
  if not request['inboxName']; raise ArgumentError.new(); end
  query = {}
  return get(
      'Gs2Inbox',
      'GetInboxStatus',
      @@ENDPOINT,
      @@VARIATION,
      '/inbox/' + request['inboxName'] + '/status',
      query);
end

#get_message(request) ⇒ Array

メッセージを取得

Parameters:

  • request (Array) —

    • inboxName => 受信ボックス名

    • messageId => メッセージID

Returns:

  • (Array) —

    • item

      • messageId => メッセージID

      • inboxId => 受信ボックスID

      • userId => 受信ユーザID

      • message => メッセージ本文

      • cooperation => 開封時に連携用URLを呼び出すか

      • date => 受信日時

      • read => 既読状態



333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
 
# File 'lib/gs2/inbox/Client.rb', line 333

def get_message(request)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('inboxName'); raise ArgumentError.new(); end
  if not request['inboxName']; raise ArgumentError.new(); end
  if not request.has_key?('messageId'); raise ArgumentError.new(); end
  if not request['messageId']; raise ArgumentError.new(); end
  query = {}
  return get(
      'Gs2Inbox',
      'GetMessage',
      @@ENDPOINT,
      @@VARIATION,
      '/inbox/' + request['inboxName'] + '/message/' + request['messageId'],
      query);
end

#read_message(request) ⇒ Array

メッセージを開封

受信ボックスの設定で開封時自動削除設定が有効な場合は、メッセージは削除されます。

連携用URLを呼び出す設定になっている場合、連携用URLにメッセージIDを付与したコールバックが実行されます。
このコールバックをうけて、持ち物を増やしたりすることでメッセージにアイテムを添付することができます。

レスポンスには連携用URLを呼び出した際の応答内容も含まれますので、開封時にさらにメッセージを表示させるようなこともできます。
例えば、連携用URLを呼び出した際に「アイテムを手に入れた」というレスポンスを返すことで、このAPIのレスポンスにその文字列も含んだ形で応答されますので、
開封時にさらにその応答メッセージを使って画面にメッセージとして「アイテムを手に入れた」という表示をすることができます。

開封時のコールバックは通信障害などの理由により、コールバック先のサーバは正しく処理を行えたけれど、
GS2側のインフラにレスポンスが届かず、結果的に処理が失敗する可能性を考慮する必要があります。
この場合、複数回の開封コールバックが呼び出される可能性がありますので、コールバック処理は冪等性を持った形で実装するようにしてください。

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

Parameters:

  • request (Array) —

    • inboxName => 受信ボックス名

    • messageId => メッセージID

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

Returns:

  • (Array) —

    • item

      • messageId => メッセージID

      • inboxId => 受信ボックスID

      • userId => 受信ユーザID

      • message => メッセージ本文

      • cooperation => 開封時に連携用URLを呼び出すか

      • date => 受信日時

      • read => 既読状態



379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
 
# File 'lib/gs2/inbox/Client.rb', line 379

def read_message(request)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('inboxName'); raise ArgumentError.new(); end
  if not request['inboxName']; raise ArgumentError.new(); end
  if not request.has_key?('messageId'); raise ArgumentError.new(); end
  if not request['messageId']; raise ArgumentError.new(); end
  if not request.has_key?('accessToken'); raise ArgumentError.new(); end
  if not request['accessToken']; raise ArgumentError.new(); end
  body = {}
  query = {}
  header = {
    'X-GS2-ACCESS-TOKEN' => request['accessToken']
  }
  return post(
      'Gs2Inbox',
      'ReadMessage',
      @@ENDPOINT,
      @@VARIATION,
      '/inbox/' + request['inboxName'] + '/message/' + request['messageId'],
      body,
      query,
      header);
end

#send_message(request) ⇒ Array

メッセージを送信

メッセージを受信ボックスに送信します。
メッセージには本文との他に開封時通知を有効にするかのフラグ、既読状態のフラグといった情報が付加されています。

開封時通知を有効にすると、受信ボックスに設定された連携用URLにメッセージIDがPOSTリクエストで通知されます。
メッセージ送信時にも送信したメッセージIDが取得できますので、
例えば、メッセージに課金用アイテムを添付したい場合は以下の様なメッセージを送信します。

  • 送信先: user-0001

  • メッセージ本文: サーバ障害のお詫びです

  • 開封時通知: 有効

このAPIの戻り値に含まれるメッセージIDとユーザID、アイテムの内容(課金用アイテム)をひも付けて保存します。

その後、ユーザがこのメッセージを開封すると、連携用URLにこのメッセージのメッセージIDが通知されます。
それを受けて、ユーザIDのアカウントにアイテムの内容(課金用アイテム)を付与します。
これで、メッセージにアイテムを添付することができます。

また、連携用URLを呼び出した際にエラー応答することで、メッセージの開封を失敗させることができます。
これによって、持ち物がいっぱいの場合などにアイテムの付与に失敗しても再度開封処理を実行させることができます。

開封時のコールバックは通信障害などの理由により、コールバック先のサーバは正しく処理を行えたけれど、
GS2側のインフラにレスポンスが届かず、結果的に処理が失敗する可能性を考慮する必要があります。
この場合、複数回の開封コールバックが呼び出される可能性がありますので、コールバック処理は冪等性を持った形で実装するようにしてください。

Parameters:

  • request (Array) —

    • inboxName => 受信ボックス名

    • userId => 宛先ユーザID

    • message => メッセージ本文

    • cooperation => 開封時に連携用URLを呼び出すか

Returns:

  • (Array) —

    • item

      • messageId => メッセージID

      • inboxId => 受信ボックスID

      • userId => 受信ユーザID

      • message => メッセージ本文

      • cooperation => 開封時に連携用URLを呼び出すか

      • date => 受信日時

      • read => 既読状態



258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/gs2/inbox/Client.rb', line 258

def send_message(request)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('inboxName'); raise ArgumentError.new(); end
  if not request['inboxName']; raise ArgumentError.new(); end
  body = {}
  if request.has_key?('userId'); body['userId'] = request['userId']; end
  if request.has_key?('message'); body['message'] = request['message']; end
  if request.has_key?('cooperation'); body['cooperation'] = request['cooperation']; end
  query = {}
  return post(
      'Gs2Inbox',
      'SendMessage',
      @@ENDPOINT,
      @@VARIATION,
      '/inbox/' + request['inboxName'] + '/message',
      body,
      query);
end

#update_inbox(request) ⇒ Array

受信ボックスを更新

Parameters:

  • request (Array) —

    • inboxName => 受信ボックス名

    • serviceClass => サービスクラス

    • cooperationUrl => 連携用URL

Returns:

  • (Array) —

    • item

      • inboxId => 受信ボックスID

      • ownerId => オーナーID

      • name => 受信ボックス名

      • serviceClass => サービスクラス

      • autoDelete => 自動削除設定

      • cooperationUrl => 連携用URL

      • createAt => 作成日時



182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/gs2/inbox/Client.rb', line 182

def update_inbox(request)
  if not request; raise ArgumentError.new(); end
  if not request.has_key?('inboxName'); raise ArgumentError.new(); end
  if not request['inboxName']; raise ArgumentError.new(); end
  body = {}
  if request.has_key?('serviceClass'); body['serviceClass'] = request['serviceClass']; end
  if request.has_key?('cooperationUrl'); body['cooperationUrl'] = request['cooperationUrl']; end
  query = {}
  return put(
      'Gs2Inbox',
      'UpdateInbox',
      @@ENDPOINT,
      @@VARIATION,
      '/inbox/' + request['inboxName'],
      body,
      query);
end