> ## 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.

# PlayFab Inventory API

> 플레이어 인벤토리 관리, 아이템 지급, 화폐 잔액 추적, 스택 조회를 위한 PlayFab Economy v2 Inventory API 개요.

# Inventory

<Info>
  Economy v2는 이제 정식 출시(GA)되었습니다. 지원과 피드백은 [PlayFab Forum](https://community.playfab.com)을 방문하세요.
</Info>

PlayFab Inventory API는 플레이어의 인벤토리와 인벤토리 데이터를 관리하고 저장할 수 있는 기능을 제공합니다. Stacks와 Collections 같은 기능은 플레이어 인벤토리 구조에 유연성을 제공하며, 이 시스템은 모든 게임과 함께 동작할 수 있습니다.

## 플레이어 인벤토리 관리

다음 API는 플레이어 인벤토리에 아이템을 추가, 제거, 업데이트 및 삭제하는 데 사용됩니다. 현재 한도는 10,000 아이템이며, 이를 초과하면 오류가 발생합니다.

### 플레이어 인벤토리 가져오기

#### Game Manager

1. [Game Manager](/services/playfab/live-service-management/gamemanager)에서 `Players`로 이동합니다.
2. 보려는 플레이어를 선택하거나 `New Player`를 만든 다음 `Inventory (V2)`로 이동합니다.

#### API

`GetInventoryItems`를 사용하여 플레이어의 인벤토리를 가져올 수 있습니다. 플레이어는 자신의 인벤토리에만 접근하고 조작할 수 있습니다. Title Entity는 접근하려는 플레이어의 인벤토리를 나타내기 위해 `Entity` 매개변수를 전달할 수 있습니다.

`GetInventoryItems` 요청 예시:

```json theme={null}
{
  "Entity": {
    "Type": "title_player_account",
    "Id": "ABCD12345678"
  },
  "CollectionId": "main_character",
  "Count": 15,
  "ContinuationToken": "abc="
}
```

***

`CollectionId`를 사용하고 플레이어당 여러 인벤토리를 갖는 방법에 대한 자세한 내용은 [여기](/services/playfab/economy-monetization/economy-v2/inventory/collections)를 참조하세요.

##### Continuation Token

검색 응답에서 반환되는 `ContinuationToken` 필드는 여러 결과를 페이지 단위로 순회하기 위해 인벤토리 요청에 전달할 수 있습니다.

### 인벤토리 아이템 추가

`AddInventoryItems` API는 특정 플레이어의 인벤토리에 아이템을 직접 추가하는 데 사용됩니다. `EntityId`, `ItemId`, `Amount` 매개변수를 받아 지정된 아이템을 플레이어의 인벤토리에 추가합니다.

`AddInventoryItems` 요청 예시:

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

### 인벤토리 아이템 차감

`SubtractInventoryItems` API는 플레이어 인벤토리의 아이템 수량을 특정 양만큼 직접 줄이는 데 사용됩니다. `EntityId`, `ItemId`, `Amount` 매개변수를 받아 지정된 양만큼 해당 아이템을 제거합니다. 현재 사용 가능한 수량보다 더 많이 제거하려고 하면 이 API는 오류를 발생시킵니다.

`SubtractInventoryItems` 요청 예시:

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

### 인벤토리 아이템 업데이트

`UpdateInventoryItems` API는 플레이어 인벤토리의 아이템 수량을 특정 값으로 직접 설정하는 데 사용됩니다. `EntityId`, `ItemId`, `Amount` 매개변수를 받아 지정된 양으로 아이템 수량을 설정합니다. 이 API는 수량을 늘리거나 줄이는 데 사용될 수 있으며, 해당 아이템이 존재하지 않을 경우 플레이어 인벤토리에 아이템을 추가할 수도 있습니다.

`UpdateInventoryItems` 요청 예시:

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

### 인벤토리 아이템 삭제

`DeleteInventoryItems` API는 플레이어 인벤토리에서 아이템 스택 전체를 삭제하는 데 사용됩니다.

`DeleteInventoryItems` 요청 예시:

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

### 인벤토리 아이템 구매

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

`PurchaseInventoryItems` API에는 다음과 같은 몇 가지 주요 매개변수가 있습니다.

* `PriceAmounts`는 **개당** 가격을 나타내는 아이템과 수량의 목록입니다. 이러한 가격은 Catalog 또는 지정된 Store에 구성된 값과 일치해야 합니다.
* `StoreId`는 아이템을 구매할 Store에 대한 선택적 매개변수입니다. Store에 대한 자세한 내용은 [여기](/services/playfab/economy-monetization/economy-v2/catalog/stores)를 참조하세요.

`PurchaseInventoryItems` 요청 예시:

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

<Note>
  `PurchaseInventoryItems` API는 가상 화폐 구매에 사용됩니다. 외부 마켓플레이스(Apple App Store, Google Play, Steam, Microsoft Store)를 통한 실물 화폐 구매에는 해당 Redeem API(`RedeemAppleAppStoreInventoryItems`, `RedeemGooglePlayInventoryItems`, `RedeemSteamInventoryItems`, `RedeemMicrosoftStoreInventoryItems` 등)를 사용하세요. 이러한 API는 마켓플레이스에서 구매 영수증을 검증하고 아이템을 플레이어의 인벤토리에 지급합니다. 자세한 내용은 [Marketplace Redemption](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/overview)를 참조하세요.
</Note>

#### 번들

번들이 구매될 때(`PurchaseInventoryItems` 또는 마켓플레이스 Redeem API를 통해), 번들은 **자동으로 플레이어 인벤토리로 언팩**됩니다. 번들의 `ItemReferences`에 참조된 개별 아이템이 직접 지급되며, 번들 자체는 플레이어 인벤토리에 아이템으로 표시되지 않습니다.

예를 들어 Laser Sword 2개와 Laser Gun 2개를 담은 번들을 구매하면 해당 아이템들이 개별적으로 지급됩니다. 번들의 `PriceOptions`에 정의된 가상 화폐 비용은 트랜잭션의 일부로 플레이어 인벤토리에서 차감됩니다.

`AlternateIds`를 통해 마켓플레이스 제품에 연결된 번들도 상환 시 동일한 언팩 동작을 따릅니다. 번들 생성에 관한 자세한 내용은 [Bundles](/services/playfab/economy-monetization/economy-v2/catalog/bundles)를 참조하세요.

### 인벤토리 아이템 이전

`TransferInventoryItems` API는 세 가지 방식으로 사용할 수 있습니다.

1. 플레이어 간 아이템 이전(예: Player A가 Player B에게 사과 3개를 줌)
2. 단일 플레이어의 인벤토리 컬렉션 간 아이템 이전(예: Player A가 자신의 Wizard 캐릭터 인벤토리에서 Warrior 캐릭터의 인벤토리로 Long sword를 옮김)
3. 단일 플레이어의 인벤토리 내에서 아이템 이전을 통해 아이템 스택을 만들거나 제거하거나 조작(예: Player A가 금화 10개 스택을 3개와 7개의 두 스택으로 분리)

`GivingItem`과 `Amount` 매개변수는 이전되는 아이템과 수량을 나타냅니다. `ReceivingItem`은 받는 플레이어 계정의 아이템 목적지를 나타냅니다. `GivingItem`과 `ReceivingItem` 모두 아이템의 `Id`와 `StackId`를 담는 `InventoryItemReference` 객체입니다. 한 엔티티가 아이템을 이전하지 않는 경우를 처리하기 위해 `GivingItem`과 `ReceivingItem`은 비어 있을 수 있습니다. 별도로 지정하지 않으면 플레이어 인벤토리에 추가되거나 이전되는 모든 아이템은 `StackId`가 `default`로 설정됩니다.

#### 1. 플레이어 간 이전

플레이어 간 이전의 경우, 아이템을 이전하는 플레이어와 받는 플레이어를 각각 나타내는 `GivingEntity`와 `ReceivingEntity`를 지정해야 합니다.

플레이어 간 `TransferInventoryItems` 요청 예시:

```json theme={null}
{
    "GivingEntity": {
        "Type": "title_player_account",
        "Id": "DEFG98765432"
    },
    "ReceivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "GivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "ReceivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "Amount": 1
}
```

#### 2. 컬렉션 간 이전

컬렉션 간 이전의 경우, 요청이 이전을 시작하는 인벤토리 컬렉션 ID와 목적지 컬렉션 ID를 나타내는 `GivingCollectionId`와 `ReceivingCollectionId`를 설정해야 합니다.

컬렉션 간 `TransferInventoryItems` 요청 예시:

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

위 요청은 플레이어의 `default` 컬렉션에서 `main_character` 컬렉션으로 해당 아이템 10개를 이전합니다.

컬렉션에 대한 자세한 내용은 [여기](/services/playfab/economy-monetization/economy-v2/inventory/collections)를 참조하세요.

#### 3. 스택 간 이전

스택 간 이전의 경우 요청의 `GivingItem`과 `ReceivingItem`에 대한 `StackId`를 지정해야 합니다.

스택 간 `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
}
```

위 요청은 플레이어의 `default` 스택에서 `MyNewStack` 스택으로 해당 아이템 10개를 이전합니다.

스택에 대한 자세한 내용은 [여기](/services/playfab/economy-monetization/economy-v2/inventory/stacks)를 참조하세요.

### ExecuteInventoryOperations API

`ExecuteInventoryOperations` API를 사용하면 단일 요청으로 여러 인벤토리 작업을 일괄 실행할 수 있습니다. 작업은 지정된 요청 순서대로 수행되며, 어느 하나의 작업이 수행되지 않으면 전체 작업 세트가 취소됩니다.

`ExecuteInventoryOperations`는 작업 목록인 `Operation` 매개변수를 받습니다. `Operation` 목록에는 최대 **50개의 작업**이 있을 수 있지만 동일한 작업 유형이 반복될 수 있습니다(예: 10개의 Add 작업은 유효함). 또한 단일 요청에서 수정/추가할 수 있는 아이템은 **300개**로 제한됩니다. 예를 들어 50개의 아이템이 담긴 번들을 추가하면 수정된 아이템 50개로 계산됩니다. 유효한 작업 유형은 다음과 같습니다.

* Add
* Subtract
* Update
* Purchase
* Transfer\*
* Delete

<Note>
  \*배치 내에서는 단일 컬렉션 이전만 지원됩니다.
</Note>

`ExecuteInventoryOperations` 요청 예시:

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

### 멱등성

Inventory API를 호출할 때 대체 또는 중복 처리 용도로 반복 호출이 발생하는 상황에 사용할 수 있는 `IdempotencyId`를 전달할 수 있습니다. 여러 API 호출이 동일한 `IdempotencyId`를 가지고 있으면 시스템은 그중 하나만 처리되도록 보장합니다.

예를 들어 다음 `PurchaseItem` API 요청은 여러 번 호출될 수 있지만, 모든 요청이 동일한 `IdempotencyId`를 가지므로 해당 플레이어의 인벤토리에서는 단 한 번의 구매만 이루어집니다.

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

`IdempotencyId`는 14일 동안 저장되고 적용되며, 이후에는 해당 ID를 다시 사용할 수 있습니다.

<Note>
  서로 다른 요청 유형에 동일한 `IdempotencyId`를 사용하면 충돌이 발생하고 오류가 발생합니다.
</Note>

### ETag 및 동시성 제어

Inventory 쓰기 API는 ETag와 HTTP 헤더를 통해 낙관적 동시성 제어를 지원합니다. 자세한 내용은 [Inventory ETags](/services/playfab/economy-monetization/economy-v2/inventory/etags)를 참조하세요.

### 표시 속성

표시 속성(Display Properties)은 플레이어 인벤토리의 아이템과 아이템 스택에 추가할 수 있는 사용자 지정 아이템 속성입니다.

이 속성은 `AddInventoryItems`, `PurchaseInventoryItems`, `TransferInventoryItems`, `UpdateInventoryItems` 작업으로 추가할 수 있습니다.

#### 새 스택/아이템에 속성 추가

`AddInventoryItems`, `PurchaseInventoryItems`, `TransferInventoryItems` API의 경우, 표시 속성은 **오직** 새 스택이 생성될 때만 추가할 수 있습니다. 새 아이템에 대한 표시 속성을 설정하려면 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"
        }
    }
}
```

스택에 대한 자세한 내용은 [여기](/services/playfab/economy-monetization/economy-v2/inventory/stacks)를 참조하세요.

#### 기존 스택/아이템에 대한 속성 업데이트

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

`DisplayProperties`가 포함된 `UpdateInventoryItems` 요청 예시:

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


## Related topics

- [Inventory ETags](/ko/services/playfab/economy-monetization/economy-v2/inventory/etags.md)
- [PFInventoryInventoryOperation](/ko/services/playfab/api-references/c/pfinventorytypes/structs/pfinventoryinventoryoperation.md)
- [PFInventoryInventoryItem](/ko/services/playfab/api-references/c/pfinventorytypes/structs/pfinventoryinventoryitem.md)
- [Inventory Stacks](/ko/services/playfab/economy-monetization/economy-v2/inventory/stacks.md)
- [PFInventoryInventoryItemReference](/ko/services/playfab/api-references/c/pfinventorytypes/structs/pfinventoryinventoryitemreference.md)