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

モデル

EzJob

ジョブ

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

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

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

必須デフォルト値の制限説明
jobIdstring~ 1024文字ジョブGRN
scriptIdstring~ 1024文字スクリプトGRN
argsstring~ 5242880文字引数
currentRetryCountint0~ 100現在のリトライ回数
maxTryCountint31 ~ 100最大試行回数

EzJobResult

ジョブ実行結果

必須デフォルト値の制限説明
statusCodeint~ 1000ステータスコード
resultstring~ 5242880文字レスポンスの内容

EzJobEntry

登録ジョブ

必須デフォルト値の制限説明
scriptIdstring~ 1024文字スクリプトGRN
argsstring“{}”~ 131072文字引数
maxTryCountint3~ 100最大試行回数

EzJobResultBody

ジョブの実行結果

必須デフォルト値の制限説明
tryNumberint1 ~ 10000試行回数
statusCodeint~ 1000ステータスコード
resultstring~ 5242880文字レスポンスの内容
tryAtlong現在時刻作成日時 (UNIX時間 単位:ミリ秒)

メソッド

run

タスクキューのジョブを実行。

タスクキューのプッシュ通知設定をすることでタスクキューに新しくジョブが追加されたときにプッシュ通知を受けることができます。
定期的にこのAPIを呼び出すか、プッシュ通知をトリガーしてこのAPIを呼び出してください。
isLastJob が false を返している間は繰り返し実行してください。

Request

必須デフォルト値の制限説明
namespaceNamestring~ 128文字ネームスペース名
accessTokenstring~ 128文字ユーザーID

Result

説明
itemEzJobジョブ
resultEzJobResultBodyジョブの実行結果
isLastJobbool

Error

このAPIには特別な例外が定義されています。
GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は こちら のドキュメントを参考にしてください。

基底クラス説明
ConflictExceptionConflictExceptionジョブキューの実行が衝突しました。リトライが必要です

実装例

// 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

必須デフォルト値の制限説明
namespaceNamestring~ 128文字ネームスペース名
accessTokenstring~ 128文字ユーザーID
jobNamestringUUID~ 36文字ジョブの名前

Result

説明
itemEzJobResultジョブの実行結果

実装例

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

イベントハンドラ

OnPushNotification

ジョブキューにジョブが登録されたときに使用する通知

名前説明
namespaceNamestringネームスペース名
userIdstringユーザー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

ジョブキューのジョブを実行した時に使用する通知

名前説明
namespaceNamestringネームスペース名
userIdstringユーザーID
jobNamestringジョブの名前

実装例

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