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

# GS2-Dictionary トランザクションアクション

検証/消費/入手の各トランザクションアクションの仕様




## アクションの組み合わせと同時実行

すべてのサービスに共通する前提は [トランザクションアクションの組み合わせ]() にまとめています。先にそちらを読んでください。この節の残りは GS2-Dictionary 固有の内容です。

GS2-Dictionary のトランザクションアクションは、ネームスペースとユーザーの組で決まる 1 人のユーザーの図鑑、つまり取得済みエントリーの一覧を対象にします。エントリーの追加・削除はこの一覧をまるごと書き換える形で反映されます。

操作 | 同じ行を重ねたとき | 入れ子越し | 別の対象になる境界 | 直列実行モード有効時
--- | --- | --- | --- | ---
エントリーの追加<br>`AddEntriesByUserId` | 統合され、エントリー名が重複を除いて結合される | 失敗する | ネームスペース・ユーザー | 成立する。内側から届く追加は、外側がすでに書き込んだ状態の上に適用される
エントリーの削除<br>`DeleteEntriesByUserId` | 統合され、エントリー名が重複を除いて結合される | 失敗する | ネームスペース・ユーザー | 成立する。内側から届く削除は、外側がすでに書き込んだ状態の上に適用される
エントリーの検証<br>`VerifyEntryByUserId` | まったく同じ検証は 1 件にまとめられる | 読み取りだけなので衝突しない | エントリー・検証タイプ | 変わらない。読み取りだけなのでもともと衝突しない

追加と削除は行が違い、境界が同じです。1 つの図鑑に対する追加と削除を同じトランザクションで行うことはできません。トランザクションを分けてください。**直列実行モード（`enableSequentialExecution` または `TransactionSettingV2`）を有効にすると、この制約はなくなります。アクションが 1 件ずつ実行され、後から実行される方は先に実行されたアクションが書き込んだ状態を読んだうえで実行されるため、同じ図鑑に対する追加と削除を 1 つのトランザクションに入れられるようになります。**

追加は重複を取り除いて統合されるので、同じエントリーが複数のアクションに現れてもかまいません。100 件の上限も、重複を除いたあとの数で判定されます。

追加と削除のどちらかが結果的に図鑑を書き換えなかった場合、たとえば追加対象をすべて取得済みだったり、削除対象を 1 件も持っていなかったりした場合には、同居していてもトランザクションが成功することがあります。実行時点のユーザーの取得状況に左右されるため、これを前提に設計しないでください。

検証アクションはトランザクション開始時点の図鑑を見ます。同じトランザクションで追加したエントリーを `have` で検証したり、削除したエントリーを `havent` で検証したりすることはできません。

### 入れ子になったトランザクションに注意

並べて書けば 1 件に統合されたはずの追加どうしでも、片方が内側から届く場合はトランザクションが失敗します。同じエントリーを両方の経路から追加した場合も同様です。直列実行モードを有効にすると、この失敗は起こらなくなります。内側のトランザクションは外側と同じ直列実行の区間で実行されるようになるため、内側の追加は外側がすでに書き込んだ状態の上に適用されます。

### 制限を回避したい場合

エントリーの追加は入手アクション、削除は消費アクションです。内側から届いた追加との衝突は `acquireActionUseJobQueue` を有効にすれば解消できますが、追加と削除の同居は `enableAtomicCommit` を無効にしないと解消しません。

### 同時実行とリトライ

同一ユーザーの図鑑を複数のリクエストが同時に更新した場合、後から確定した側がコンフリクト (409) になります。図鑑の内容に問題があるわけではないので、リトライすれば成功します。

同一ユーザーに対して図鑑を更新するリクエストを短時間に並行して発行するほど発生しやすくなります。追加と削除を 1 つのトランザクションにまとめる、同一ユーザーへの更新は直列化する、といった対策が有効です。

---


## Verify Action

検証アクション

### Gs2Dictionary:VerifyEntryByUserId

ユーザーIDを指定してエントリーを検証<br>

指定されたユーザーが特定のエントリーを収集済みか未収集かを検証します。<br>
検証タイプで条件を指定します：`have` はユーザーがエントリーを保有していることを確認し、`havent` は保有していないことを確認します。<br>
検証に失敗した場合、エラーが返されます。

