GS2-JobQueue SDK for Game Engine API リファレンス
モデル
EzJob
ジョブ
ジョブキューとは直ちに処理を完了せず、処理を遅延実行するための仕組みです。
例えば、キャラクターを入手したときに直ちに実行しなければならない処理としては所持品にキャラクターを格納することです。
一方で、直ちに処理しなければならないわけではない処理として、図鑑に登録する
という処理があります。
こういった直ちに処理するまでもない処理をジョブキューを経由して処理するようにすることで、障害に強い設計にすることができます。
なぜなら、図鑑サービスが何らかの障害によって止まっていたとしても、図鑑に登録されない状態でゲームを継続することができます。
ジョブキューに詰まれた処理は失敗しても、障害が解消した後でリトライすることで結果的に正しい状態にできます。
GS2 ではこのような 結果整合
処理を推奨しており、様々な場面でジョブキューを利用した遅延処理が行われます。
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
jobId | string | ✓ | ~ 1024文字 | ジョブGRN | |
scriptId | string | ✓ | ~ 1024文字 | スクリプトGRN | |
args | string | ✓ | ~ 5242880文字 | 引数 | |
currentRetryCount | int | ✓ | 0 | ~ 100 | 現在のリトライ回数 |
maxTryCount | int | ✓ | 3 | 1 ~ 100 | 最大試行回数 |
EzJobResult
ジョブ実行結果
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
statusCode | int | ✓ | ~ 1000 | ステータスコード | |
result | string | ✓ | ~ 5242880文字 | レスポンスの内容 |
EzJobEntry
登録ジョブ
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
scriptId | string | ✓ | ~ 1024文字 | スクリプトGRN | |
args | string | ✓ | “{}” | ~ 131072文字 | 引数 |
maxTryCount | int | ✓ | 3 | ~ 100 | 最大試行回数 |
EzJobResultBody
ジョブの実行結果
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
tryNumber | int | ✓ | 1 ~ 10000 | 試行回数 | |
statusCode | int | ✓ | ~ 1000 | ステータスコード | |
result | string | ✓ | ~ 5242880文字 | レスポンスの内容 | |
tryAt | long | ✓ | 現在時刻 | 作成日時 (UNIX時間 単位:ミリ秒) |
メソッド
run
タスクキューのジョブを実行。
タスクキューのプッシュ通知設定をすることでタスクキューに新しくジョブが追加されたときにプッシュ通知を受けることができます。
定期的にこのAPIを呼び出すか、プッシュ通知をトリガーしてこのAPIを呼び出してください。isLastJob
が false を返している間は繰り返し実行してください。
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID |
Result
型 | 説明 | |
---|---|---|
item | EzJob | ジョブ |
result | EzJobResultBody | ジョブの実行結果 |
isLastJob | bool |
Error
このAPIには特別な例外が定義されています。
GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は こちら のドキュメントを参考にしてください。
型 | 基底クラス | 説明 |
---|---|---|
ConflictException | ConflictException | ジョブキューの実行が衝突しました。リトライが必要です |
実装例
// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API
// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API
// SDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
getResult
ジョブの実行結果を取得
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID | |
jobName | string | ✓ | UUID | ~ 36文字 | ジョブの名前 |
Result
型 | 説明 | |
---|---|---|
item | EzJobResult | ジョブの実行結果 |
実装例
var domain = gs2.JobQueue.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Job(
jobName: "job-0001"
).JobResult(
tryNumber: null
);
var item = await domain.ModelAsync();
var domain = gs2.JobQueue.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Job(
jobName: "job-0001"
).JobResult(
tryNumber: null
);
var future = domain.Model();
yield return future;
var item = future.Result;
const auto Domain = Gs2->JobQueue->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Job(
"job-0001" // jobName
)->JobResult(
nullptr // tryNumber
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
値の変更イベントハンドリング
var domain = gs2.JobQueue.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Job(
jobName: "job-0001"
).JobResult(
tryNumber: null
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
var domain = gs2.JobQueue.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Job(
jobName: "job-0001"
).JobResult(
tryNumber: null
);
var future = domain.Model();
yield return future;
var item = future.Result;
const auto Domain = Gs2->JobQueue->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Job(
"job-0001" // jobName
)->JobResult(
nullptr // tryNumber
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::JobQueue::Model::FJobResult> value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
イベントハンドラ
OnPushNotification
ジョブキューにジョブが登録されたときに使用する通知
名前 | 型 | 説明 |
---|---|---|
namespaceName | string | ネームスペース名 |
userId | string | ユーザーID |
実装例
gs2.JobQueue.OnPushNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var userId = notification.UserId;
};
gs2.JobQueue.OnPushNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var userId = notification.UserId;
};
Gs2->JobQueue->OnPushNotification().AddLambda([](const auto Notification)
{
const auto NamespaceName = Notification->NamespaceNameValue;
const auto UserId = Notification->UserIdValue;
});
OnRunNotification
ジョブキューのジョブを実行した時に使用する通知
名前 | 型 | 説明 |
---|---|---|
namespaceName | string | ネームスペース名 |
userId | string | ユーザーID |
jobName | string | ジョブの名前 |
実装例
gs2.JobQueue.OnRunNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var userId = notification.UserId;
var jobName = notification.JobName;
};
gs2.JobQueue.OnRunNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var userId = notification.UserId;
var jobName = notification.JobName;
};
Gs2->JobQueue->OnRunNotification().AddLambda([](const auto Notification)
{
const auto NamespaceName = Notification->NamespaceNameValue;
const auto UserId = Notification->UserIdValue;
const auto JobName = Notification->JobNameValue;
});