XBOX services 呼び出しのベストプラクティス - XBOX Game Development Documentation

XBOX services を呼び出す主な方法は 2 つあります。XBOX Services API (XSAPI) を使用する方法と、REST エンドポイントを直接呼び出す方法です。コードから XBOX services をどのように呼び出すかにかかわらず、適切な呼び出しパターンとリトライロジックを持つことが重要です。適切なリトライロジックを記述する方法を理解するには、REST エンドポイントの 2 つの種類 — 冪等性 と 非冪等性 — について知る必要があります。これらについて以下で説明します。

非冪等性エンドポイント

繰り返し呼び出すと副作用がある HTTP メソッドは 非冪等性 とみなされます。つまり、クライアントがエンドポイントを呼び出してネットワークタイムアウトが発生した場合、リソースが更新されている可能性があるにもかかわらず、ネットワークが呼び出し元に成功を通知できなかった可能性があるため、メソッドを安全に再試行することはできません。エラーが発生した場合、クライアントは再試行する代わりに、まず呼び出しが成功したかどうかを確認するためにクエリを実行する必要があります。呼び出しが成功していなかった場合にのみ、再試行する必要があります。 XBOX Services API では、一部の API は内部的に非冪等性エンドポイントを呼び出すものとしてマークされています。つまり、これらのエンドポイントを呼び出した際に失敗が発生しても、API は自動的にはエンドポイントを再試行しません。非冪等性 API の完全なリストは次のとおりです:

冪等性メソッド

一方、冪等性 の HTTP メソッドは副作用を残しません。これはつまり、安全に再試行できるということです。 XBOX Services API では、すべての冪等性メソッドは特定の条件下で自動的に再試行されます。冪等性 API の完全なリストは、上記の非冪等性としてリストされていないすべての API です。

リトライロジックのベストプラクティス

冪等性の呼び出しでは、次の条件で自動的に再試行する必要があります:

すべてのネットワークエラー
401: Unauthorized
408: RequestTimeout
429: Too Many Requests
500: InternalError
502: BadGateway
503: ServiceUnavailable
504: GatewayTimeout

UWP では、401: Unauthorized は特別に扱われます。この値は XBOX services 認証トークンの有効期限が切れたことを示すため、XBOX Services API は OS を呼び出してトークンを更新し、単一のリトライとして実行します。リトライを実行する際は、“Retry-After” ヘッダーの時間に達するまでサービスを呼び出さないことがベストプラクティスです。 XSAPI はこのベストプラクティスを実装しています。失敗の HTTP ステータスコードと “Retry-After” ヘッダーがいずれかの API に対して返された場合、Retry-After の時間より前に同じ API へ追加で呼び出しを行うと、サービスにアクセスすることなく、即座に元のエラーが返されます。呼び出しを再試行する際は、サービスへの負荷を分散させるために、ランダムなジッターを伴う指数バックオフを行うことがベストプラクティスです。 XSAPI では既定の遅延として 2 秒から開始し、これは XblContextSettingsSetHttpRetryDelay を使用して制御します。つまり、既定では各リトライは 2、4、8 秒以上の指数バックオフを行います。応答時間に基づき現在のバックオフ値と次のバックオフ値の間で遅延をジッターさせ、リトライを試みるデバイス群全体で負荷をさらに分散させます。タイトルは、呼び出しのリトライにどれだけ時間をかけるかを制御すべきです。 XSAPI を使用する場合、開発者は XblContextSettingsSetHttpTimeoutWindow 関数を使用してこれを直接制御できます。既定では、これは 20 秒に設定されています。これを 0 秒に設定すると、実質的にリトライロジックが無効になります。

内部 HTTP タイムアウトの動的な調整

XSAPI は、XblContextSettingsGetHttpTimeoutWindow の残り時間に基づいて、内部 HTTP タイムアウトを動的に調整します。内部 HTTP タイムアウトは、OS が HTTP ネットワーク操作を中止するまでにその操作に費やす時間を制御します。呼び出しは、XblContextSettingsGetHttpTimeoutWindow に少なくとも 5 秒残っていない限り、再試行されません。これは、呼び出しを完了するのに十分な時間を与えるためです。このルールは最初の呼び出しには適用されないため、XblContextSettingsSetHttpTimeoutWindow を 0 に設定することは許容され、単一の呼び出しになります。このロジックにより、XblContextSettingsGetHttpTimeoutWindow は API 呼び出しがいつ返るかについてより決定論的になります。 “Retry-After” ヘッダーが返された場合、“Retry-After” の時間に達するまでリトライは実行されません。 “Retry-After” の時間が XblContextSettingsGetHttpTimeoutWindow より後の場合、呼び出しは XblContextSettingsGetHttpTimeoutWindow の終了時に返されます。

