APIのセオリー

編集

API全般のセオリー

RPGアツマールAPIは、基本的に非同期的な、つまり数秒に1回程度までのゆるやかな通信を想定して設計されています。

これはゲーム作者の皆さんに、サーバーの設定・準備や負荷対策などといった複雑な要素を気にすることなく手軽にご利用いただくAPIとして、リアルタイム通信をサポートするのは難易度が高いためです(リアルタイムの同期通信はサーバー負荷が高いだけでなく、ゲームを作る側にとっても途中切断時の処理などの難易度が高く、またせっかく完成してもマッチングする相手がいないとゲームが成立しないといった多くの困難が存在します)。

そのためあまりに高頻度な通信に対しては、APIの呼び出し回数制限という形で制限を設けさせていただいております。

ユーザー情報APIのセオリー

ユーザー情報APIには、「ユーザーIDを指定してユーザー情報取得」、「ユーザー本人のユーザー情報取得」、「このゲームを最近プレイしたユーザーたちを取得」の3通りのAPIがあります。
特に最近のユーザーの取得は、共有セーブAPIやユーザーシグナルAPIで必要になる「他のユーザーのユーザーID」を複数取得する方法として、重宝します。
また「プレイヤー本人のユーザー情報取得」で本人のユーザーIDを取得することは、ユーザー本人と他のユーザーを識別する上では必須のテクニックです。

グローバルサーバー変数APIのセオリー

グローバルサーバー変数APIの大きな特長として、複数のユーザーが同時に安全に値を変更(足し引き)できる現状唯一のAPIであることが挙げられます。
つまり、複数のユーザーが同時にトリガーを発動させて値を足し引きした場合、そのトリガー呼び出しが成功していれば必ず結果の値はその足し引きをすべて適応した値になります(トリガーから代入を許してしまうと、簡単には結果を保証できません。それ故に足し引きのみに制限しているのです)。

使いどき

  • 全ユーザーで共通の整数を保持&足し引きしたいとき
  • 整数の足し引きを確実に適応したいとき
  • 非ログインユーザーも参加できるゲームを作りたいとき

向いてないとき

  • 整数以外のデータを扱いたいとき
  • ユーザー一人ひとりに属するデータを持ちたいとき
  • 大量のデータを扱いたいとき

共有セーブAPIのセオリー

共有セーブAPIの特長は、他人と通信するAPIの中では現状最も大量のデータをやり取りできることです。
他人から読み取り可能なセーブデータを作るという特性上、ゲーム作者側からすれば保存できる・読み取れる容量の上限が存在しません(もちろん、通常のセーブデータと同様に各ユーザーのセーブ容量(ブロック)を消費しますので、ユーザーの便宜のためになるべく容量が小さくなるよう努める必要はあります)。
また、セーブの内容には任意の文字列を指定できるため、JSONをはじめとした様々な構造のデータを読み書きできます。容量の大きさ・構造の自由度ともに高く、極めればカードデッキや自作コースなどを丸々やり取りすることも可能でしょう。
ユーザー各々が持つデータを他人と通信させたい場合は、まずは共有セーブAPIの利用を検討するのがよいでしょう。

使いどき

  • ユーザー一人ひとりが持つデータを他のユーザーから参照したいとき
  • 大量の・複雑なデータをやり取りしたいとき

向いてないとき

  • 全ユーザーで共通の値を持ちたいとき
  • あるユーザーから他のユーザーへ情報を送りたいとき

シグナルAPIのセオリー

シグナルAPIの特長は、あるユーザーから他の特定のユーザー(ユーザーシグナルの場合)または全ユーザー(グローバルシグナルの場合)へ何らかの情報や合図を簡単に送り、それを蓄積できることです。
共有セーブAPIでは他人の共有セーブを読み取ることはできますが、書き込むことは許されていませんから、他人への働きかけを表現する方法がありません。また、グローバルサーバー変数は1つの整数値の足し引きは得意ですが、複数の情報を蓄積することに向いていません。

ただし、いくつかシグナルAPI特有の制約もあります。
まず、同じく文字列をやり取りする共有セーブとは違い、シグナルAPIには一回あたり100byteまでの容量制限があることに注意しましょう(100byteは半角英数字のみなら100文字まで、日本語などの場合は約30文字までのサイズです)。
あるユーザーから他のユーザーへ大量のデータを送りたい場合は、ユーザーシグナルで「送り主の共有セーブを見よ」といった内容だけを送り、受け手に改めて共有セーブAPIで読み出してもらうなどの工夫が必要です。

また、シグナルは常に送信して蓄積することができるのみで、一度送った(受信した)シグナルの内容を変更したり削除したりすることは決してできないことに注意しましょう。
一度受け取ったシグナルを無視するためには、受信したシグナルのcreatedAtと前回受信した最も新しいシグナルのcreatedAtを比較して、それ以降のものだけを処理するといった方法があります(厳密には送受信が完全に同時刻に発生するとcreatedAtの比較時に取りこぼす可能性があります。これを徹底的に対策する場合は、さらに処理し終えたシグナルのIDを覚えておくと良いでしょう)。
こういった処理は面倒なようですが、仮にシグナルAPIにシグナルを削除できるような機能が存在すると「シグナルを処理して削除してからゲームをセーブせずにリセットした場合、消したシグナルは二度と戻ってこない」といった別の困難な問題を引き起こす可能性があります。

使いどき

  • あるユーザーから他のユーザーor全ユーザーへ小さい情報や合図を送りたいとき
  • 送信した内容を蓄積してほしいとき

向いてないとき

  • 大量のデータを扱いたいとき
  • 全ユーザーで共通の値を持ちたいとき