> For the complete documentation index, see [llms.txt](/llms.txt)

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

ゲームエンジン向け GS2-JobQueue SDK の モデルの仕様 と API のリファレンス



## モデル

### EzJob

ジョブ<br>

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

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

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| jobId | string |  | ※ |  |  ~ 1024文字 | ジョブGRN<br>※ サーバーが自動で設定 |
| scriptId | string |  | ✓ |  |  ~ 1024文字 | スクリプトGRN |
| args | string |  | ✓ |  |  ~ 5242880文字 | 引数<br>ジョブの実行時にスクリプトに渡すJSON形式のリクエストパラメータです。アクションタイプや対象リソースなどの具体的な操作内容を含みます。最大5MBです。 |
| currentRetryCount | int |  |  | 0 | 0 ~ 100 | 現在のリトライ回数<br>失敗後にこのジョブがリトライされた回数です。リトライ可能なエラーで実行が終了するたびにインクリメントされます。このカウントがmaxTryCountに達すると、ジョブは恒久的な失敗としてマークされます。 |
| maxTryCount | int |  |  | 3 | 1 ~ 100 | 最大試行回数<br>初回の試行とリトライを含めて、このジョブを実行できる最大回数です。すべての試行が失敗した場合、ジョブは放棄されます。デフォルトは3、最大100です。 |

**関連するメソッド:**
run - プレイヤーのジョブキューにある次のジョブを実行する


---

### EzJobResult

ジョブ実行結果（詳細）<br>

単一のジョブ実行試行の結果を記録します。各試行ごとに個別のJobResultが作成されるため、複数回リトライされたジョブには複数の結果が存在します。statusCodeはジョブが成功したか失敗したかを示します。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| statusCode | int |  | ✓ |  | 0 ~ 1000 | ステータスコード<br>スクリプト実行から返されたHTTPステータスコードです。2xxコードは成功を示し、その他のコードは失敗を示します。リトライ可能なエラーの場合、maxTryCountに達していなければ自動リトライが行われることがあります。 |
| result | string |  | ✓ |  |  ~ 5242880文字 | レスポンスの内容<br>スクリプト実行から返されたJSON形式のレスポンスボディです。成功時には結果データを、失敗時にはエラーの詳細を含みます。最大5MBです。 |

**関連するメソッド:**
getResult - 完了したジョブの実行結果を取得する


---

### EzJobEntry

登録ジョブ<br>

ジョブキューに新しいジョブを登録するためのパラメータを表します。実行するスクリプト、JSON引数、最大リトライ回数を含みます。ジョブをキューにプッシュする際の入力として使用されます。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| scriptId | string |  | ✓ |  |  ~ 1024文字 | スクリプトGRN |
| args | string |  |  | "{}" |  ~ 131072文字 | 引数<br>ジョブの実行時にスクリプトに渡すJSON形式のリクエストパラメータです。デフォルトは空のJSONオブジェクト "{}" です。最大128KBです。 |
| maxTryCount | int |  |  | 3 | 0 ~ 100 | 最大試行回数<br>初回の試行とリトライを含めて、ジョブを実行できる最大回数です。デフォルトは3、最大100です。 |


---

### EzJobResultBody

ジョブの実行結果<br>

試行番号、ステータスコード、レスポンス内容、実行タイムスタンプを含むジョブ実行結果の軽量な表現です。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| tryNumber | int |  | ✓ |  | 1 ~ 10000 | 試行回数<br>この実行結果の連番試行番号で、1から始まります。どのリトライ試行がこの結果を生成したかを識別するために使用されます。 |
| statusCode | int |  | ✓ |  | 0 ~ 1000 | ステータスコード<br>スクリプト実行から返されたHTTPステータスコードです。2xxコードは成功を示し、その他のコードは失敗を示します。リトライ可能なエラーの場合、maxTryCountに達していなければ自動リトライが行われることがあります。 |
| result | string |  | ✓ |  |  ~ 5242880文字 | レスポンスの内容<br>スクリプト実行から返されたJSON形式のレスポンスボディです。成功時には結果データを、失敗時にはエラーの詳細を含みます。最大5MBです。 |
| tryAt | long |  | ※ | 現在時刻 |  | 作成日時<br>UNIX 時間・ミリ秒<br>※ サーバーが自動で設定 |

**関連するメソッド:**
run - プレイヤーのジョブキューにある次のジョブを実行する