エラー処理

タイトル開発者は、すべての サービス呼び出しに対して常に適切なエラー処理を使用し、失敗の応答を適切に処理する必要があります。 XBOX services へのリクエストが失敗コードを返す原因となる、現実世界の状況は数多く存在します。例えば:

ネットワークが利用できない。例えば、デバイスが 4G を失った、Wi-Fi を失った、またはネットワークがダウンした。
サービスへの負荷が高すぎる (503)。
サービス上で障害が発生した (500)。
サービスへ送信されたリクエストが多すぎる (429)。
書き込み操作の競合 (412)。例えば、マルチプレイヤーセッションの別のプレイヤーが先に変更を送信した。
ユーザーが BAN されている、または権限を持っていない。
ユーザーがサインアウトしている。

適切なエラーハンドラーは、これらの状況でゲームが正しく機能することを保証するために極めて重要です。エラー処理のベストプラクティスの詳細については、Error handling を参照してください。これをカバーする動画については、Xfest 2015 Videos の XSAPI: C++, No Exceptions! というトークをご覧ください。

最適な呼び出しパターン

バッチリクエストを使用する

一部のエンドポイントは、一連のリクエストのバッチ処理または集約を単一の呼び出しへまとめることをサポートしています。例えば、XBOX service のプロファイルサービスでは、単一ユーザーのプロファイルまたは複数ユーザーのプロファイルを要求できます。したがって、複数ユーザーのプロファイルが必要な場合、ユーザープロファイルごとに一つずつエンドポイントや API を呼び出すのは非常に非効率です。各呼び出しには多くの認証オーバーヘッドが伴います。そのため、代わりに情報を取得したいすべてのユーザーを一度に API に渡し、エンドポイントがすべてのユーザープロファイルを同時に処理して単一のレスポンスを返せるようにします。

ポーリングの代わりに Real Time Activity (RTA) サービスを使用する

定期的なポーリングの代わりに Real-Time Activity (RTA) サービスを使用することがベストプラクティスです。 Real-Time Activity サービスは、対象のリソースがサービス上で変更されたときにクライアントに通知を送信する Web ソケットを公開します。 RTA サービスは、プレゼンス変更、統計変更、マルチプレイヤーセッションドキュメントの変更、およびソーシャル関係の変更に関する通知を提供します。クライアントがどの情報に関心を持っているかを知るために、クライアントはまず Web ソケット経由でその項目を購読する必要があります。これにより、項目が変更されたときに正確に通知されるため、変更を検出するためのサービスへのポーリングを回避できます。 XSAPI は、クライアントが使用できる一連の購読 API として RTA サービスを公開しています。これらの API にはそれぞれ、項目が変更されたときに呼び出されるコールバック関数を受け取る対応する *ChangedHandler API があります。

XblPresenceSubscribeToDevicePresenceChange
XblPresenceSubscribeToTitlePresenceChange
XblUserStatisticsSubscribeToStatisticChange
XblSocialSubscribeToSocialRelationshipChange

XSAPI クライアントサイドマネージャーを使用する

XSAPI には、特定のシナリオで面倒な作業をすべて行うキャッシュおよびステートマシンとして機能する一連のマネージャーがあります。 Social Manager は、フレンドリストとプロファイルに関する面倒な作業をすべて行います。 Social Manager は、RTA サービスを使用してフレンドリスト、プロファイル、およびプレゼンスデータを最新の状態に保ちます。 Social Manager は、ゲームエンジンに非常に適した同期 API を公開します。 Social Manager はサービスからの最新情報のインメモリキャッシュを保持しているため、ゲームは Social Manager API を頻繁に呼び出せます。 Social Manager を参照してください。

Multiplayer Manager

マルチプレイヤーセッション管理には、Multiplayer Manager が従来のマルチプレイヤーゲーム向けのドロップインソリューションとして機能します。 Multiplayer Manager API には、プレイヤーロースターとセッション管理が含まれ、ゲーム招待、途中参加、マッチメイキングを処理し、既存のネットワーキングソリューションに組み込むことができます。従来のマルチプレイヤーフローの実装に関する面倒な作業をすべて行います。 Multiplayer Manager を参照してください。

スロットリング (きめ細かなレート制限)

