# プレイヤーの残高

> 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

プレイヤーの残高は、プレイヤーの 1 つの通貨残高を表します。これには以下のフィールドがあります。

* `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}");
};
```