10. デバッグ補助

10.1. はじめに

アプリケーション開発で NEX を利用する際のデバッグ補助機能として、以下を提供しています。

  • ゲームサーバーとの通信が発生する API の呼び出しの記録・取得機能( 10.2. )
  • 記録された API の呼び出し履歴から呼び出し頻度を集計しガイドラインの目安を超えていないかチェックする機能( 10.3. )
  • ゲームサーバーの挙動を変更する機能( 10.5. )
  • API 呼び出し時に意図的にエラーを発生させる機能( 10.6. )

前半の 3 つのデバッグ補助機能は、DebugClient から利用できます。 アクセス頻度のチェックを行うだけであれば、Debug サンプルをビルドして使用してください。

注意

パッケージには DebugClient の Release ビルド版ライブラリが含まれていません。そのため DebugClient をターゲットアプリケーションに組み込むことは推奨しません。 Debug サンプルを利用したり、これを元に専用のアプリケーションを作成することを推奨します。

10.2. ゲームサーバーとの通信が発生する API の呼び出しの記録

ゲームサーバーとの通信が発生する API の呼び出しをゲームサーバーで記録し、その履歴を取得・確認することでアプリの挙動を確認することが出来ます。 「ゲームサーバーへのアクセス制限」および「ゲームサーバーへの定期アクセスの禁止」についてのガイドライン項目の合格基準をみたしているかの確認にも使用できます。

記録される API 呼び出しの内容は以下のとおりです。

  • API を呼び出したクライアントの PrincipalID
  • 呼び出した API 名
  • 呼び出し時刻(UTC 時刻)

記録される API 名はライブラリ内部で使用される名前となるため、アプリケーションから呼び出す API 名とは異なります。 記録される API 名と実際にアプリケーションで呼び出す API 名との対応は、「 10.4. API名対応表 」 を参考にしてください。 また、ログイン時や NAT トラバーサル実行時にライブラリ内部で自動的に呼びだされる API も記録されることに留意してください(ライブラリ内部で自動的に呼びだされる API についてはアクセス制限に関するガイドライン項目の対象外となります)。

10.2.1. サービスクライアントの初期化・終了

DebugClient の初期化・終了処理はマッチメイクでのサービスクライアントの初期化・終了処理と同じとなります。

10.2.2. API呼び出しの記録機能と有効化・無効化

API呼び出しの記録機能は通常OFFになっているため、 DebugClient::EnableApiRecorder() を用いて有効化する必要があります。

Code 10.1 API呼び出しの記録機能の有効化・無効化
// 記録の有効化
qBool EnableApiRecorder(ProtocolCallContext* pContext);

// 記録の無効化
qBool DisableApiRecorder(ProtocolCallContext* pContext);

DebugClient::EnableApiRecorder() の非同期処理に成功すると、API呼び出しの記録機能が有効化されます。 機能が有効化されると、ゲームサーバーは最大1000件までの履歴を先入れ先出し方式で保持します。各履歴は最大 24 時間保持されます。

記録機能はDebugClient::DisableApiRecorder() を呼び出すか、24 時間以上サーバーへのAPI呼び出しが無かった場合に無効化されます。 無効化されるとそれまで保持していた履歴も併せて無効化されます。

機能の有効・無効はゲームサーバー全体で単一の設定となっているため、他のクライアントの操作によって状態が変わることに注意してください。

10.2.3. API呼び出し履歴の取得

記録したAPI呼び出し履歴を取得するには DebugClient::GetApiCalls() 関数を利用してください。

Code 10.2 API呼び出しの履歴を取得
// 記録の取得
qBool GetApiCalls(ProtocolCallContext *pContext,
                  qList<ApiCallData>* pApiCallDatas,
                  qList<PrincipalID>& principalIds,
                  DateTime sinceTime = DateTime::Never,
                  DateTime untilTime = DateTime::Never
                  );

principalIds に空のリストを与えることで、全てのクライアントのAPI呼び出し履歴を取得することが出来ます。 特定のクライアントの記録のみ取得する場合は、取得したい PrincipalID を指定してください。

