GS2-JobQueue SDK for Game Engine API リファレンス

ゲームエンジン向け GS2-JobQueue SDK のモデルの仕様と API のリファレンス

モデル

EzJob

ジョブ

ジョブキューとは直ちに処理を完了せず、処理を遅延実行するための仕組みです。
例えば、キャラクターを入手したときに直ちに実行しなければならない処理としては所持品にキャラクターを格納することです。
一方で、直ちに処理しなければならないわけではない処理として、図鑑に登録する という処理があります。

こういった直ちに処理するまでもない処理をジョブキューを経由して処理するようにすることで、障害に強い設計にすることができます。
なぜなら、図鑑サービスが何らかの障害によって止まっていたとしても、図鑑に登録されない状態でゲームを継続することができます。
ジョブキューに詰まれた処理は失敗しても、障害が解消した後でリトライすることで結果的に正しい状態にできます。

GS2 ではこのような 結果整合 処理を推奨しており、様々な場面でジョブキューを利用した遅延処理が行われます。

	型	必須	デフォルト	値の制限	説明
jobId	string	※		~ 1024文字	ジョブ GRN ※ サーバーが自動で設定
scriptId	string	✓		~ 1024文字	スクリプト GRN
args	string	✓		~ 5242880文字	引数ジョブの実行時にスクリプトに渡すJSON形式のリクエストパラメータです。アクションタイプや対象リソースなどの具体的な操作内容を含みます。最大5MBです。
currentRetryCount	int		0	0 ~ 100	現在のリトライ回数失敗後にこのジョブがリトライされた回数です。リトライ可能なエラーで実行が終了するたびにインクリメントされます。このカウントがmaxTryCountに達すると、ジョブは恒久的な失敗としてマークされます。
maxTryCount	int		3	1 ~ 100	最大試行回数初回の試行とリトライを含めて、このジョブを実行できる最大回数です。すべての試行が失敗した場合、ジョブは放棄されます。デフォルトは3、最大100です。

EzJobResult

ジョブ実行結果

単一のジョブ実行試行の結果を記録します。各試行ごとに個別のJobResultが作成されるため、複数回リトライされたジョブには複数の結果が存在します。statusCodeはジョブが成功したか失敗したかを示します。

	型	有効化条件	必須	デフォルト	値の制限	説明
statusCode	int		✓		0 ~ 1000	ステータスコードスクリプト実行から返されたHTTPステータスコードです。2xxコードは成功を示し、その他のコードは失敗を示します。リトライ可能なエラーの場合、maxTryCountに達していなければ自動リトライが行われることがあります。
result	string		✓		~ 5242880文字	レスポンスの内容スクリプト実行から返されたJSON形式のレスポンスボディです。成功時には結果データを、失敗時にはエラーの詳細を含みます。最大5MBです。

EzJobEntry

登録ジョブ

ジョブキューに新しいジョブを登録するためのパラメータを表します。実行するスクリプト、JSON引数、最大リトライ回数を含みます。ジョブをキューにプッシュする際の入力として使用されます。

	型	必須	デフォルト	値の制限	説明
scriptId	string	✓		~ 1024文字	スクリプト GRN
args	string		“{}”	~ 131072文字	引数ジョブの実行時にスクリプトに渡すJSON形式のリクエストパラメータです。デフォルトは空のJSONオブジェクト “{}” です。最大128KBです。
maxTryCount	int		3	0 ~ 100	最大試行回数初回の試行とリトライを含めて、ジョブを実行できる最大回数です。デフォルトは3、最大100です。

EzJobResultBody

ジョブの実行結果

試行番号、ステータスコード、レスポンス内容、実行タイムスタンプを含むジョブ実行結果の軽量な表現です。

	型	必須	デフォルト	値の制限	説明
tryNumber	int	✓		1 ~ 10000	試行回数この実行結果の連番試行番号で、1から始まります。どのリトライ試行がこの結果を生成したかを識別するために使用されます。
statusCode	int	✓		0 ~ 1000	ステータスコードスクリプト実行から返されたHTTPステータスコードです。2xxコードは成功を示し、その他のコードは失敗を示します。リトライ可能なエラーの場合、maxTryCountに達していなければ自動リトライが行われることがあります。
result	string	✓		~ 5242880文字	レスポンスの内容スクリプト実行から返されたJSON形式のレスポンスボディです。成功時には結果データを、失敗時にはエラーの詳細を含みます。最大5MBです。
tryAt	long	※	現在時刻		作成日時 UNIX 時間・ミリ秒 ※ サーバーが自動で設定

メソッド

run

プレイヤーのジョブキューにある次のジョブを実行する

GS2 では、すぐに完了しなくてもよい処理を「ジョブキュー」で遅延実行します。たとえば、キャラクターを入手したとき、所持品への追加は即座に行いますが、図鑑への登録はジョブキューを通じて後から処理できます。
この仕組みにより、関連サービスが一時的に停止していてもゲームを継続でき、キューに溜まったジョブはサービス復旧後にリトライされて正しい状態になります。

このAPIを呼び出すと、プレイヤーのキューにある次のジョブを1つ実行し、その結果を返します。
レスポンスに含まれる isLastJob フラグが false の場合はまだ未処理のジョブが残っているため、true になるまで繰り返し呼び出してください。

ネームスペースにプッシュ通知を設定しておけば、新しいジョブが追加されたタイミングで通知を受け取れるため、ポーリングせずに通知をトリガーにしてこのAPIを呼び出すこともできます。

ネームスペースで enableAutoRun を有効にしている場合は、ジョブはサーバー側で自動実行されるため、このAPIを呼び出す必要はありません。

Request

	型	有効化条件	必須	デフォルト	値の制限	説明
namespaceName	string		✓		~ 128文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
gameSession	GameSession		✓			GameSession

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文字	ネームスペース名ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
gameSession	GameSession	✓			GameSession
jobName	string	✓	UUID	~ 36文字	ジョブの名前ジョブの一意な名前を保持します。名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各ジョブを識別するために使用されます。

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.ModelFuture();
    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 callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

    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	ジョブの名前ジョブの一意な名前を保持します。名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各ジョブを識別するために使用されます。

実装例

    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;
    });