基本概念
プロジェクト、キー、プレイヤーセッション、そして各 SDK が結果とエラーをどのように返すかを説明します。
コードのコメントと API 名は、SDK と一致させるため英語のままにしています。
プロジェクトとキー#
ゲームごとに 1 つのプロジェクトを使用します。キーはプロジェクトを識別するもので、プレイヤーを識別するものではありません。
| 認証情報 | 使用する場所 |
|---|---|
| Base URL | このサーバーのアドレスです。API は /v1 以下にあります。 |
| Project ID | すべてのリクエストに X-Project-ID として付けます。公開情報です。 |
クライアントキー pk_live_… | ゲームのビルドや Web ページで X-Client-Key として使用します。公開情報で、ログイン中のプレイヤーの範囲でしか操作できません。 |
シークレットキー sk_live_… | 自社のサーバーでのみ X-Secret-Key として使用します。表示は一度だけで、ハッシュ化して保存されます。サーバー専用のエンドポイントを利用できるようになります。 |
シークレットキー(
sk_live_…)は、ゲームのビルドや Web ページに絶対に含めないでください。プレイヤーに配布したものは、すべて読み取られる可能性があります。プレイヤーとセッション#
プレイヤー向けの呼び出しにはアクセストークンが必要です。ログインすると、アクセストークン(有効期間 1 時間)とリフレッシュトークン(有効期間 30 日)が返されます。
- SDK はセッションをデバイスに保存し、有効期限が切れる前に更新します。そのため、プレイヤーは起動をまたいでもログイン状態を維持できます。
- リフレッシュトークンは使用するたびにローテーションされます。古いトークンを再利用すると、そのセッションはすべての場所でログアウトされます(盗用検知)。
- すべてのプレイヤーはゲストとして始まり、あとからメールアドレスや Google アカウントを連携できます。ゲストの進行状況もそのまま引き継がれます。詳しくはプレイヤーを参照してください。
例外ではなく結果を返す#
SDK の呼び出しは、ネットワークエラーやサーバーエラーで例外をスローしません。ok、値、エラー(安定したコード、メッセージ、リクエスト ID を含む)を持つ結果を返します。
var top = await Majacloud.Leaderboards.GetTopAsync("coins", 10);
if (top.Ok)
{
foreach (var entry in top.Value.Entries)
Debug.Log($"#{entry.Rank} {entry.PlayerName} {entry.Score}");
}
else if (top.Error.IsRetryable)
{
// Network, timeout, 5xx or rate limit: try again later
Debug.Log("Retry in " + top.Error.RetryAfterSeconds + " s");
}
else
{
Debug.LogWarning(top.Error.Code + ": " + top.Error.Message + " (" + top.Error.RequestId + ")");
}var top := await Majacloud.leaderboards.get_top("coins", 10)
if top.ok:
for entry in top.value.entries:
print("#%d %s %d" % [entry.rank, entry.player_name, entry.score])
elif top.is_retryable():
# Network, timeout, 5xx or rate limit: try again later
print("Retry in ", top.retry_after, " s")
else:
push_warning("%s: %s (%s)" % [top.error, top.message, top.request_id])const top = await mc.leaderboards.getTop('coins', { limit: 10 });
if (top.ok) {
for (const entry of top.value.entries) {
console.log(`#${entry.rank} ${entry.player_name} ${entry.score}`);
}
} else if (top.error.retryable) {
// Network, timeout, 5xx or rate limit: try again later
console.log('Retry in', top.error.retryAfter, 's');
} else {
console.warn(`${top.error.code}: ${top.error.message} (${top.error.requestId})`);
}// Success
{ "ok": true, "entries": [ … ], "total": 42 }
// Error (HTTP 4xx/5xx)
{
"ok": false,
"error": {
"code": "rate_limited",
"message": "Project rate limit reached. Try again in a minute.",
"request_id": "6f1c2a9e-…",
"details": { "limit": 120, "window": "minute" }
}
}リトライとレート制限#
SDK は、ネットワークエラーや 5xx レスポンスの際に安全なリクエストを指数バックオフでリトライし、429 レスポンスには Retry-After に従って待機します。
- 各プロジェクトは1 分あたり 120 リクエストまで送信できます。これを超えると、API は
rate_limitedを返します。 - 各アカウントには、プランに応じた1 日あたりのリクエストクォータがあります(制限を参照)。これを超えると、00:00 UTC まで API は
quota_exceededを返します。 - レスポンスには
X-RateLimit-LimitとX-RateLimit-Remainingが含まれ、クォータに近づくとX-RateLimit-Daily-Remainingも含まれます。
リクエスト ID とログ#
すべてのレスポンスには X-Request-ID ヘッダーがあり、すべてのエラーには request_id が含まれます。プロジェクトのログページでこの ID を検索すると、エンドポイント、ステータス、レイテンシ、プレイヤーを確認できます。