取得する対象の期間を指定するには sinceTime, untilTime で指定できます。このとき、sinceTime, untilTime 丁度の秒は取得対象に 含まれません 。 例えば、2012-4-27 13:00:30 を sinceTime に指定した場合は 2012-4-27 13:00:31 からの履歴が取得されます。 また、sinceTime に DateTime::Never を指定するとゲームサーバーで保持されている履歴の全てが対象となり(その上でuntilTimeで制限がかかります)、untilTime に DateTime::Never を指定すると現在時刻(ミリ秒切り捨て)までのAPI呼び出し履歴が取得できます。

非同期処理に成功すると pApiCallDatas に履歴がセットされます。履歴は呼び出し順にソートされています。

10.3. API呼び出し履歴を集計する

DebugClient::GetApiCallSummary() 関数を使用することで、呼び出し履歴を集計し、ガイドラインで規定されている 呼び出し頻度の目安を超えていないかどうかをチェックすることができます。

10.3.1. API呼び出し頻度制限とは

NEX ではゲームサーバーの負荷軽減のために、API の呼び出し頻度を制限するガイドラインがあります。 ガイドラインではそれぞれのAPIに基準となる呼び出し頻度の目安が設定されており、基準を超えた頻度での呼び出しを制限しています。

詳細は、 「CTRガイドライン インターネット通信編」のNEXの項目 を参照してください。

目安は「基準期間」と「基準回数」として与えられ、「関数AはX秒間(基準時間)にY回(基準回数)までは呼んでよい」ということを示します。

補足

ランキングサービスなど、関数単体での呼び出し回数ではなくサービス全体での呼び出し回数の合計で制限しているパターンもあります。

10.3.2. 集計結果の取得

DebugClient::GetApiCallSummary() では集計の対象とする PrincipalID を指定することで、該当する PrincipalID のAPI呼び出しの集計をおこない、ガイドラインの目安を超えた頻度でAPIを呼び出していないか判定し、その結果を取得する事が出来ます。

Code 10.3 API呼び出し履歴の集計結果を取得
// 記録の取得
qBool GetApiCallSummary(ProtocolCallContext *pContext,
                        qList<ApiCallSummary>* pApiCallSummaryList,
                        PrincipalID principalId,
                        DateTime sinceTime = DateTime::Never,
                        DateTime untilTime = DateTime::Never,
                        qBool isLimitOverOnly = true
                        );

DebugClient::GetApiCallSummary() では集計の対象とする PrincipalID を引数で指定してください。 サーバーより取得した集計結果は pApiCallSummaryList ポインタの示すリストに入ります。

集計する期間を制限するには GetApiCalls() と同様に sinceTime, untilTime 引数を指定してください。 sinceTime 引数は集計する期間の始まりを指定します。sinceTime 引数に DateTime::Never を指定すると始まりを制限しない事になります。 untilTime 引数は集計する期間の終わりを指定します。untilTime 引数に DateTime::Never を指定するとサーバーの現在時刻(ミリ秒切り捨て)までが集計対象となります。

注意して頂きたい点として sinceTime, untilTime で指定した丁度の秒は集計の対象に 含まれません 。 例えば、sinceTime に 2013-4-27 13:00:30 を指定した場合は 2012-4-27 13:00:31 からの履歴が集計の対象となります。 同様に、untilTime に 2013-4-27 13:00:45 を指定すると44秒台までの履歴が集計の対象となります。

isLimitOverOnly 引数には標準で true の値が与えられており、この時はAPIの呼び出し頻度がガイドランの目安を超えた集計結果のみを返します。 もし、false を与えた場合にはガイドラインの目安を超えていない集計結果も合わせて取得する事ができます。

10.3.3. 集計結果の確認

集計結果( ApiCallSummary クラス)には、以下の情報が含まれています。

  • どのAPIの集計結果かを示す呼び出し関数名
  • 目安を超えているかどうか
  • 呼び出し頻度の目安(基準期間,基準回数)
  • 目安を超えた期間の始まりの時刻 と その期間内での呼び出し回数
  • 集計期間全体での総呼び出し回数
../_images/Fig_Debug_ApiCallSummary.png

Figure 10.1 集計結果に含む情報

