API Reference of GS2-JobQueue SDK for Game Engine

Model

EzJob

Job

A job queue is a mechanism for delaying the execution of a process rather than completing it immediately. For example, when a character is acquired, the process that must be executed immediately is to store the character in the possession. On the other hand, a process that does not have to be executed immediately is the process of `registering the character in the picture book.

By processing these processes that do not need to be processed immediately via a job queue, the design can be made more resilient to failures. This is because even if the illustrated book service is stopped due to some failure, the game can continue without being registered in the illustrated book. Even if the process packed in the job queue fails, it can be retried after the failure is resolved, resulting in a correct state.

GS2 recommends this kind of result matching process, and in various situations, job queues are used for delayed processing.

TypeRequireDefaultLimitationDescription
jobIdstring~ 1024 charsJob GRN
scriptIdstring~ 1024 charsScript GRN
argsstring~ 5242880 charsargument
currentRetryCountint0~ 100Current retry count
maxTryCountint31 ~ 100Maximum number of attempts

EzJobResult

Job execution results

TypeRequireDefaultLimitationDescription
statusCodeint~ 1000status code
resultstring~ 5242880 charsResponse Content

EzJobEntry

Register Job

TypeRequireDefaultLimitationDescription
scriptIdstring~ 1024 charsScript GRN
argsstring“{}”~ 131072 charsargument
maxTryCountint3~ 100Maximum number of attempts

EzJobResultBody

Job execution results

TypeRequireDefaultLimitationDescription
tryNumberint1 ~ 10000Number of attempts
statusCodeint~ 1000status code
resultstring~ 5242880 charsResponse Content
tryAtlongNowDatetime of creation (Unix time unit:milliseconds)

Methods

run

Executes jobs in the task queue.

You can receive a push notification when a new job is added to the task queue by configuring the task queue push notification settings. Call this API periodically or trigger a push notification to call this API. Repeat as long as isLastJob returns false.

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 128 charsNamespace name
accessTokenstring~ 128 charsUser Id

Result

TypeDescription
itemEzJobJob
resultEzJobResultBodyJob execution results
isLastJobbool

Error

Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.

TypeBase TypeDescription
ConflictExceptionConflictExceptionJob queue execution conflict. Retry required.

Implementation Example

// 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
// Runs at the SDK level, so there is no need to explicitly call the API

getResult

Get Job execution result

Request

TypeRequireDefaultLimitationDescription
namespaceNamestring~ 128 charsNamespace name
accessTokenstring~ 128 charsUser Id
jobNamestringUUID~ 36 charsJob Name

Result

TypeDescription
itemEzJobResultJob execution result

Implementation Example

    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;
    }
Value change event handling
    var domain = gs2.JobQueue.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Job(
        jobName: "job-0001"
    ).JobResult(
        tryNumber: null
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    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
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::JobQueue::Model::FJobResult> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

Event Handler

OnPushNotification

Notification used when a job is registered in the job queue

NameTypeDescription
namespaceNamestringNamespace name
userIdstringUser Id

Implementation Example

    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

Notification used when a job in the job queue is executed

NameTypeDescription
namespaceNamestringNamespace name
userIdstringUser Id
jobNamestringJob Name

Implementation Example

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