인벤토리

아티클
07/13/2023

Important

이제 Economy v2가 일반 공급됩니다. 지원 및 피드백을 받으려면 PlayFab 포럼으로 이동하세요.

PlayFab 인벤토리 API는 플레이어 인벤토리 및 인벤토리 데이터를 관리하고 저장하는 기능을 제공합니다. 스택 및 컬렉션과 같은 기능을 사용하면 플레이어 인벤토리를 유연하게 구성할 수 있으며 이 시스템이 모든 게임에서 작동하도록 할 수 있습니다.

플레이어 인벤토리 관리

다음 API는 플레이어의 인벤토리에 있는 아이템을 추가, 제거, 업데이트 및 삭제하는 데 사용됩니다. 현재는 아이템 3,500개까지로 제한되어 있으며, 이 제한을 초과하면 오류가 발생합니다.

게임 관리자에서 Players(으)로 이동
New Player를 보거나 만들려는 플레이어를 선택한 다음 Inventory (V2)로 이동

GetInventoryItems를 이용하여 플레이어 인벤토리를 가져올 수 있습니다. 플레이어는 자신의 인벤토리에 액세스하고 조작하는 것만 하도록 제한됩니다. 타이틀 엔티티는 액세스하려는 플레이어의 인벤토리를 나타내기 위해 Entity 매개 변수를 전달할 수 있습니다.

예제 GetInventoryItems 요청:

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

CollectionId을(를) 사용하고 플레이어당 여러 인벤토리를 보유하는 방법에 대한 자세한 내용은 여기에서 확인할 수 있습니다.

연속 토큰

검색 응답에서 반환된 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는 아이템과 해당 아이템의개당 가격 목록입니다. 이 가격은 카탈로그나 지정된 저장소에 구성된 값과 일치해야 합니다.
StoreId는 아이템을 구매할 스토어의 선택적 매개 변수입니다. 스토어에 대한 자세한 내용은 여기에서 확인할 수 있습니다.

예제 PurchaseInventoryItems 요청:

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

인벤토리 아이템 전송

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

플레이어끼리 아이템을 주고받는 경우(예: 플레이어 A가 플레이어 B에게 사과 3개 제공)
동일한 플레이어가 서로 다른 인벤토리 컬렉션 사이에서 아이템을 옮기는 경우(예: 플레이어 A가 마법사 캐릭터 인벤토리에서 전사 캐릭터 인벤토리로 롱소드를 옮기는 경우)
동일한 플레이어가 인벤토리에서 아이템을 옮겨 아이템 스택을 만들거나 없애거나 조절하는 경우(예: 플레이어 A가 금화 10개짜리 스택을 금화 3개짜리 스택과 금화 7개짜리 스택으로 나누는 경우)

GivingItem 및 Amount 매개 변수는 전송되는 아이템과 전송되는 수량을 나타내는 데 사용됩니다. ReceivingItem은 아이템을 받을 플레이어 계정의 아이템 대상을 나타냅니다. GivingItem과 ReceivingItem 매개 변수는 모두 InventoryItemReference 개체로서 해당 아이템의 Id와 StackId를 포함하고 있습니다. 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. 컬렉션 간의 이동

컬렉션 사이에서 이동하는 경우 GivingCollectionId와 ReceivingCollectionId가 모두 설정되어 어떤 인벤토리 컬렉션 ID에서 어떤 인벤토리 컬렉션 ID로 아이템이 이동할 것인지 각각 나타내어야 합니다.

컬렉션 간의 예시 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
}

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

컬렉션과 관련된 자세한 정보는 여기에서 확인할 수 있습니다.

3. 스택 간의 이동

스택 사이에 아이템을 이동하는 경우, GivingItem의 StackId와 요청 ReceivingItem이 지정되어야 합니다.

스택 간의 예시 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
}

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

스택과 관련된 자세한 정보는 여기에서 확인할 수 있습니다.

ExecuteInventoryOperations API

ExecuteInventoryOperations API를 이용하여 단일 요청에서 여러 인벤토리 작업을 일괄 처리할 수 있습니다. 작업은 지정된 요청 순서로 수행되며 작업을 수행할 수 없는 경우 전체 작업 집합이 취소됩니다.

ExecuteInventoryOperations는 작업 목록인 Operation 매개 변수를 사용합니다. Operation 목록에는 작업이 최대 10개까지 들어갈 수 있지만 작업 유형은 반복할 수 있어서 추가 작업만 10개 수행하는 것도 유효합니다. 또한, 단일 요청에서 수정/추가할 수 있는 아이템은 250개로 제한됩니다. 예를 들어 아이템 50개가 있는 번들을 추가하면 아이템 50개가 수정된 것으로 계산됩니다. 유효한 작업 유형은 다음과 같습니다.

추가
빼기
업데이트
구매
전송*
삭제

참고 항목

*단일 컬렉션 전송만 일괄 처리로 지원됩니다.

예제 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
            }
        }
    ]
}

멱등성

인벤토리 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를 사용하는 경우 충돌을 일으켜 오류가 발생합니다.

디스플레이 속성

디스플레이 속성은 플레이어 인벤토리의 아이템 및 아이템 스택에 추가할 수 있는 사용자 지정 아이템 속성입니다.

이들 속성은 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"
        }
    }
}