呼び出し関数名は「MatchmakeExtensionProtocol::BrowseMatchmakeSession」といったサーバー側で記録されている形式となっています。 ランキングサービスなど複数のAPIの合計呼び出し回数で制限されている場合には「RankingProtocol::.*」の様に関数名が正規表現で表されています。

該当APIでの呼び出し頻度の目安(基準期間と基準回数)は ApiCallSummary::GetPeriod() および ApiCallSummary::GetLimit() で取得してください。

ApiCallSummary クラスには参考情報として、時系列で最初に目安を超えた期間とその期間内での呼び出し回数の情報を保持しています。 具体的には、ApiCallSummary::GetCallStartTime() で期間の始まりの時刻を取得でき、そこから基準期間内の間に呼ばれた回数が ApiCallSummary::GetCount() で取得できます。

補足

GetApiCallSummary で取得する際に isLimitOverOnly 引数に false を与えた場合には、API呼び出し頻度制限を超えていないAPI呼び出しも集計され取得されます。 呼び出し頻度を超えていない集計結果は ApiCallSummary::GetResult() の戻り値が DebugConstants::ApiCallSummaryResult_Normal となっています。 その場合 ApiCallSummary::GetCallStartTime(),ApiCallSummary::GetCount() で取得できる情報は、呼び出し頻度制限を超えた期間ではなく呼び出し頻度が最大となる期間の開始時刻と期間内でのAPI呼び出し回数の情報となります。

10.4. API名対応表

10.4.1. ファサード

Table 10.1 ファサード API 対応表
記録される API 名 ライブラリ内部の API 名
SecureConnectionInternalProtocol::TestConnectivity NgsFacade::TestConnectivity

10.4.2. マッチメイク

