# 购买

> Use the SDK to make virtual purchases and redeem real money purchases.

通过 `Purchases` 命名空间中的方法，您可以作为当前登录的用户进行购买。

> **Note:**
>
> 此命名空间中的所有方法都可以抛出 [EconomyException](./exceptions.md#economyexception)。

## MakeVirtualPurchaseAsync##makevirtualpurchase

进行 ID 指定的虚拟购买。

此方法可采用 `MakeVirtualPurchaseOptions` 对象。可用于指定玩家背包中应用作购买成本的物品的 `PlayersInventoryItems` ID。如果这些未提供，系统将自动选择用作购买成本的物品。

返回 `MakeVirtualPurchaseResult`。

示例：

```cs title="C#"
string purchaseID = "BUY_A_SWORD";
MakeVirtualPurchaseResult purchaseResult = await EconomyService.Instance.Purchases.MakeVirtualPurchaseAsync(purchaseID);
```

使用 `PlayersInventoryItem` ID 的另一示例：

```cs title="C#"
string purchaseID = "BUY_A_SWORD";
MakeVirtualPurchaseOptions options = new MakeVirtualPurchaseOptions
{
    PlayersInventoryItemIds = new List<string> { "playersInventoryItemId1", "playersInventoryItemId2" }
};

MakeVirtualPurchaseResult purchaseResult = await EconomyService.Instance.Purchases.MakeVirtualPurchaseAsync(purchaseID, options);
```

### MakeVirtualPurchaseOptions##makevirtualpurchaseoptions

`MakeVirtualPurchaseAsync` 调用的选项对象。它有以下字段：

* `PlayersInventoryItemIds`： 字符串列表。默认为 `null`。玩家背包中要用作购买成本的物品的 `PlayersInventoryItem` ID。

### MakeVirtualPurchaseResult##makevirtualpurchaseresult

`MakeVirtualPurchaseAsync` 调用返回该对象。它包含以下字段：

* `Costs`：`Costs` 对象代表此次购买花费的成本。这又包含两个字段：

  * `Currency`：[`CurrencyExchangeItem`](#currencyexchangeitem) 列表，描述的是用于进行此次购买的货币。
  * `Inventory`：[`InventoryExchangeItem`](#inventoryexchangeitem) 列表，描述的是用作此次购买的成本的物品。

* `Rewards`：`Rewards` 对象代表此次购买所得的内容。和以上对象一样，也包含两个字段：

  * `Currency`：[`CurrencyExchangeItem`](#currencyexchangeitem) 列表，描述的是此次购买所得的货币。
  * `Inventory`：[`InventoryExchangeItem`](#inventoryexchangeitem) 列表，描述的是此次购买所得的物品。

## RedeemAppleAppStorePurchaseAsync##redeemappleappstorepurchaseasync

通过提交来自 Apple App Store 的收据来兑换进行真实货币购买的所得内容。如果购买经验证有效，将根据配置中定义的所得内容，将所得内容应用于玩家的背包和货币余额。

必须采用 [`RedeemAppleAppStorePurchaseArgs`](#redeemappleappstorepurchaseargs) 对象。它用于提供购买细节。

```cs title="C#"
RedeemAppleAppStorePurchaseArgs args = new RedeemAppleAppStorePurchaseArgs("PURCHASE_ID", "RECEIPT_FROM_APP_STORE", 0, "USD");
RedeemAppleAppStorePurchaseResult purchaseResult = await EconomyService.Instance.RedeemAppleAppStorePurchaseAsync(args);
```

### RedeemAppleAppStorePurchaseArgs##redeemappleappstorepurchaseargs

用于 `RedeemAppleAppStorePurchaseAsync` 调用的参数对象。它包含以下字段：

* `RealMoneyPurchaseId`：字符串。要进行的购买的配置 ID。
* `Receipt`：字符串。从 Apple App Store 中返回的收据数据。
* `LocalCost`：整数。以整数表示货币中含小数的购买费用，例如，1.99 美元就是 199。
* `LocalCurrency`：字符串。购买中使用的货币的 ISO-4217 代码。

### RedeemAppleAppStorePurchaseResult##redeemappleappstorepurchaseresult

`RedeemAppleAppStorePurchaseAsync` 调用返回该对象。它包含以下字段：

* `Verification`：从验证服务返回的收据验证细节。

  * `Status`：收据验证的状态。为以下某一种：

    * `VALID`：购买有效。
    * `VALID_NOT_REDEEMED`：购买有效，之前可见，但尚未兑换。
    * `INVALID_ALREADY_REDEEMED`：购买已兑换。
    * `INVALID_VERIFICATION_FAILED`：收据验证服务返回的结果是收据数据无效。
    * `INVALID_ANOTHER_PLAYER`：该收据之前已被另一玩家使用并验证过。
    * `INVALID_CONFIGURATION`：服务配置无效，更多信息请参见响应的细节部分。
    * `INVALID_PRODUCT_ID_MISMATCH`：购买配置商店商品标识符与收据中的信息不符。

  * `Store`：来自收据验证服务的细节。这包含三个字段：

    * `Code`：从 Apple App Store 验证服务返回的状态代码。
    * `Message`：返回的状态代码的文本描述。
    * `Receipt`：购买的收据数据。

* `Rewards`：`Rewards` 对象代表此次购买所得的内容。它包含以下字段：

  * `Currency`：[`CurrencyExchangeItem`](#currencyexchangeitem) 列表，描述的是此次购买所得的货币。
  * `Inventory`：[`InventoryExchangeItem`](#inventoryexchangeitem) 列表，描述的是此次购买所得的物品。

### EconomyAppleAppStorePurchaseFailedException##economyappleappstorepurchasefailedexception

`RedeemAppleAppStorePurchaseAsync` 可能抛出 `EconomyAppleAppStorePurchaseFailedException` 类型的异常。它继承自 `EconomyException`，并包含一个额外的字段 `Data`。

`Data` 字段的类型是 `RedeemAppleAppStorePurchaseResult`（参见[上文](#redeemappleappstorepurchaseresult)）。

> **Note:**
>
> `Data` 字段与基类 `Exception` 中的 `Data` 字段不同。

## RedeemGooglePlayPurchaseAsync##redeemgoogleplaypurchaseasync

通过提交来自 Google Play 应用商店的收据来兑换进行真实货币购买的所得内容。如果购买经验证有效，将根据配置中定义的所得内容，将所得内容应用于玩家的背包和货币余额。

必须采用 [`RedeemGooglePlayStorePurchaseArgs`](#redeemgoogleplaystorepurchaseargs) 对象。它用于提供购买细节。

```cs title="C#"
RedeemGooglePlayStorePurchaseArgs args = new RedeemGooglePlayStorePurchaseArgs("PURCHASE_ID", "PURCHASE_DATA", "PURCHASE_DATA_SIGNATURE", 0, "USD");
RedeemGooglePlayPurchaseResult purchaseResult = await EconomyService.Instance.RedeemGooglePlayPurchaseAsync(args);
```

### RedeemGooglePlayStorePurchaseArgs##redeemgoogleplaystorepurchaseargs

用于 `RedeemGooglePlayPurchaseAsync` 调用的参数对象。它包含以下字段：

* `RealMoneyPurchaseId`：字符串。要进行的购买的配置 ID。
* `PurchaseData`：字符串。成功进行应用内结算购买后所返回的 JSON 编码字符串。
* `PurchaseDataSignature`：字符串。成功进行应用内结算购买后所返回的 `PurchaseData` 的签名。
* `LocalCost`：整数。以整数表示货币中含小数的购买费用，例如，1.99 美元就是 199。
* `LocalCurrency`：字符串。购买中使用的货币的 ISO-4217 代码。

### RedeemGooglePlayPurchaseResult##redeemgoogleplaypurchaseresult

`RedeemGooglePlayPurchaseAsync` 调用返回该对象。它包含以下字段：

* `Verification`：从验证服务返回的收据验证细节。

  * `Status`：收据验证的状态。为以下某一种：

    * `VALID`：购买有效。
    * `VALID_NOT_REDEEMED`：购买有效，之前可见，但尚未兑换。
    * `INVALID_ALREADY_REDEEMED`：购买已兑换。
    * `INVALID_VERIFICATION_FAILED`：收据验证服务返回的结果是收据数据无效。
    * `INVALID_ANOTHER_PLAYER`：该收据之前已被另一玩家使用并验证过。
    * `INVALID_CONFIGURATION`：服务配置无效，更多信息请参见响应的细节部分。
    * `INVALID_PRODUCT_ID_MISMATCH`：购买配置商店商品标识符与收据中的信息不符。

  * `Store`：来自收据验证服务的细节。它包含一个字段：

    * `Receipt`：购买的收据数据。

* `Rewards`：`Rewards` 对象代表此次购买所得的内容。它包含以下字段：

  * `Currency`：[`CurrencyExchangeItem`](#currencyexchangeitem) 列表，描述的是此次购买所得的货币。
  * `Inventory`：[`InventoryExchangeItem`](#inventoryexchangeitem) 列表，描述的是此次购买所得的物品。

### EconomyGooglePlayStorePurchaseFailedException##economygoogleplaystorepurchasefailedexception

`RedeemGooglePlayPurchaseAsync` 可能抛出 `EconomyGooglePlayStorePurchaseFailedException` 类型的异常。它继承自 `EconomyException`，并包含一个额外的字段 `Data`。

`Data` 字段的类型是 `RedeemGooglePlayPurchaseResult`（参见[上文](#redeemgoogleplaypurchaseresult)）。

> **Note:**
>
> `Data` 字段与基类 `Exception` 中的 `Data` 字段不同。

## CurrencyExchangeItem##currencyexchangeitem

该对象代表购买中涉及的某种货币。它包含以下字段：

* `Id`：货币的 ID。
* `Amount`：购买时使用的该货币的数量。

## InventoryExchangeItem##inventoryexchangeitem

该对象表示购买中涉及的背包物品。它包含以下字段：

* `Id`：货币的 ID。
* `Amount`：购买中使用/所得的该背包物品的数量。
* `InstanceIds`：购买中使用/所得的实例的 ID 列表。