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

# GS2-JobQueue

非同期ジョブキュー




GS2-JobQueue はゲームサーバー上で実行する処理を非同期に積み上げるためのジョブキュー機能を提供します。

ゲームの処理には、すぐに結果を返す必要のないものや、サーバー側で時間をかけて段階的に進めたいものがあります。
そのような処理を「ジョブ」としてキューに登録しておき、後からプレイヤーがアクセスしたタイミングや明示的なAPI呼び出しによって実行することができます。

## 主な用途

- GS2-Script を非同期に実行するための実行基盤
- 長時間処理を細かいステップに分割し、ステップごとにジョブとして登録して順次処理する
- ログイン中に発生したリワード配布などをまとめてサーバー側でトランザクション発行・実行
- 他マイクロサービスの完了通知ハンドラとして、後続処理を非同期に行う

```mermaid
graph LR
  Producer["ジョブ登録元<br/>(他のマイクロサービス / GS2-Script)"] --> Queue["GS2-JobQueue"]
  Queue --> Run["プレイヤーが Run を実行<br/>または 自動実行"]
  Run --> Script["GS2-Script"]
  Script -- 成功 --> Result["JobResult として記録"]
  Script -- 失敗 --> Retry{"最大試行回数<br/>に到達?"}
  Retry -- No --> Queue
  Retry -- Yes --> DeadLetter["DeadLetterJob として保管"]
```

## 自動実行モード

ネームスペースの設定で `enableAutoRun` を有効にすると、各マイクロサービスのAPI処理の最後にユーザーのキューに積まれているジョブを自動的に実行します。
プレイヤーがアプリを操作するだけで、サーバー側に積まれたジョブが順次消化されていきます。

`enableAutoRun` を無効にする場合は、クライアントから明示的に `Run` API を呼び出してジョブを実行する必要があります。

## ジョブ結果

ジョブの実行結果は試行回数(`tryNumber`)ごとに `JobResult` として記録されます。
`JobResult` には GS2-Script の終了コード・実行ログ・結果ペイロードなどが含まれ、後から実行履歴を確認することができます。

## 通知設定

ネームスペースの設定で `runNotification` ・ `pushNotification` を構成しておくと、ジョブが実行されたとき、または新規にジョブがキューに積まれたときに GS2-Gateway を経由してクライアントへ通知できます。
この通知をフックに、クライアント側で残り情報を再取得するといった連携が可能です。

## トランザクションアクション

GS2-JobQueue は他のマイクロサービスから完了通知の受け先として呼び出されることが多く、トランザクションアクションとしてジョブ登録を提供しています。

- 入手アクション: ジョブをユーザーのキューに登録

たとえば GS2-Mission の完了報酬として GS2-JobQueue にジョブを積み、後でまとめて GS2-Script を実行するといった構成が可能です。

## マスターデータ管理

GS2-JobQueue はマスターデータを持ちません。
振る舞いはネームスペースの設定でのみ制御します。

## 実装例

### 自分のキューに積まれているジョブを実行

`enableAutoRun` を無効にした場合や、明示的にジョブの消化を進めたい場合に呼び出します。
`Run` を呼び出すと、ジョブを1件取り出して GS2-Script を実行し、その結果を返します。
`IsLastJob` が `true` であれば、これ以上消化すべきジョブが残っていないことを示します。



**Unity**
```csharp

    var domain = gs2.JobQueue.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.RunAsync(
    );
    var isLastJob = domain.IsLastJob;
    var needRetry = result.NeedRetry;
```
**Unreal Engine**
```cpp

    const auto Domain = Gs2->JobQueue->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto Future = Domain->Run(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError()) return false;
    const auto IsLastJob = Domain->IsLastJob;
    const auto NeedRetry = Future->GetTask().Result()->NeedRetry;
```


### ジョブの実行結果を取得

特定のジョブの特定の試行回数の実行結果を取得します。



**Unity**
```csharp

    var item = await gs2.JobQueue.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Job(
        jobName: "job-0001"
    ).JobResult(
        tryNumber: 1
    ).ModelAsync();
```
**Unreal Engine**
```cpp

    const auto Domain = Gs2->JobQueue->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Job(
        "job-0001" // jobName
    )->JobResult(
        1 // tryNumber
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError()) return false;
    const auto Result = Future->GetTask().Result();
```


### ジョブの状態を取得

キューに積まれているジョブの最新状態を取得します。
ジョブの現在の試行回数や登録された GS2-Script の情報などを確認できます。



**Unity**
```csharp

    var item = await gs2.JobQueue.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Job(
        jobName: "job-0001"
    ).ModelAsync();
```
**Unreal Engine**
```cpp

    const auto Future = Gs2->JobQueue->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Job(
        "job-0001" // jobName
    )->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError()) return false;
    const auto Result = Future->GetTask().Result();
```


## 詳細なリファレンス

[GS2-JobQueue API リファレンス](../../api_reference/job_queue)