Table 10.2 マッチメイク API 対応表
記録される API 名 ライブラリ内部の API 名
MatchmakeExtensionProtocol::GetFriendNotificationData MatchmakeExtensionClient::GetFriendNotificationData
MatchmakeExtensionProtocol::GetlstFriendNotificationData MatchmakeExtensionClient::GetFriendNotificationData
MatchmakeExtensionProtocol::UpdateNotificationData MatchmakeExtensionClient::UpdateNotificationData
MatchmakeExtensionProtocol::AutoMatchmake_Postpone MatchmakeExtensionClient::AutoMatchmake
MatchmakeExtensionProtocol::AutoMatchmakeWithSearchCriteria_Postpone MatchmakeExtensionClient::AutoMatchmake
MatchmakeExtensionProtocol::AutoMatchmakeWithGatheringId_Postpone MatchmakeExtensionClient::AutoMatchmake
MatchmakeExtensionProtocol::AutoMatchmakeWithParam_Postpone MatchmakeExtensionClient::AutoMatchmake(AutoMatchmakeParam指定)
MatchmakeExtensionProtocol::BrowseMatchmakeSession MatchmakeExtensionClient::BrowseMatchmakeSession(GatheringHolderで取得)
MatchmakeExtensionProtocol::BrowseMatchmakeSessionWithHostUrls MatchmakeExtensionClient::BrowseMatchmakeSession(GatheringHolderで取得、ホストのURLも取得)
MatchmakeExtensionProtocol::BrowseMatchmakeSessionNoHolder MatchmakeExtensionClient::BrowseMatchmakeSession(MatchmakeSessionで取得)
MatchmakeExtensionProtocol::BrowseMatchmakeSessionWithHostUrlsNoHolder MatchmakeExtensionClient::BrowseMatchmakeSession(MatchmakeSessionで取得、ホストのURLも取得)
MatchmakeExtensionProtocol::CreateMatchmakeSession MatchmakeExtensionClient::CreateMatchmakeSession
MatchmakeExtensionProtocol::CreateMatchmakeSessionWithParam MatchmakeExtensionClient::CreateMatchmakeSession(CreateMatchmakeSessionParam指定)
MatchmakeExtensionProtocol::JoinMatchmakeSessionEx MatchmakeExtensionClient::JoinMatchmakeSession
MatchmakeExtensionProtocol::JoinMatchmakeSessionWithParam MatchmakeExtensionClient::JoinMatchmakeSession(JoinMatchmakeSessionParam指定)
MatchmakeExtensionProtocol::UpdateMatchmakeSession MatchmakeExtensionClient::UpdateMatchmakeSession
MatchmakeExtensionProtocol::UpdateMatchmakeSessionPart MatchmakeExtensionClient::UpdateMatchmakeSession(部分更新)
MatchmakeExtensionProtocol::UpdateMatchmakeSessionAttribute MatchmakeExtensionClient::UpdateMatchmakeSessionAttribute
MatchmakeExtensionProtocol::ModifyMatchmakeSessionAttribute MatchmakeExtensionClient::ModifyMatchmakeSessionAttribute
MatchmakeExtensionProtocol::ModifyCurrentGameAttribute MatchmakeExtensionClient::ModifyMatchmakeSessionAttribute
MatchmakeExtensionProtocol::UpdateApplicationBuffer MatchmakeExtensionClient::UpdateApplicationBuffer
MatchmakeExtensionProtocol::OpenParticipation MatchmakeExtensionClient::OpenParticipation
MatchmakeExtensionProtocol::CloseParticipation MatchmakeExtensionClient::CloseParticipation
MatchmakeExtensionProtocol::GetPlayingSession MatchmakeExtensionClient::GetPlayingSession
MatchmakeExtensionProtocol::UpdateProgressScore MatchmakeExtensionClient::UpdateProgressScore
MatchmakeExtensionProtocol::DebugNotifyEvent MatchmakeExtensionClient::DebugNotifyEvent
MatchmakeExtensionProtocol::GenerateMatchmakeSessionSystemPassword MatchmakeExtensionClient::GenerateMatchmakeSessionSystemPassword
MatchmakeExtensionProtocol::ClearMatchmakeSessionSystemPassword MatchmakeExtensionClient::ClearMatchmakeSessionSystemPassword
MatchmakeExtensionProtocol::FindMatchmakeSessionByGatheringIdDetail MatchmakeExtensionClient::FindMatchmakeSessionByGatheringIdDetail
MatchMakingProtocol::FindByID MatchMakingClient::FindByID(一括取得)
MatchMakingProtocol::FindBySingleID MatchMakingClient::FindByID(id指定)
MatchMakingProtocol::FindByOwner MatchMakingClient::FindByOwner
MatchMakingProtocol::GetSessionURLs MatchMakingClient::GetSessionURLs
MatchMakingProtocol::GetDetailedParticipants MatchMakingClient::GetDetailedParticipants
MatchMakingProtocol::UpdateSessionHost MatchMakingClient::UpdateSessionHost
MatchMakingProtocol::UnregisterGathering MatchMakingClient::UnregisterGathering
MatchMakingProtocol::MigrateGatheringOwnership MatchMakingClient::MigrateGatheringOwnership
MatchMakingProtocolExt::EndParticipation MatchMakingClient::EndParticipation
MatchmakeExtensionProtocol::CreateCommunity MatchmakeExtensionClient::CreatePersistentGathering
MatchmakeExtensionProtocol::UpdateCommunity MatchmakeExtensionClient::UpdatePersistentGathering
MatchmakeExtensionProtocol::JoinCommunity MatchmakeExtensionClient::JoinPersistentGathering
MatchmakeExtensionProtocol::FindCommunityByGatheringId MatchmakeExtensionClient::FindPersistentGatheringByGatheringId
MatchmakeExtensionProtocol::FindOfficialCommunity MatchmakeExtensionClient::FindOfficialPersistentGathering
MatchmakeExtensionProtocol::FindCommunityByParticipant MatchmakeExtensionClient::FindPersistentGatheringByParticipant
MatchmakeExtensionProtocol::CreateCommunity MatchmakeExtensionClient::CreateCommunity
MatchmakeExtensionProtocol::UpdateCommunity MatchmakeExtensionClient::UpdateCommunity
MatchmakeExtensionProtocol::JoinCommunity MatchmakeExtensionClient::JoinCommunity
MatchmakeExtensionProtocol::FindCommunityByGatheringId MatchmakeExtensionClient::FindCommunityByGatheringId
MatchmakeExtensionProtocol::FindOfficialCommunity MatchmakeExtensionClient::FindOfficialCommunity
MatchmakeExtensionProtocol::FindCommunityByParticipant MatchmakeExtensionClient::FindCommunityByParticipant
MatchmakeExtensionProtocol::UpdatePrivacySetting MatchmakeExtensionClient::UpdatePrivacySetting
MatchmakeExtensionProtocol::GetMyBlockList MatchmakeExtensionClient::GetMyBlockList
MatchmakeExtensionProtocol::AddToBlockList MatchmakeExtensionClient::AddToBlockList
MatchmakeExtensionProtocol::RemoveFromBlockList MatchmakeExtensionClient::RemoveFromBlockList
MatchmakeExtensionProtocol::ClearMyBlockList MatchmakeExtensionClient::ClearBlockList
MatchmakeExtensionProtocol::FindCommunityByOwner MatchmakeExtensionClient::FindPersistentGatheringByOwner
MatchmakeRefereeProtocol::StartRound MatchmakeRefereeClient::StartRound
MatchmakeRefereeProtocol::GetStartRoundParam MatchmakeRefereeClient::GetStartRoundParam
MatchmakeRefereeProtocol::EndRound MatchmakeRefereeClient::EndRound
MatchmakeRefereeProtocol::EndRoundWithoutReport MatchmakeRefereeClient::EndRoundWithoutReport
MatchmakeRefereeProtocol::GetRoundParticipants MatchmakeRefereeClient::GetRoundParticipants
MatchmakeRefereeProtocol::GetNotSummarizedRound MatchmakeRefereeClient::GetNotSummarizedRound
MatchmakeRefereeProtocol::GetRound MatchmakeRefereeClient::GetRound
MatchmakeRefereeProtocol::GetStatsPrimary MatchmakeRefereeClient::GetStats(対象プリンシパル ID の個人統計)
MatchmakeRefereeProtocol::GetStatsPrimaries MatchmakeRefereeClient::GetStats(対象プリンシパル ID のプライマリ関連 NEX ユニーク ID の個人統計)
MatchmakeRefereeProtocol::GetStatsAll MatchmakeRefereeClient::GetStats(対象プリンシパル ID の全ての関連 NEX ユニーク ID の個人統計)
MatchmakeRefereeProtocol::CreateStats MatchmakeRefereeClient::CreateStats
MatchmakeRefereeProtocol::GetOrCreateStats MatchmakeRefereeClient::GetOrCreateStats
MatchmakeRefereeProtocol::ResetStats MatchmakeRefereeClient::ResetStats

