# 플레이어 인벤토리

> Use the SDK to manage player inventory items including adding, updating, and deleting items.

`PlayerInventory` 네임스페이스에서 메서드를 사용하면 플레이어 인벤토리 인스턴스를 가져오고 업데이트할 수 있습니다.

이러한 메서드는 현재 Authentication SDK에서 로그인된 플레이어의 인벤토리 데이터를 반환합니다.

> **Note:**
>
> 이 네임스페이스에 있는 모든 메서드로 인해 [EconomyException](./exceptions.md#economyexception)이 발생할 수 있습니다.

## GetInventoryAsync##getinventory

현재 로그인된 플레이어와 연결된 현재 인벤토리 아이템 인스턴스를 가져옵니다.

이 메서드는 필요에 따라 `GetInventoryOptions` 오브젝트를 사용합니다. 이를 통해 각 가져오기의 아이템 수를 설정하고 필터링할 수 있습니다.

구성 아이템 ID 목록이나 `PlayersInventoryItem` ID를 사용하여 인벤토리 아이템을 필터링할 수 있습니다. 이러한 필터 옵션을 사용하면 특정 구성 아이템 ID와 `PlayersInventoryItem` ID에 포함된 플레이어 아이템만 반환됩니다.

다음 샘플 코드는 현재 사용자의 첫 아이템 5개를 가져온 후, 그 다음 5개를 가져옵니다.

```cs title="C#"
// Optional, defaults to 20
GetInventoryOptions options = new GetInventoryOptions
{
    ItemsPerFetch = 5
};

GetInventoryResult inventoryResult = await EconomyService.Instance.PlayerInventory.GetInventoryAsync(options);
List<PlayersInventoryItem> firstFiveItems = inventoryResult.PlayersInventoryItems;
// do something with your items

if (inventoryResult.HasNext) {
    inventoryResult = await inventoryResult.GetNextAsync(5);
    List<PlayersInventoryItem> nextFiveItems = inventoryResult.PlayersInventoryItems;
    // do something with your items
}
```

다음 샘플 코드는 플레이어의 `SWORD` 아이템만 가져옵니다.

```cs title="C#"
GetInventoryOptions options = new GetInventoryOptions
{
    InventoryItemIds = new List<string>() { "SWORD" }
};

GetInventoryResult inventoryResult = await EconomyService.Instance.PlayerInventory.GetInventoryAsync(options);

List<PlayersInventoryItem> listOfItems = inventoryResult.PlayersInventoryItems;

// ... etc
```

이 메서드는 `GetInventoryResult`를 반환합니다.

### GetInventoryOptions##getinventoryoptions

`GetInventoryAsync` 호출의 옵션 오브젝트입니다. 포함되는 필드는 다음과 같습니다.

* `PlayersInventoryItemIds`: 문자열 목록입니다. 기본값은 `null`입니다. 플레이어 인벤토리에서 가져오려는 아이템의 `PlayersInventoryItem` ID입니다.
* `InventoryItemIds`: 문자열 목록입니다. 기본값은 `null`입니다. 가져오려는 아이템의 구성 ID입니다.
* `ItemsPerFetch`: 정수입니다. 기본값은 20입니다. 이를 통해 1\~100까지 호출당 가져올 최대 아이템 수를 설정합니다.

### GetInventoryResult##getinventoryresult

`GetInventoryResult`는 가져온 플레이어의 인벤토리 아이템 목록에 대해 페이지가 지정된 액세스를 제공합니다. 포함되는 필드는 다음과 같습니다.

* `PlayersInventoryItems`: `List<PlayersInventoryItem>`과 현재 가져온 아이템이 있습니다.

포함되는 메서드는 다음과 같습니다.

* `GetNextAsync(int itemsToFetch = 20)`: 이 메서드는 비동기식으로 더 많은 결과를 가져옵니다. 여기에는 필요에 따라 가져오는 결과를 제한하는 파라미터 1개가 포함됩니다. 1\~100으로 설정할 수 있으며 기본값은 20입니다. `PlayersInventoryItems` 목록에는 원래 아이템과 새로 가져온 아이템이 모두 포함된 새 결과가 반환됩니다. 가져올 결과가 더 없으면 결과값은 `null`이 됩니다.

## AddInventoryItemAsync##addinventoryitemasync

플레이어의 인벤토리에 아이템을 추가합니다.

이 메서드는 필요에 따라 `AddInventoryItemOptions` 오브젝트를 사용합니다. 이를 통해 커스텀 `PlayersInventoryItemId`를 설정합니다. 값이 `null`이면 자동으로 하나가 생성됩니다. 인스턴스 데이터의 딕셔너리를 설정하는 데 사용할 수도 있습니다.

플레이어 인벤토리에 추가된 인벤토리 아이템을 나타내는 `PlayersInventoryItem`이 반환됩니다.

```cs title="C#"
Dictionary<string, object> instanceData = new Dictionary<string, object>
{
    { "rarity", "purple" }
};

AddInventoryItemOptions options = new AddInventoryItemOptions
{
    PlayersInventoryItemId = "customID",
    InstanceData = instanceData 
};

PlayersInventoryItem createdInventoryItem = await EconomyService.Instance.PlayerInventory.AddInventoryItemAsync("SWORD", options);
```

### AddInventoryItemOptions##addinventoryitemoptions

`AddInventoryItemAsync` 호출의 옵션 오브젝트입니다. 포함되는 필드는 다음과 같습니다.

* `PlayersInventoryItemId`: 문자열이며, 기본값은 `null`입니다. 생성된 `PlayersInventoryItem`의 ID를 설정합니다. 설정되지 않으면 하나가 생성됩니다.
* `InstanceData`: `Dictionary<string, object>`입니다. [인스턴스 데이터](#using-instancedata)의 딕셔너리를 설정하는 데 사용됩니다.

## DeletePlayersInventoryItemAsync##deleteplayersinventoryitemasync

플레이어 인벤토리에서 아이템을 삭제합니다.

이 메서드는 필요에 따라 쓰기 잠금을 설정하는 데 사용되는 `DeletePlayersInventoryItemOptions` 오브젝트를 사용합니다. 쓰기 잠금이 입력되면 Economy 서비스에서 쓰기 잠금이 허용된 경우에만 아이템이 삭제됩니다. 쓰기 잠금이 입력되지 않으면 작업이 강제로 실행됩니다.

```cs title="C#"
DeletePlayersInventoryItemOptions options = new DeletePlayersInventoryItemOptions
{
    WriteLock = "writeLock"
};
EconomyService.Instance.PlayerInventory.DeletePlayersInventoryItemAsync("playersInventoryItemID", options);
```

### DeletePlayersInventoryItemOptions##deleteplayersinventoryitemoptions

`DeletePlayersInventoryItemAsync` 호출의 옵션 오브젝트입니다. 포함되는 필드는 다음과 같습니다.

* `WriteLock`: 문자열이며, 기본값은 `null`입니다. 이 문자열을 사용하여 낙관적 동시성을 위한 쓰기 잠금을 설정합니다. [쓰기 잠금](./common-objects.md#using-the-writelock)을 참고하십시오.

## UpdatePlayersInventoryItemAsync##updateplayersinventoryitemasync

새 인스턴스 데이터를 사용하여 아이템을 업데이트합니다.

업데이트된 플레이어 인벤토리 아이템이 반환됩니다.

이 메서드는 필요에 따라 쓰기 잠금을 설정하는 데 사용되는 `UpdatePlayersInventoryItemOptions` 오브젝트를 사용합니다. 쓰기 잠금이 입력되면 Economy 서비스에서 쓰기 잠금이 허용된 경우에만 아이템이 업데이트됩니다. 쓰기 잠금이 입력되지 않으면 작업이 강제로 실행됩니다.

```cs title="C#"
Dictionary<string, object> instanceData = new Dictionary<string, object>
{
    { "rarity", "purple" }
};

UpdatePlayersInventoryItemOptions options = new UpdatePlayersInventoryItemOptions
{
    WriteLock = writeLock 
};

PlayersInventoryItem playersInventoryItem = await EconomyService.Instance.PlayerInventory.UpdatePlayersInventoryItemAsync("playersInventoryItemID", instanceData, options);
```

### UpdatePlayersInventoryItemOptions##updateplayersinventoryitemoptions

`UpdatePlayersInventoryItemAsync` 호출의 옵션 오브젝트입니다. 포함되는 필드는 다음과 같습니다.

* `WriteLock`: 문자열이며, 기본값은 `null`입니다. 이 문자열을 사용하여 낙관적 동시성을 위한 쓰기 잠금을 설정합니다. [쓰기 잠금](./common-objects.md#using-the-writelock)을 참고하십시오.

## PlayersInventoryItem##playersinventoryitem

`PlayersInventoryItem`은 플레이어 인벤토리에 있는 단일 고유 아이템입니다. 포함되는 필드는 다음과 같습니다.

* `PlayersInventoryItemId`: 플레이어 인벤토리에 있는 이 고유한 인벤토리 아이템의 ID입니다.
* `InstanceItemId`: 이 인벤토리 아이템의 구성 ID입니다.
* `InstanceData`: 이 플레이어 인벤토리 아이템과 연결된 모든 인스턴스 데이터입니다.
* `InstanceDataDeserializable`: `IDeserializable`로 이 플레이어 인벤토리 아이템과 연결된 모든 인스턴스 데이터입니다. [InstanceDataDeserializable 사용](#using-instancedata)을 참고하십시오.
* `WriteLock`: 이 플레이어 인벤토리 아이템의 현재 `writelock` 문자열입니다.
* `Created`: 이 플레이어 인벤토리 아이템이 생성된 날짜입니다. [EconomyDate](./common-objects.md#economydate) 오브젝트입니다.
* `Modified`: 이 플레이어 인벤토리 아이템이 수정된 날짜입니다. [EconomyDate](./common-objects.md#economydate) 오브젝트입니다.

다음의 헬퍼 메서드도 포함되어 있습니다.

### GetItemDefinitionAsync##getitemdefinitionasync

이 메서드는 이 플레이어의 인벤토리 아이템 구성(`InventoryItemDefinition` 유형)을 가져옵니다.

```cs title="C#"
PlayersInventoryItem playersInventoryItem = // ... fetch the players inventory item
InventoryItemDefinition itemDefinition = playersInventoryItem.GetItemDefinitionAsync();
```

## PlayersInventoryItemUpdated##playersinventoryitemupdated

이 이벤트를 구독하면 SDK에서 플레이어 인벤토리의 특정 아이템이 업데이트될 때 알림을 받을 수 있습니다. 구독자에게는 업데이트된 아이템의 `playersInventoryItem` ID가 전달됩니다.

> **Note:**
>
> 이 이벤트는 SDK에서 시작된 작업(예: 플레이어 인벤토리 업데이트, 구매)에서만 호출됩니다. 업데이트가 다른 디바이스나 서비스에서 발생한 변경 사항으로 인한 것이면 호출되지 않습니다.

```cs title="C#"
EconomyService.Instance.PlayerInventory.PlayersInventoryItemUpdated += playersInventoryItemID => {
    Debug.Log($"The players inventory item that was updated was {playersInventoryItemID}");
};
```

### InstanceDataDeserializable 사용##using-instancedata

`InstanceDataDeserializable`을 사용하여 플레이어 인벤토리의 특정 아이템에 대해 커스텀 데이터를 추가합니다. 이는 `object` 유형으로 전달되고 `IDeserializable` 유형으로 가져옵니다. 이렇게 하면 커스텀 클래스를 인스턴스 데이터로 전달할 수 있습니다.

예를 들어 플레이어의 방패에 내구성 등급이 있다고 가정해 봅니다. 이를 설정하고 업데이트하는 데 `InstanceDataDeserializable`을 사용할 수 있습니다.

```cs title="C#"
class MyInstanceData
    {
        public int Durability;
        public string Rarity;
    }

MyInstanceData myInstanceData = new MyInstanceData() { Durability = 100, Rarity = "purple"};
PlayersInventoryItem updatedItem = await EconomyService.Instance.PlayerInventory.UpdatePlayersInventoryItemAsync("playersInventoryItemId", myInstanceData);
```

다음 작업을 수행하여 인스턴스 데이터를 역직렬화할 수 있습니다.

```cs title="C#"
MyInstanceData fetchedInstanceData = updatedItem.InstanceData.GetAs<MyInstanceData>();
int durability = fetchedInstanceData.Durability;
string rarity = fetchedInstanceData.Rarity;
```