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