10.4.3. メッセージング

Table 10.3 メッセージング API 対応表
記録される API 名 ライブラリ内部の API 名
MessagingProtocol::DeliverMessage MessagingClient::SendInstant または MessagingClient::SendChat

10.4.4. ユーティリティ

Table 10.4 ユーティリティ API 対応表
記録される API 名 ライブラリ内部の API 名
UtilityProtocol::AcquireNexUniqueId UtilityClient::AcquireNexUniqueId

10.4.5. ランキング

Table 10.5 ランキング API 対応表
記録される API 名 ライブラリ内部の API 名
RankingProtocol::UploadScore RankingClient::UploadScore
RankingProtocol::DeleteScore RankingClient::DeleteScore
RankingProtocol::DeleteAllScores RankingClient::DeleteScore
RankingProtocol::UploadCommonData RankingClient::UploadCommonData
RankingProtocol::DeleteCommonData RankingClient::DeleteCommonData
RankingProtocol::GetCommonData RankingClient::GetCommonData
RankingProtocol::ChangeAttributes RankingClient::ChangeAttributes
RankingProtocol::ChangeAllAttributes RankingClient::ChangeAttributes
RankingProtocol::GetRanking RankingClient::GetRanking
RankingProtocol::GetRankingByPIDList RankingClient::GetRankingByPIDList
RankingProtocol::GetRankingByUniqueIdList RankingClient::GetRankingByUniqueIdList
RankingProtocol::GetApproxOrder RankingClient::GetApproxOrder
RankingProtocol::GetStats RankingClient::GetStats
RankingProtocol::GetCachedTopXRanking RankingClient::GetCachedTopXRanking
RankingProtocol::GetCachedTopXRankings RankingClient::GetCachedTopXRankings