XBOX services には、単一のデバイスからサービスに極端な負荷をかけないようにするためのスロットリングが用意されています。タイトルがスロットリングされたときを知ることは重要です。タイトルがスロットリングされたかどうかを判断するには、次のいずれかの方法を使用します:

HTTP ステータスコード 429 の監視
デバッグアサートの使用
XBOX services Trace Analyzer ツールの使用

これらの方法について以下で説明します。

HTTP ステータスコード 429 の監視

Fiddler を使用して、HTTP ステータスコード 429 が返されるかを監視できます。 JSON レスポンスには、エンドポイントがどのようにスロットリングされたかについての詳細が含まれます。例:

{
  "version":1,
  "currentRequests":13,
  "maxRequests":10,
  "periodInSeconds":120,
  "limitType":"Rate"
}

XSAPI を使用している場合、API は HTTP_E_STATUS_429_TOO_MANY_REQUESTS エラーを返し、API がどのようにスロットリングされたかの詳細を示すエラーメッセージを設定します。

デバッグアサートの使用

XSAPI を使用している場合、開発者サンドボックス内でタイトルのデバッグビルドを使用中に呼び出しがスロットリングされると、スロットリングが発生したことを開発者にすぐに知らせるためにアサートが行われます。これは、誤って記述されたコードが原因で 429 スロットリングエラーを意図せず見逃すことを避けるためです。問題のあるコードを修正せずに作業を続けるためにこれらのアサートを無効にしたい場合は、XblDisableAssertsForXboxLiveThrottlingInDevSandboxes API を使用できます:

XblDisableAssertsForXboxLiveThrottlingInDevSandboxes(
    XblConfigSetting::ThisCodeNeedsToBeChanged
);

この API はタイトルがスロットリングされることを防ぐわけではないことに注意してください。タイトルは引き続きスロットリングされます。これは単に、デバッグビルドで開発サンドボックスにいる間のアサートを無効にするだけです。

XBOX services Trace Analyzer ツールの使用

タイトルがスロットリングされたかどうかを判断するもう一つの選択肢は、XBOX サービス呼び出しのトレースを記録し、XBOX services Trace Analyzer ツールを使用してそのトレースを分析することです。トレースを記録するには、Fiddler を使用して .SAZ ファイルを記録するか、XSAPI の組み込みトレースログを使用します。 XSAPI でトレースをオンにする方法の詳細については、XBOX の記事 XBOX services Trace Analyzer (XblTraceAnalyzer.exe) を参照してください。トレースを取得すると、XBOX services Trace Analyzer ツールはスロットリングされた呼び出しを検出したときに警告を発します。

XBOX services は稼働していますか？

XBOX service は、プロファイル、フレンドとプレゼンス、統計、リーダーボード、実績、マルチプレイヤー、マッチメイキングなどの XBOX 機能を公開するマイクロサービスの集合体です。 XBOX services が稼働しているかどうかを定義する単一のサーバーやエンドポイントは存在しません。単一のサーバーがダウンしても、XBOX service の他のマイクロサービスはほぼ独立しており、動作しているはずです。単一のサービスが一時的な停止を経験している場合、そのサービス呼び出しがゲームにとってミッションクリティカルかどうかを知ることが重要です。断続的なネットワークやサービスの問題がある間も、合理的なエクスペリエンスを提供するよう努めてください。例えば、プレゼンスサービスが失敗を返している場合、その呼び出しはおそらくゲームにとってミッションクリティカルではありません。そのため、XBOX network (XBOX Live としても知られる) がダウンしていると報告する代わりに、単純に最後に確認できたプレゼンスをユーザーに報告してください。 XBOX services は “結果整合性” の一貫性モデルに従います。つまり、新しい更新が行われなければ、最終的にはそのリソースに対するすべてのリクエストが最後に更新された値を報告します。これは、データが伝播する間、情報が古い状態になる短い期間があることを意味します。

​非冪等性エンドポイント

​冪等性メソッド

​リトライロジックのベストプラクティス

​内部 HTTP タイムアウトの動的な調整

​エラー処理

​最適な呼び出しパターン

​バッチリクエストを使用する

​ポーリングの代わりに Real Time Activity (RTA) サービスを使用する

​XSAPI クライアントサイドマネージャーを使用する

​Social Manager

​Multiplayer Manager

​スロットリング (きめ細かなレート制限)

​HTTP ステータスコード 429 の監視

​デバッグアサートの使用

​XBOX services Trace Analyzer ツールの使用

​XBOX services は稼働していますか？