---

## メソッド

### run

プレイヤーのジョブキューにある次のジョブを実行する<br>

GS2 では、すぐに完了しなくてもよい処理を「ジョブキュー」で遅延実行します。たとえば、キャラクターを入手したとき、所持品への追加は即座に行いますが、図鑑への登録はジョブキューを通じて後から処理できます。<br>
この仕組みにより、関連サービスが一時的に停止していてもゲームを継続でき、キューに溜まったジョブはサービス復旧後にリトライされて正しい状態になります。<br>

このAPIを呼び出すと、プレイヤーのキューにある次のジョブを1つ実行し、その結果を返します。<br>
レスポンスに含まれる `isLastJob` フラグが `false` の場合はまだ未処理のジョブが残っているため、`true` になるまで繰り返し呼び出してください。<br>

ネームスペースにプッシュ通知を設定しておけば、新しいジョブが追加されたタイミングで通知を受け取れるため、ポーリングせずに通知をトリガーにしてこのAPIを呼び出すこともできます。<br>

ネームスペースで `enableAutoRun` を有効にしている場合は、ジョブはサーバー側で自動実行されるため、このAPIを呼び出す必要はありません。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzJob](#ezjob) | ジョブ|
| result | [EzJobResultBody](#ezjobresultbody) | ジョブの実行結果の内容|
| isLastJob | bool | |

#### Error

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

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

#### 実装例




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

```

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

```

**Unreal Engine 5**
```cpp
// SDKレベルで実行されるため明示的にAPIを呼び出す必要はありません

```


---

### getResult

完了したジョブの実行結果を取得する<br>

ジョブ名を指定して、そのジョブの実行結果を取得します。<br>
結果には、成功・失敗を示すステータスコードと、ジョブが返したレスポンスの内容が含まれます。<br>

図鑑への登録や報酬の配布など、遅延処理が正しく完了したかどうかを確認したい場合に使います。<br>
ジョブが複数回リトライされた場合は、試行回数を指定して特定の試行の結果を確認することもできます。<br>

※ ジョブの実行結果は実行後一定期間のみ保持され、自動的に削除される場合があります。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓|  |  | GameSession |
| jobName | string |  | ✓| UUID |  ~ 36文字 | ジョブの名前<br>ジョブの一意な名前を保持します。<br>名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各ジョブを識別するために使用されます。 |
| tryNumber | int |  | |  | 0 ~ 10000 | 試行回数 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzJobResult](#ezjobresult) | ジョブの実行結果|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.JobQueue.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Job(
        jobName: "job-0001"
    ).JobResult(
        tryNumber: null
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    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;

```

**Unreal Engine 5**
```cpp
    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;
    }

```


##### 値の変更イベントハンドリング




**Unity (UniTask)**
```csharp
    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);

```

**Unity (Vanilla)**
```cs
    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);

```

**Unreal Engine 5**
```cpp
    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);

```


{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}

---

## イベントハンドラ

### OnPushNotification

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

 | 名前 | 型 | 説明 |
| --- | --- | --- |
| namespaceName | string |ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| userId | string |ユーザーID|

#### 実装例





**Unity (UniTask)**
```csharp

    gs2.JobQueue.OnPushNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var userId = notification.UserId;
    };
```

**Unity (Vanilla)**
```cs

    gs2.JobQueue.OnPushNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var userId = notification.UserId;
    };
```

**Unreal Engine 5**
```cpp

    Gs2->JobQueue->OnPushNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto UserId = Notification->UserIdValue;
    });
```


---

### OnRunNotification

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

 | 名前 | 型 | 説明 |
| --- | --- | --- |
| namespaceName | string |ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| userId | string |ユーザーID|
| jobName | string |ジョブの名前<br>ジョブの一意な名前を保持します。<br>名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各ジョブを識別するために使用されます。|

#### 実装例





**Unity (UniTask)**
```csharp

    gs2.JobQueue.OnRunNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var userId = notification.UserId;
        var jobName = notification.JobName;
    };
```

**Unity (Vanilla)**
```cs

    gs2.JobQueue.OnRunNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var userId = notification.UserId;
        var jobName = notification.JobName;
    };
```

**Unreal Engine 5**
```cpp

    Gs2->JobQueue->OnRunNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto UserId = Notification->UserIdValue;
        const auto JobName = Notification->JobNameValue;
    });
```


---