10.4.6. ランキング 2

Table 10.6 ランキング 2 API対応表
記録されるAPI名 ライブラリ側API名
Ranking2Protocol::PutScore Ranking2Client::PutScore または Ranking2Client::PutScore(複数登録)
Ranking2Protocol::GetCommonData Ranking2Client::GetCommonData
Ranking2Protocol::PutCommonData Ranking2Client::PutCommonData
Ranking2Protocol::DeleteCommonData Ranking2Client::DeleteCommonData
Ranking2Protocol::GetRanking Ranking2Client::GetRanking
Ranking2Protocol::GetRankingByPrincipalId Ranking2Client::GetRanking(プリンシパル ID リスト)
Ranking2Protocol::GetCategorySetting Ranking2Client::GetCategorySetting
Ranking2Protocol::GetEstimateScoreRank Ranking2Client::GetEstimateScoreRank
Ranking2Protocol::GetRankingChart Ranking2Client::GetRankingChart(単数)
Ranking2Protocol::GetRankingCharts Ranking2Client::GetRankingChart(複数)

10.4.7. データストア

Table 10.7 データストア API 対応表
記録される API 名 ライブラリ内部の API 名
DataStoreProtocol::PrepareGetObject DataStoreClient::GetObject
DataStoreProtocol::PostMetaBinary DataStoreClient::PostObject(メタ情報のみアップロードする場合)
DataStoreProtocol::PreparePostObject DataStoreClient::PostObject(※1)
DataStoreProtocol::CompletePostObject DataStoreClient::PostObject(※1)
DataStoreProtocol::PrepareUpdateObject DataStoreClient::UpdateObject(※2)
DataStoreProtocol::CompleteUpdateObject DataStoreClient::UpdateObject(※2)
DataStoreProtocol::DeleteObject DataStoreClient::DeleteObject
DataStoreProtocol::DeleteObjects DataStoreClient::DeleteObject(一括処理)
DataStoreProtocol::ChangeMeta DataStoreClient::ChangeMeta
DataStoreProtocol::ChangeMetas DataStoreClient::ChangeMeta(一括処理)
DataStoreProtocol::GetMeta DataStoreClient::GetMeta
DataStoreProtocol::GetMetas または DataStoreProtocol::GetMetasMultipleParam DataStoreClient::GetMeta(一括処理)
DataStoreProtocol::SearchObject DataStoreClient::SearchObject
DataStoreProtocol::SearchObjectLight DataStoreClient::SearchObjectLight
DataStoreProtocol::RateObject DataStoreClient::RateObject
DataStoreProtocol::GetRating DataStoreClient::GetRating
DataStoreProtocol::GetRatings DataStoreClient::GetRating(一括処理)
DataStoreProtocol::ResetRating DataStoreClient::ResetRating
DataStoreProtocol::ResetRatings DataStoreClient::ResetRating(一括処理)
DataStoreProtocol::TouchObject DataStoreClient::TouchObject
DataStoreProtocol::GetPersistenceInfo DataStoreClient::GetPersistenceInfo
DataStoreProtocol::GetPersistenceInfos DataStoreClient::GetPersistenceInfo(一括処理)
DataStoreProtocol::PerpetuateObject DataStoreClient::PerpetuateObject
DataStoreProtocol::UnperpetuateObject DataStoreClient::UnperpetuateObject
DataStoreProtocol::GetPasswordInfo DataStoreClient::GetPasswordInfo
DataStoreProtocol::GetPasswordInfos DataStoreClient::GetPasswordInfo(一括処理)
DataStoreProtocol::CompletePostObjects DataStoreClient::CompleteSuspendedPostObject

10.4.8. サブスクライバー