**数量指定可能なアクション：いいえ**

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| userId | string |  | ✓|  |  ~ 128文字 | ユーザーID<br>`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| entryModelName | string |  | ✓|  |  ~ 128文字 | エントリーモデル名<br>エントリーモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| verifyType | 文字列列挙型<br>enum {<br>"havent",<br>"have"<br>}<br> |  | ✓|  |  | 検証の種類havent: 指定したエントリーを保有していないこと / have: 指定したエントリーを保有していること /  |
| timeOffsetToken | string |  | |  |  ~ 1024文字 | タイムオフセットトークン |




**JSON**
```json
{
    "action": "Gs2Dictionary:VerifyEntryByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "entryModelName": "[string]エントリーモデル名",
        "verifyType": "[string]検証の種類",
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2Dictionary:VerifyEntryByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  entryModelName: "[string]エントリーモデル名"
  verifyType: "[string]検証の種類"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("dictionary").verify.verify_entry_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    entryModelName="[string]エントリーモデル名",
    verifyType="[string]検証の種類",
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---

## Consume Action

消費アクション

### Gs2Dictionary:DeleteEntriesByUserId

ユーザーIDを指定してエントリーを削除<br>

エントリーモデル名のリストを指定して、指定されたユーザーの図鑑から特定のエントリーを削除します。<br>
バッチ操作として複数のエントリーを一度に削除できます。<br>
返されるリストには、実際に削除されたエントリーが含まれます。

**数量指定可能なアクション：いいえ**

**反転可能なアクション：はい**

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| userId | string |  | ✓|  |  ~ 128文字 | ユーザーID<br>`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| entryModelNames | List&lt;string&gt; |  | | [] | 0 ~ 100 items | エントリーモデル名のリスト |
| timeOffsetToken | string |  | |  |  ~ 1024文字 | タイムオフセットトークン |




**JSON**
```json
{
    "action": "Gs2Dictionary:DeleteEntriesByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "entryModelNames": [
            "[string]エントリーモデル名"
        ],
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2Dictionary:DeleteEntriesByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  entryModelNames: 
    - "[string]エントリーモデル名"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("dictionary").consume.delete_entries_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    entryModelNames={
        "[string]エントリーモデル名"
    },
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---

## Acquire Action

入手アクション

### Gs2Dictionary:AddEntriesByUserId

ユーザーIDを指定してエントリーを登録<br>

指定されたユーザーの図鑑に1つ以上のエントリーを登録します。<br>
バッチ操作として複数のエントリーモデル名を一度に指定できます。<br>
既に登録済みのエントリーはエラーにならず、スキップされます。<br>
返されるリストには、新たに追加されたエントリーのみが含まれます。

**数量指定可能なアクション：いいえ**

**反転可能なアクション：はい**

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| userId | string |  | ✓|  |  ~ 128文字 | ユーザーID<br>`#{userId}` と設定することでログイン中のユーザーIDに置換されます。 |
| entryModelNames | List&lt;string&gt; |  | | [] | 0 ~ 100 items | エントリーモデル名のリスト |
| timeOffsetToken | string |  | |  |  ~ 1024文字 | タイムオフセットトークン |




**JSON**
```json
{
    "action": "Gs2Dictionary:AddEntriesByUserId",
    "request": {
        "namespaceName": "[string]ネームスペース名",
        "userId": "[string]ユーザーID",
        "entryModelNames": [
            "[string]エントリーモデル名"
        ],
        "timeOffsetToken": "[string]タイムオフセットトークン"
    }
}
```

**YAML**
```yaml

action: Gs2Dictionary:AddEntriesByUserId
request:
  namespaceName: "[string]ネームスペース名"
  userId: "[string]ユーザーID"
  entryModelNames: 
    - "[string]エントリーモデル名"
  timeOffsetToken: "[string]タイムオフセットトークン"
```

**GS2-Script**
```lua

transaction.service("dictionary").acquire.add_entries_by_user_id({
    namespaceName="[string]ネームスペース名",
    userId="[string]ユーザーID",
    entryModelNames={
        "[string]エントリーモデル名"
    },
    timeOffsetToken="[string]タイムオフセットトークン",
})
```


---