NAV
Unity Unreal Engine 4

GS2-JobQueue

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

ゲームエンジン向けSDK

モデル

EzJob

ジョブ

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

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

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

説明
jobId string ジョブGRN
scriptId string スクリプトGRN
args string 引数
currentRetryCount int 現在のリトライ回数
maxTryCount int 最大試行回数

EzJobResult

説明
statusCode int ステータスコード
result string レスポンスの内容

EzJobEntry

説明
scriptId string スクリプトGRN
args string 引数
maxTryCount int 最大試行回数

EzJobResultBody

説明
tryNumber int 試行回数
statusCode int ステータスコード
result string レスポンスの内容
tryAt long 作成日時

メソッド

run

run

ProfilePtr = std::make_shared<gs2::ez::Profile>(
    TCHAR_TO_ANSI(*ClientId),
    TCHAR_TO_ANSI(*ClientSecret),
    gs2::ez::Gs2BasicReopener()
);

ClientPtr = std::make_shared<gs2::ez::Client>(
    *ProfilePtr
);

ProfilePtr->initialize(
    [this](gs2::ez::Profile::AsyncInitializeResult r)
    {
        if (r.getError())
        {
            GEngine->AddOnScreenDebugMessage(-1, 5.f, FColor::Red, "profile.initialize failed.");
        }
        else
        {
            AccountCreate();
        }
    }
);

// Up to this line is the initialization process.

ClientPtr->jobQueue.run(
    [](gs2::ez::account::AsyncEzRunResult r)
    {
        if (r.getError())
        {
            GEngine->AddOnScreenDebugMessage(-1, 5.f, FColor::Red, "jobQueue.run failed.");
        }
        else
        {
            Item = r.getResult()->getItem();
            Result = r.getResult()->getResult();
            IsLastJob = r.getResult()->getIsLastJob();
        }
    },
    ProfilePtr->getGs2Session(),
    TCHAR_TO_ANSI("namespace2") // namespaceName
);

///////////////////////////////////////////////////////////////
// New Experience (Enabled UniTask)
///////////////////////////////////////////////////////////////
// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API
///////////////////////////////////////////////////////////////
// Legacy Experience
///////////////////////////////////////////////////////////////

using Gs2.Core.AsyncResult;
using Gs2.Gs2Account.Unity.Result;
using Gs2.Unity.Util;

var profile = new Profile(
    clientId: "your client id",
    clientSecret: "your client secret",
    reopener: new Gs2BasicReopener()
);

{
    AsyncResult<object> asyncResult = null;

    var current = profile.Initialize(
        r => { asyncResult = r; }
    );

    yield return current;

    if (asyncResult.Error != null)
    {
        OnError(asyncResult.Error);
        yield break;
    }
}
var gs2 = new Gs2.Unity.Client(profile);

// Up to this line is the initialization process.

{
    AsyncResult<EzRunResult> asyncResult = null;
    var current = gs2.JobQueue.Run(
        callback: r => { asyncResult = r; },
        session: session,
        namespaceName: "namespace2"
    );

    yield return current;
    if (asyncResult.Error != null)
    {
        OnError(asyncResult.Error);
        yield break;
    }

    var result = asyncResult.Result;
    var item = result.Item;
    var result = result.Result;
    var isLastJob = result.IsLastJob;
}

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

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

Request

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

Result

説明
item EzJob ジョブ
result EzJobResultBody ジョブの実行結果
isLastJob bool

getResult

getResult

ProfilePtr = std::make_shared<gs2::ez::Profile>(
    TCHAR_TO_ANSI(*ClientId),
    TCHAR_TO_ANSI(*ClientSecret),
    gs2::ez::Gs2BasicReopener()
);

ClientPtr = std::make_shared<gs2::ez::Client>(
    *ProfilePtr
);

ProfilePtr->initialize(
    [this](gs2::ez::Profile::AsyncInitializeResult r)
    {
        if (r.getError())
        {
            GEngine->AddOnScreenDebugMessage(-1, 5.f, FColor::Red, "profile.initialize failed.");
        }
        else
        {
            AccountCreate();
        }
    }
);

// Up to this line is the initialization process.

ClientPtr->jobQueue.getJobResult(
    [](gs2::ez::account::AsyncEzGetJobResultResult r)
    {
        if (r.getError())
        {
            GEngine->AddOnScreenDebugMessage(-1, 5.f, FColor::Red, "jobQueue.getJobResult failed.");
        }
        else
        {
            Item = r.getResult()->getItem();
        }
    },
    ProfilePtr->getGs2Session(),
    TCHAR_TO_ANSI("namespace1"), // namespaceName
    TCHAR_TO_ANSI("job-0001") // jobName
);

///////////////////////////////////////////////////////////////
// New Experience (Enabled UniTask)
///////////////////////////////////////////////////////////////

using Gs2.Unity.Util;
#if GS2_ENABLE_UNITASK
using Cysharp.Threading.Tasks;
using Cysharp.Threading.Tasks.Linq;
#endif

var profile = new Profile(
    clientId: "your client id",
    clientSecret: "your client secret",
    reopener: new Gs2BasicReopener()
);
await profile.InitializeAsync();
var gs2 = new Gs2.Unity.Core.Gs2Domain(profile);

// Up to this line is the initialization process.

{
    var domain = gs2.JobQueue.Namespace(
        namespaceName: "namespace1"
    ).Me(
        gameSession: gameSession
    ).Job(
        jobName: "job-0001"
    ).JobResult(
        tryNumber: null
    );
    var item = await domain.ModelAsync();
}
///////////////////////////////////////////////////////////////
// Legacy Experience
///////////////////////////////////////////////////////////////

using Gs2.Core.AsyncResult;
using Gs2.Gs2Account.Unity.Result;
using Gs2.Unity.Util;

var profile = new Profile(
    clientId: "your client id",
    clientSecret: "your client secret",
    reopener: new Gs2BasicReopener()
);

{
    AsyncResult<object> asyncResult = null;

    var current = profile.Initialize(
        r => { asyncResult = r; }
    );

    yield return current;

    if (asyncResult.Error != null)
    {
        OnError(asyncResult.Error);
        yield break;
    }
}
var gs2 = new Gs2.Unity.Client(profile);

// Up to this line is the initialization process.

{
    AsyncResult<EzGetResultResult> asyncResult = null;
    var current = gs2.JobQueue.GetResult(
        callback: r => { asyncResult = r; },
        session: session,
        namespaceName: "namespace1",
        jobName: "job-0001"
    );

    yield return current;
    if (asyncResult.Error != null)
    {
        OnError(asyncResult.Error);
        yield break;
    }

    var result = asyncResult.Result;
    var item = result.Item;
}

ジョブの実行結果を取得

Request

必須 デフォルト 値の制限 説明
namespaceName string ~ 32文字 ネームスペース名
accessToken string ~ 128文字 ユーザーID
jobName string UUID ~ 36文字 ジョブの名前

Result

説明
item EzJobResult ジョブの実行結果