Table 10.8 サブスクライバー API 対応表
記録される API 名 ライブラリ内部の API 名
SubscriberProtocol::PostContent SubscriberClient::PostContent
SubscriberProtocol::GetContent SubscriberClient::GetContent
SubscriberProtocol::GetContentMulti SubscriberClient::GetContent(複数取得)
SubscriberProtocol::Follow SubscriberClient::Follow
SubscriberProtocol::UnfollowAllAndFollow SubscriberClient::UnfollowAllAndFollow または SubscriberClient::UnfollowAll
SubscriberProtocol::Unfollow SubscriberClient::Unfollow
SubscriberProtocol::GetFollowing SubscriberClient::GetFollowing
SubscriberProtocol::GetFollower SubscriberClient::GetFollower
SubscriberProtocol::GetNumFollowers SubscriberClient::GetNumFollowers
SubscriberProtocol::GetTimeline SubscriberClient::GetTimeline
SubscriberProtocol::DeleteContent SubscriberClient::DeleteContent

10.4.9. デバッグ補助

Table 10.9 デバッグ補助 API 対応表
記録される API 名 ライブラリ内部の API 名
DebugProtocol::EnableApiRecorder DebugClient::EnableApiRecorder
DebugProtocol::DisableApiRecorder DebugClient::DisableApiRecorder
DebugProtocol::IsApiRecorderEnabled DebugClient::IsApiRecorderEnabled
DebugProtocol::GetApiCalls DebugClient::GetApiCalls
DebugProtocol::GetApiSummary DebugClient::GetApiSummary
DebugProtocol::SetExcludeJoinedMatchmakeSession DebugClient::SetExcludeJoinedMatchmakeSession
DebugProtocol::GetExcludeJoinedMatchmakeSession DebugClient::GetExcludeJoinedMatchmakeSession

10.4.10. ライブラリが自動で呼び出す API

Table 10.10 ライブラリが自動で呼び出す API の一覧
ライブラリ内部の API 名 呼び出されるタイミング
SecureConnectionInternalProtocol::GetConnectionID ログイン時
SecureConnectionInternalProtocol::InsertConnectionProperties ログイン時
SecureConnectionInternalProtocol::UpdateConnectionProperties NAT トラバーサル時
SecureConnectionInternalProtocol::ReplaceConnectionProperties NAT トラバーサル時
NATTraversalReportInternalProtocol::ReportNATTraversalResult NAT トラバーサル時
NATTraversalReportInternalProtocol::ReportNATTraversalResultDetail NAT トラバーサル時
NATTraversalReportInternalProtocol::ReportNATProperties ログイン後の初回 ConnectivityManager::StartNatSession() 時

10.4.11. 記録用のダミーの API

以下の API は、サーバーから切断した時の記録を残すためにダミーとして用意しているもので、実際には存在しません。

Table 10.11 記録用のダミーの API の一覧
ライブラリ内部の API 名 呼び出されるタイミング
DummyProtocol::LogoutNormally NgsFacade::Logout() によりログアウトした場合
DummyProtocol::LogoutFaultily 通信断や電源断などにより自動的にログアウトした場合

10.5. ゲームサーバーの挙動を変更する

デバッグ用途に限り、ゲームサーバーの挙動を変更することが出来ます。 MatchmakeExtensionClient::AutoMatchmake() で過去に参加したマッチメイクセッションを参加対象から除外するかどうかの設定変更が可能です。

補足

ゲームサーバー全体に関わる設定変更については、将来的に管理用の Web システムが提供される予定です。 その際には、設定変更 API は DebugClient からは削除されます。

10.5.1. 過去に参加したマッチメイクセッションの除外設定を変更する

ゲームサーバーのデフォルト設定では、 MatchmakeExtensionClient::AutoMatchmake() で、過去3回にわたって参加したマッチメイクセッションに関して、サーバー側で参加対象から外しています。アプリケーションのデバッグ時に、 MatchmakeExtensionClient::AutoMatchmake() 同じマッチメイクセッションに参加したいという場合には、DebugClient::SetExcludeJoinedMatchmakeSession() で設定を変更してください。

DebugClient::SetExcludeJoinedMatchmakeSession() はゲームサーバー全体の設定になります。設定を変更する上では、同じゲームサーバーに接続している他の開発者に影響があることを留意してください。また、製品用ゲームサーバーでは設定変更はできません(常に参加対象から外されます)。そのため、過去に参加したマッチメイクセッションの除外設定がオフになっていることを前提にしてアプリケーションを開発しないでください。

