> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Inventory Stacks

> 플레이어의 인벤토리에서 고유한 데이터, 수량 및 만료를 가진 동일한 아이템을 그룹화하기 위한 PlayFab Economy v2 Inventory Stacks를 이해합니다.

# Stacks

<Info>
  Economy v2는 이제 정식으로 사용할 수 있습니다(GA). 지원 및 피드백은 [PlayFab Forum](https://community.playfab.com)을 방문하세요.
</Info>

Economy V2 Inventory 서비스는 인벤토리 요구 사항에 더 큰 유연성과 지원을 추가할 수 있는 스택의 개념을 도입합니다. 스택을 사용하면 동일한 아이템의 별개의 서로 다른 인스턴스가 동일한 인벤토리 내에 존재할 수 있습니다. 이 기능을 통해 게임 내 조직 시나리오, 다양한 아이템 속성 설정 기능 등이 가능합니다!

동일한 `Id`의 아이템은 각각의 수량이 있고 `StackId`로 구분되는 아이템 스택으로 저장할 수 있습니다. 지정되지 않은 경우 인벤토리 작업은 일반적으로 StackId가 `default`인 기본 스택을 사용합니다. 기본 스택은 삭제할 수 있습니다. 다음에 StackId 없이(또는 기본 StackId를 사용하여) 추가/이전이 발생하면 기본 스택이 다시 만들어집니다.

## 인벤토리 및 스택 관리

다음은 [Inventory APIs](/services/playfab/economy-monetization/economy-v2/inventory)와 스택과의 상호 작용에 대한 자세한 분석입니다.

### Add Inventory Items

`AddInventoryItems` API에서 `Item` 매개 변수에 `StackId`를 정의할 수 있습니다. 이 매개 변수는 증가되고 있는 스택 또는 만들어지는 새 스택의 ID를 정의합니다.

`StackId`가 있는 `AddInventoryItems` 요청 예:

```json theme={null}
{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "NewStack"
    },
    "Amount": 5,
}
```

위의 요청은 수량이 5이고 StackId가 `NewStack`인 새 아이템 스택을 만들거나, 이미 존재하는 경우 기존 `NewStack`에 5개를 추가합니다.

### Subtract Inventory Items

`SubtractInventoryItems` API에서 StackId는 감산되는 스택을 정의하는 데 사용됩니다. 또한 감산된 수량으로 인해 스택 수량이 0이 되는 경우 스택을 삭제하는 `DeleteEmptyStacks` 부울을 설정할 수 있습니다.

현재 스택 수량보다 많이 스택에서 감산하려고 하면 오류가 발생합니다.

StackId가 있는 `SubtractInventoryItems` 요청 예:

```json theme={null}
{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "NewStack"
    },
    "Amount": 5,
    "DeleteEmptyStacks": true,
}
```

위의 요청은 ID가 `NewStack`인 스택에서 5개를 감산하고 스택 수량이 정확히 5인 경우 스택을 삭제합니다.

### Update Inventory Items

`UpdateInventoryItems` API에서 `Item` 매개 변수에 `StackId`를 정의할 수 있습니다. 이 매개 변수는 업데이트되고 있는 스택 또는 만들어지는 새 스택의 ID를 정의합니다.

`UpdateInventoryItems` 요청 예:

```json theme={null}
{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "NewStack",
        "Amount": 5
    }
}
```

위의 요청은 수량이 5이고 StackId가 `NewStack`인 새 아이템 스택을 만들거나, 이미 존재하는 경우 `NewStack`의 수량을 5로 설정합니다.

### Delete Inventory Items

`DeleteInventoryItems` API는 플레이어의 인벤토리에서 아이템 스택 전체를 삭제하는 데 사용됩니다. 삭제할 특정 아이템 스택을 정의하기 위해 `StackId`를 제공할 수 있습니다.

`DeleteInventoryItems` 요청 예:

```json theme={null}
{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "NewStack"
    },
}
```

### Purchase Inventory Items

`PurchaseInventoryItems` API는 아이템의 카탈로그 정의 가격을 사용하며, 플레이어의 인벤토리에서 비용을 차감하고 원하는 수량의 아이템으로 교환합니다. 구매하려는 `Item`과 구매하려는 아이템의 `Amount`를 지정해야 합니다.

스택으로 구매할 때 관련된 몇 가지 매개 변수가 있습니다.

* `PriceAmounts`의 경우 각 가격 아이템(즉, 소비되는 아이템)에 대해 소비된 아이템이 감산될 스택을 정의하기 위해 선택적 `StackId`를 정의할 수 있습니다.
* `Item` 개체의 경우 받는 아이템이 배치될 스택을 나타내는 선택적 `StackId`를 정의할 수 있습니다.
* 감산된 수량으로 인해 스택 수량이 0이 되는 경우 스택을 삭제하는 `DeleteEmptyStacks` 부울을 설정할 수 있습니다.

<Note>
  아이템 구매에 대한 자세한 내용은 [PurchaseInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/purchase-inventory-items)를 참조하세요.
</Note>

스택이 있는 `PurchaseInventoryItems` 요청 예:

```json theme={null}
{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "LaserSword",
        "StackId": "MyLaserSwordStack"
    },
    "Amount": 10,
    "PriceAmounts": [
        {
            "ItemId": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
            "Amount": 5,
            "StackId": "MyNewStack",
        }
    ],
    "DeleteEmptyStacks": true,
}
```

### Transfer Inventory Items

스택과 함께 `TransferInventoryItems` API를 사용하는 경우 몇 가지 관련 매개 변수가 있습니다.

* `GivingItem` 개체에서 주어진 아이템이 가져올 스택을 나타내는 선택적 `StackId`를 정의할 수 있습니다.
* `ReceivingItem` 개체에서 받는 아이템이 배치될 스택을 나타내는 선택적 `StackId`를 정의할 수 있습니다.
* `GivingItem` 수량으로 인해 스택 수량이 0이 되는 경우 스택을 삭제하는 `DeleteEmptyStacks` 부울을 설정할 수 있습니다.

스택이 있는 `TransferInventoryItems` 요청 예:

```json theme={null}
{
    "GivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "ReceivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "GivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "default",
    },
    "ReceivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "MyNewStack",
    },
    "Amount": 10,
    "DeleteEmptyStacks": true
}
```

### ExecuteInventoryOperations API

`ExecuteInventoryOperations` API의 `Operation` 개체에서 `StackId`와 `DeleteEmptyStacks` 매개 변수를 사용할 수 있습니다. 이러한 매개 변수를 사용하면 스택을 사용하여 여러 인벤토리 작업을 일괄 처리할 수 있습니다.

스택이 있는 `ExecuteInventoryOperations` 요청 예:

```json theme={null}
"Entity": {
    "Type": "title_player_account",
    "Id": "ABCD12345678"
 },
"Operations": [
    {
        "Update": {
            "Item": {
                "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
                "StackId": "default",
                "Amount": 10
            }
        }
    },
    {
        "Subtract": {
            "Item": {
                "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
                "StackId": "MyNewStack"
            },
            "Amount": 5
        }
    }
]
```

### DisplayProperties와 NewStackValues로 사용자 지정 속성 추가

`DisplayProperties` 매개 변수를 사용하여 인벤토리 아이템에 사용자 지정 아이템 속성을 설정할 수 있습니다. 속성 설정은 `AddInventoryItems`, `PurchaseInventoryItems`, `TransferInventoryItems` API에서 수행할 수 있지만, **새 스택이 만들어질 때만** 가능합니다. 새 아이템에 대해 Display Properties를 설정하려면 API 요청에 `NewStackValues` 매개 변수를 설정해야 합니다.

`NewStackValues`가 있는 `AddInventoryItems` 요청 예:

```json theme={null}
{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "20a645ce-a3bf-4fcb-8e67-36aa7bf0331d",
        "StackId": "NewStack"
    },
    "Amount": 15,
    "NewStackValues": {
        "DisplayProperties": {
            "DifficultyRating":5,
            "IsMagic": true,
            "Rarity": "Legendary"
        }
    }
}
```

기존 아이템의 Display Properties를 업데이트하려면 `UpdateInventoryItems` API를 사용하여 속성을 직접 수정할 수 있습니다.


## Related topics

- [PFInventoryTransferInventoryItemsOperation](/ko/services/playfab/api-references/c/pfinventorytypes/structs/pfinventorytransferinventoryitemsoperation.md)
- [PlayFab Inventory API](/ko/services/playfab/economy-monetization/economy-v2/inventory/index.md)
- [PFInventoryInventoryItemReference](/ko/services/playfab/api-references/c/pfinventorytypes/structs/pfinventoryinventoryitemreference.md)
- [PFInventoryPurchaseInventoryItemsOperation](/ko/services/playfab/api-references/c/pfinventorytypes/structs/pfinventorypurchaseinventoryitemsoperation.md)
- [PFInventoryInventoryItem](/ko/services/playfab/api-references/c/pfinventorytypes/structs/pfinventoryinventoryitem.md)