# 플레이어 잔액

> Use the SDK to manage player currency balances.

`PlayerBalances` 네임스페이스에는 플레이어의 재화 잔액을 가져오고 업데이트하는 것과 관련된 모든 메서드가 포함되어 있습니다.

이러한 메서드는 현재 Authentication SDK에서 로그인된 플레이어의 잔액을 반환합니다.

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

## GetBalancesAsync##getbalances

현재 사용자의 재화 잔액을 가져옵니다. 필요에 따라 `GetBalancesOptions`를 사용합니다.

잔액을 가져올 때 `GetBalancesOptions`를 사용하여 가져오려는 잔액 수의 제한(1\~100까지)을 설정할 수 있습니다. 이는 페이지 지정에 유용합니다. 기본 수는 20입니다.

다음 샘플 코드는 현재 사용자의 처음 잔액 5개를 가져온 다음, 구성에서 삭제된 재화를 포함하여 다음 잔액 5개를 가져옵니다.

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

GetBalancesResult getBalancesResult = await EconomyService.Instance.PlayerBalances.GetBalancesAsync(options);
List<PlayerBalance> firstFiveBalances = getBalancesResult.Balances;
// do something with your balances

if (getBalancesResult.HasNext) {
    getBalancesResult = await getBalancesResult.GetNextAsync(options.ItemsPerFetch);
    List<PlayerBalance> nextFiveBalances = getBalancesResult.Balances;
    // do something with your balances
}
```

이 메서드는 `GetBalancesResult`를 반환합니다. [GetBalancesResult](#getbalancesresults)를 참고하십시오.

### GetBalancesOptions##getbalancesoptions

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

* `ItemsPerFetch`: 정수입니다. 기본값은 20입니다. 이 필드를 사용하여 1\~100까지 호출당 가져올 최대 잔액 수를 설정합니다.

### GetBalancesResult##getbalancesresults

`GetBalancesResult`는 가져온 잔액 목록에 대해 페이지가 지정된 액세스를 제공합니다. 포함되는 필드는 다음과 같습니다.

* `Balances`: `List<PlayerBalance>`와 현재 가져온 잔액이 있습니다.

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

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

## SetBalanceAsync##setbalance

특정 재화의 잔액을 특정 값으로 설정합니다.

이 메서드는 필요에 따라 쓰기 잠금을 설정하는 데 사용되는 `SetBalancesOptions` 오브젝트를 사용합니다. 이 내용이 입력된 경우 `writeLock`이 이전 읽기에서 수신한 `writeLock`과 일치하지 않으면 낙관적 동시성을 제공하기 위해 예외가 발생합니다. 입력되지 않은 경우 데이터의 기존 `writeLock`에 구애받지 않고 거래가 진행됩니다.

작업이 성공하면 이 메서드는 업데이트가 적용된 후 현재 잔액을 반환합니다.

```cs title="C#"
string currencyID = "GOLD_BARS";
int newAmount = 1000;
string writeLock = "someLockValueFromPreviousRequest";
SetBalanceOptions options = new SetBalanceOptions
{
    WriteLock = writeLock
};

PlayerBalance newBalance = await EconomyService.Instance.PlayerBalances.SetBalanceAsync(currencyID, newAmount);
// OR
PlayerBalance otherNewBalance = await EconomyService.Instance.PlayerBalances.SetBalanceAsync(currencyID, newAmount, options);
```

### SetBalanceOptions##setbalanceoptions

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

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

## IncrementBalanceAsync##incrementbalance

특정 재화의 잔액을 특정 값에 따라 증액합니다.

이 메서드는 필요에 따라 쓰기 잠금을 설정하는 데 사용되는 `IncrementBalancesOptions` 오브젝트를 사용합니다. 이 내용이 입력된 경우 `writeLock`이 이전 읽기에서 수신한 `writeLock`과 일치하지 않으면 낙관적 동시성을 제공하기 위해 예외가 발생합니다. 입력되지 않은 경우 데이터의 기존 `writeLock`에 구애받지 않고 거래가 진행됩니다.

작업이 성공하면 이 메서드는 업데이트가 적용된 후 현재 잔액을 반환합니다.

```cs title="C#"
string currencyID = "GOLD_BARS";
int incrementAmount = 1000;
string writeLock = "someLockValueFromPreviousRequest";
IncrementBalanceOptions options = new IncrementBalanceOptions
{
    WriteLock = writeLock
};

