Inventory

Economy v2는 이제 정식 출시(GA)되었습니다. 지원과 피드백은 PlayFab Forum을 방문하세요.

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

플레이어 인벤토리 관리

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

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

Game Manager

Game Manager에서 Players로 이동합니다.
보려는 플레이어를 선택하거나 New Player를 만든 다음 Inventory (V2)로 이동합니다.

API

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

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

CollectionId를 사용하고 플레이어당 여러 인벤토리를 갖는 방법에 대한 자세한 내용은 여기를 참조하세요.

Continuation Token

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

인벤토리 아이템 추가

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

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

인벤토리 아이템 차감

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

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

인벤토리 아이템 업데이트

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

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

인벤토리 아이템 삭제

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

{
   "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에 대한 자세한 내용은 여기를 참조하세요.

PurchaseInventoryItems 요청 예시:

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

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

번들

번들이 구매될 때(PurchaseInventoryItems 또는 마켓플레이스 Redeem API를 통해), 번들은 자동으로 플레이어 인벤토리로 언팩됩니다. 번들의 ItemReferences에 참조된 개별 아이템이 직접 지급되며, 번들 자체는 플레이어 인벤토리에 아이템으로 표시되지 않습니다. 예를 들어 Laser Sword 2개와 Laser Gun 2개를 담은 번들을 구매하면 해당 아이템들이 개별적으로 지급됩니다. 번들의 PriceOptions에 정의된 가상 화폐 비용은 트랜잭션의 일부로 플레이어 인벤토리에서 차감됩니다. AlternateIds를 통해 마켓플레이스 제품에 연결된 번들도 상환 시 동일한 언팩 동작을 따릅니다. 번들 생성에 관한 자세한 내용은 Bundles를 참조하세요.

인벤토리 아이템 이전

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

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

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

1. 플레이어 간 이전

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

{
    "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 요청 예시:

{
    "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개를 이전합니다. 컬렉션에 대한 자세한 내용은 여기를 참조하세요.

3. 스택 간 이전

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

{
    "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개를 이전합니다. 스택에 대한 자세한 내용은 여기를 참조하세요.

ExecuteInventoryOperations API

ExecuteInventoryOperations API를 사용하면 단일 요청으로 여러 인벤토리 작업을 일괄 실행할 수 있습니다. 작업은 지정된 요청 순서대로 수행되며, 어느 하나의 작업이 수행되지 않으면 전체 작업 세트가 취소됩니다. ExecuteInventoryOperations는 작업 목록인 Operation 매개변수를 받습니다. Operation 목록에는 최대 50개의 작업이 있을 수 있지만 동일한 작업 유형이 반복될 수 있습니다(예: 10개의 Add 작업은 유효함). 또한 단일 요청에서 수정/추가할 수 있는 아이템은 300개로 제한됩니다. 예를 들어 50개의 아이템이 담긴 번들을 추가하면 수정된 아이템 50개로 계산됩니다. 유효한 작업 유형은 다음과 같습니다.

Add
Subtract
Update
Purchase
Transfer*
Delete

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

ExecuteInventoryOperations 요청 예시:

{
    "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를 가지므로 해당 플레이어의 인벤토리에서는 단 한 번의 구매만 이루어집니다.

{
    "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를 다시 사용할 수 있습니다.

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

ETag 및 동시성 제어

Inventory 쓰기 API는 ETag와 HTTP 헤더를 통해 낙관적 동시성 제어를 지원합니다. 자세한 내용은 Inventory ETags를 참조하세요.

표시 속성

표시 속성(Display Properties)은 플레이어 인벤토리의 아이템과 아이템 스택에 추가할 수 있는 사용자 지정 아이템 속성입니다. 이 속성은 AddInventoryItems, PurchaseInventoryItems, TransferInventoryItems, UpdateInventoryItems 작업으로 추가할 수 있습니다.

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

AddInventoryItems, PurchaseInventoryItems, TransferInventoryItems API의 경우, 표시 속성은 오직 새 스택이 생성될 때만 추가할 수 있습니다. 새 아이템에 대한 표시 속성을 설정하려면 API 요청에 NewStackValues 매개변수를 설정해야 합니다. NewStackValues가 포함된 AddInventoryItems 요청 예시:

{
    "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"
        }
    }
}

스택에 대한 자세한 내용은 여기를 참조하세요.

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

기존 아이템의 표시 속성을 업데이트하려면 UpdateInventoryItems API를 사용하여 속성을 직접 수정할 수 있습니다. DisplayProperties가 포함된 UpdateInventoryItems 요청 예시:

{
    "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"
        }
    }
}

​Inventory

​플레이어 인벤토리 관리

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

​Game Manager

​API

Continuation Token

​인벤토리 아이템 추가

​인벤토리 아이템 차감

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

​인벤토리 아이템 삭제

​인벤토리 아이템 구매

​번들

​인벤토리 아이템 이전

​1. 플레이어 간 이전

​2. 컬렉션 간 이전

​3. 스택 간 이전

​ExecuteInventoryOperations API

​멱등성

​ETag 및 동시성 제어

​표시 속성

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

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

Inventory

플레이어 인벤토리 관리

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

Game Manager

API

인벤토리 아이템 추가

인벤토리 아이템 차감

인벤토리 아이템 업데이트

인벤토리 아이템 삭제

인벤토리 아이템 구매

번들

인벤토리 아이템 이전

1. 플레이어 간 이전

2. 컬렉션 간 이전

3. 스택 간 이전

ExecuteInventoryOperations API

멱등성

ETag 및 동시성 제어

표시 속성

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

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