共通事項

APIのセオリー

編集

API全般のセオリー

アツマール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つの整数値の足し引きは得意ですが、複数の情報を蓄積することに向いていません。

また、シグナルは常に送信して蓄積することができるのみで、一度送った(受信した)シグナルの内容を変更したり削除したりすることは決してできないことに注意しましょう。

一度受け取ったシグナルを無視するためには、受信したシグナルのcreatedAtと前回受信した最も新しいシグナルのcreatedAtを比較して、それ以降のものだけを処理するといった方法があります(厳密には送受信が完全に同時刻に発生するとcreatedAtの比較時に取りこぼす可能性があります。これを徹底的に対策する場合は、さらに処理し終えたシグナルのIDを覚えておくと良いでしょう)。

こういった処理は面倒なようですが、仮にシグナルAPIにシグナルを削除できるような機能が存在すると「シグナルを処理して削除してからゲームをセーブせずにリセットした場合、消したシグナルは二度と戻ってこない」といった別の困難な問題を引き起こす可能性があります。

シグナルが向いている用途

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

シグナルが向いていない用途

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

最終更新日

  • 2020/02/28