10.6. API 呼び出し時に意図的にエラーを発生させる

デバッグ用途に限り、API 呼び出し時に意図的にエラーを発生させる、エラーシミュレーションの機能を利用できます。 アプリケーションが NEX API のエラーハンドリングを正しく行っているかを確認するために使用します。

エラーシミュレーションは、エラーを発生させる対象のプリンシパル ID と API 名を指定して、エラーのシーケンスとして登録することができます。また 1 つのプリンシパル ID に対して、複数の API にシミュレーションの設定を登録することもできます。

例えば以下のようなエラーシミュレーションの設定をすることが可能です。

注意

MessagingClient::SendInstant() 、MessagingClient::SendChat() にはエラーシミュレーションを適用することはできません。 これらの API にエラーシミュレーションの設定を登録しても無視されます。

補足

エラーシミュレーションの設定の登録や実行ログの確認などについては、NEX ゲームサーバー管理ツール( NMAS, Nex server MAnagement System )を利用してください。

10.6.1. エラーシミュレーションの設定内容

エラーシミュレーションの設定には以下の項目があります。

  • プリンシパル ID

    エラーシミュレーションの対象となるプリンシパル ID です。

  • API 名

    エラーシミュレーションの対象となる API 名です。 エラーシミュレーションで指定する API 名はライブラリ内部で使用する名前となるため、アプリケーションから呼び出す API とは異なりますので、ご注意ください。ライブラリ内部で使用する API と アプリケーションから呼び出す API の対応については「 10.4. API名対応表 」を参照してください。

    またゲームサーバーへのログイン時にエラーを発生させたい場合は、API 名に Login と指定してください。 エラーシミュレーションの設定登録時に、ログイン時にライブラリ内部で使用する API である SecureConnectionInternalProtocol::GetConnectionID() に自動的に変換してシミュレーションの登録を行います。

  • シミュレーション設定の有効期限

    シミュレーションの設定には有効期限が存在します。有効期限が切れたシミュレーション設定は、自動的にゲームサーバーから削除されます。デフォルトの有効期限は 1 時間で、 シミュレーション設定の登録時に有効期限を指定することも可能です。

  • リターンコード

    クライアントに返すリターンコードです。リターンコードにエラーコードを指定した場合は、ゲームサーバー上ではAPI の処理そのものは実行されず、クライアントにエラーを返すだけの動作となります。 リターンコードにサクセスコードもしくは何も指定しなかった場合は、ゲームサーバー上では通常通り API の処理が実行されます。サクセスコードを指定しても、API が正常に動作しなかった場合はエラーが返ることがあります。

  • 回数

    上記のリターンコードを返し続ける回数です。同じエラーコードを返し続けたい場合は、こちらに大きな値を指定してください。 呼び出した回数によってエラーを変えたい場合は、その回数に合わせて指定してください。

リターンコードと回数の組み合わせは複数指定することができます。API を呼び出した回数によってクライアントに返すエラーを切り替えたい場合は、想定しているエラーのシーケンスに合うようにこの組み合わせを設定してください。

エラーシミュレーションの設定の登録や、登録済みのエラーシミュレーションの設定の確認・削除は WebAPI から実行できます。 WebAPI の詳細は「 12.6.2. エラーシミュレーション 」を参照してください。

10.6.2. エラーシミュレーションの実行ログ

クライアントからの API 呼び出し時にエラーシミュレーションが適用された際は、シミュレーションの実行ログがゲームサーバー上で保存されます。 実行ログには以下の情報が含まれます。

  • エラーシミュレーションを適用した API 名
  • クライアントに返したリターンコード
  • エラーシミュレーションの適用日時

実行ログはプリンシパル ID を指定して、WebAPI から取得できます。WebAPI の詳細は「 12.6.2.5. エラーシミュレーションの実行ログの取得 」を参照してください。

エラーシミュレーションの実行ログは、実行ログの登録から 24 時間の有効期限が存在します。 有効期限を過ぎた実行ログはゲームサーバー上から削除されますので、ご注意ください。