PlayerBalance newBalance = await EconomyService.Instance.PlayerBalances.IncrementBalanceAsync(currencyID, newAmount);
// OR
PlayerBalance otherNewBalance = await EconomyService.Instance.PlayerBalances.IncrementBalanceAsync(currencyID, newAmount, options);
```

### IncrementBalanceOptions##incrementbalanceoptions

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

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

## DecrementBalanceAsync##decrementbalance

특정 재화의 잔액을 특정 값에 따라 감액합니다.

이 메서드는 필요에 따라 쓰기 잠금을 설정하는 데 사용되는 `DecrementBalanceOptions` 오브젝트를 사용합니다. 이 내용이 입력된 경우 `writeLock`이 이전 읽기에서 수신한 `writeLock`과 일치하지 않으면 낙관적 동시성을 제공하기 위해 예외가 발생합니다. 입력되지 않은 경우 데이터의 기존 `writeLock`에 구애받지 않고 거래가 진행됩니다.

작업이 성공하면 이 메서드는 업데이트가 적용된 후 현재 잔액을 반환합니다.

```cs title="C#"
string currencyID = "GOLD_BARS";
int decrementAmount = 1000;
string writeLock = "someLockValueFromPreviousRequest";
DecrementBalanceOptions options = new DecrementBalanceOptions
{
    WriteLock = writeLock
};

PlayerBalance newBalance = await EconomyService.Instance.PlayerBalances.DecrementBalanceAsync(currencyID, newAmount);
// OR
PlayerBalance otherNewBalance = await EconomyService.Instance.PlayerBalances.DecrementBalanceAsync(currencyID, newAmount, options);
```

### DecrementBalanceOptions##decrementbalanceoptions

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

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

## PlayerBalance##playerbalance

플레이어 잔액은 플레이어의 단일 재화 잔액을 나타냅니다. 포함되는 필드는 다음과 같습니다.

* `CurrencyId`: 이 잔액이 나타내는 재화의 ID입니다.
* `Balance`: 플레이어가 보유한 이 재화의 금액(정수)입니다.
* `WriteLock`: 현재 `writeLock` 문자열입니다.
* `Created`: 이 잔액이 생성된 날짜입니다. [EconomyDate](./common-objects.md#economydate) 오브젝트입니다.
* `Modified`: 이 잔액이 수정된 날짜입니다. [EconomyDate](./common-objects.md#economydate) 오브젝트입니다.

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

### GetCurrencyDefinitionAsync##getcurrencydefinitionasync

이 잔액과 연결된 재화의 재화 정의를 가져올 수 있는 간편한 메서드입니다. [CurrencyDefinition](./configuration.md#currencydefinition)이 반환됩니다.

```cs title="C#"
PlayerBalance myPlayerBalance = ... // Get a player balance from one of the above methods
CurrencyDefinition currencyDefForMyPlayerBalance = myPlayerBalance.GetCurrencyDefinitionAsync();
```

## BalanceUpdated##balanceupdated

이 이벤트를 구독하면 SDK에서 특정 재화의 잔액이 업데이트될 때 알림을 받을 수 있습니다. 구독자에게는 업데이트된 잔액의 재화 ID가 전달됩니다.

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

```cs title="C#"
EconomyService.Instance.PlayerBalances.BalanceUpdated += currencyID => {
    Debug.Log($"The currency that was updated was {currencyID}");
};
```