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.

	Type	Require	Default	Limitation	Description
jobId	string	✓		~ 1024 chars	Job GRN
scriptId	string	✓		~ 1024 chars	Script GRN
args	string	✓		~ 5242880 chars	argument
currentRetryCount	int	✓	0	~ 100	Current retry count
maxTryCount	int	✓	3	1 ~ 100	Maximum number of attempts

EzJobResult

Job execution results

	Type	Require	Default	Limitation	Description
statusCode	int	✓		~ 1000	status code
result	string	✓		~ 5242880 chars	Response Content

EzJobEntry

	Type	Require	Default	Limitation	Description
scriptId	string	✓		~ 1024 chars	Script GRN
args	string	✓	“{}”	~ 131072 chars	argument
maxTryCount	int	✓	3	~ 100	Maximum number of attempts

EzJobResultBody

Job execution results

	Type	Require	Default	Limitation	Description
tryNumber	int	✓		1 ~ 10000	Number of attempts
statusCode	int	✓		~ 1000	status code
result	string	✓		~ 5242880 chars	Response Content
tryAt	long	✓	Now		Datetime 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

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
accessToken	string	✓		~ 128 chars	User Id

Result

	Type	Description
item	EzJob	Job
result	EzJobResultBody	Job execution results
isLastJob	bool

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.

Type	Base Type	Description
ConflictException	ConflictException	Job 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

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
accessToken	string	✓		~ 128 chars	User Id
jobName	string	✓	UUID	~ 36 chars	Job Name

Result

	Type	Description
item	EzJobResult	Job 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);

Warning

This event is called when the value in the local cache that the SDK has is changed.

The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.

Event Handler

OnPushNotification

Notification used when a job is registered in the job queue

Name	Type	Description
namespaceName	string	Namespace name
userId	string	User 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

Name	Type	Description
namespaceName	string	Namespace name
userId	string	User Id
jobName	string	Job 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;
    });