管理服务中的易耗品
如果你的游戏使用基于易耗品的生态系统，那么最好开发一项后端服务来验证和管理游戏中的易耗品交易。 这样，就可在你的受信任的服务和 Xbox Store 服务 API 之间直接对易耗品进行安全的通信和管理。 依赖客户端来管理这些交易会带来风险，成为欺骗生态系统的攻击载体。 例如，用户可能会操作客户端上的流量或丢弃数据包，从而导致消费调用出现问题。 在以前的案例中，这导致了未直接通过游戏服务管理和控制的易耗品被盗窃和操作。
本文将概述如何构建可靠安全的服务以管理易耗品生态系统。 此外，本文还概述了如何检测和管理用户的易耗品退款，从而防止易耗品欺诈和盗窃行为。
若要管理易耗品并处理退款，你将从服务中调用以下 Microsoft Store API。 若要具体了解如何调用和解析结果，请参阅文档页。
| Microsoft Store API | 函数 |
|---|---|
| collections.mp.microsoft.com/v8.0/collections/consume | 消费或履行用户拥有的易耗品。 |
| purchase.mp.microsoft.com/v8.0/b2b/orders/query | 采购订单 - 报告用户在过去 90 天内进行的易耗品购买。 |
| purchase.mp.microsoft.com/v8.0/b2b/clawback/sastoken | 提供 SAS 令牌，用于查询 Clawback 事件服务消息队列中与产品相关的退款事件。 |
利用 Microsoft.StoreServices .NET 库和示例
为了帮助演示本文概述的原则和流程，请查看提供以下内容的 Microsoft.StoreServices 示例：
使用 Microsoft.StoreServices 库管理身份验证并调用 Microsoft Store 服务。
示例逻辑，用于管理易耗品、跟踪待处理的消费请求、核对退款的购买内容、续订过期的用户 Store ID 等。
配置指南，其中包括本文中有关如何为此身份验证方法配置和设置 Microsoft Entra ID 的步骤。
管理易耗品
推荐的易耗品管理服务概述
可靠的易耗品管理系统将包括以下功能：
- 接收来自客户端的通过易耗品货币使用或购买游戏内物品的请求
- 使用 Microsoft Store 服务 API 进行身份验证
- 验证用户在 Microsoft Store 中的产品余额
- 验证用户是否有足够的可消费货币用于交易（由服务器管理或由商店管理）
- 消耗或完成用户余额的一部分
- 跟踪并重试消费请求（若需要）来验证使用情况
- 完成客户的交易请求
- 向游戏客户端报告从交易中获得的结果或物品
- 核对已退款的易耗品交易
管理服务与 Microsoft Store 上的用户余额
通过从 Microsoft Store 消费任何非零余额，可以在游戏服务上完全管理商店管理的易耗品。 或者，用户的易耗余额可以在 Microsoft Store 上进行管理，只需使用用户在游戏内经济中购买内容时所需的数量。 但是，开发人员管理的易耗品必须由游戏服务管理。 请参阅选择适当的产品类型，详细了解开发人员管理的易耗品和 Microsoft Store 管理的易耗品。
推荐的且最常用的方法是跟踪和管理用户在游戏服务中的可用余额。 这需要查询 Microsoft Store，看看用户是否有游戏易耗品余额非零的情况，然后消耗这些余额，使其降至零，并将等值的游戏内货币添加到游戏服务跟踪的用户余额中。 这样，合作伙伴就能知道用户当前的余额并进行管理，而无需在使用后再次调用 Microsoft Store API。 在跨平台场景中，这个方法也是最棒的，它使在多个商店购买的易耗品可组合在一起，并在允许的情况下跨不同平台使用。 另一个好处是，如果用户有问题或需要联系客户服务，你的服务可根据需要直接在服务器上为用户余额添加数量，不必对 Microsoft Store 中的产品进行管理或授予代码。 使用这种方法，Microsoft Store 管理的易耗品通常配置为每个用户购买的数量为 1。 然后，该数量会转换成与产品相关的游戏内货币单位的数量。 示例：当用户购买一个“500 硬币”易耗品时，用户在 Microsoft Store API 中该产品的数量将增加 1。 当用户通过服务消费时，数量将减至 0，用户在服务上的帐户余额将记入 500 个游戏币。
Microsoft Store 管理的易耗品也可配置为在购买时向用户的数量授予任何指定值。 例如，你可设置上面提到的“500 硬币”选项，以便每次购买时将用户在 Microsoft Store API 中的数量增加 500。 这样，当用户购买更多的可消费货币时，商店会管理用户的余额；当用户从你的易耗品生态系统购买游戏内物品时，服务会从余额中扣除数量。
使用 TrackingId 作为冗余系统来进行消费验证
从服务中实现或消费产品时，在消费请求中包含 TrackingId。 此 TrackingId 可用作冗余回退，用于验证交易请求是否已成功完成并在 Microsoft Store 服务上得到响应。 例如，如果你的服务发送了一个消费请求，但是没有得到响应，那么无法知道用户的余额是否根据请求进行了更改。 这样的话，你的服务将不知道是否应该向用户授予易耗品。 你可针对 TrackingId、要删除的数量和 productId 都相同的同一用户帐户重新发出请求，使 Microsoft Store 服务对该消费交易的结果作出响应。 下面提供了从服务中实现易耗品的推荐示例流。 此流使用 TrackingId 并保留一个待处理消费交易列表，以便能够在需要时验证请求的结果。
产品 1（500 个游戏币）是一种易耗品，配置为每次购买时授予数量 1，然后在服务中转换为 500 枚硬币。
- 用户购买产品 1，当调用查询服务时，产品的数量为 1
- 游戏的服务查询是用户在 Microsoft Store 查询 API 中的易耗品余额，看到用户的余额为“1”
- 游戏服务生成一个 TrackingID，创建一个消费请求来消费 1 个产品数量，并将请求信息添加到待处理交易列表中。
- 游戏服务将请求发送到 Microsoft Store 消费 API
- 发生了某种情况，游戏服务从未从消费 API 获得响应。 原因可能是网络数据包丢失、服务中断、电源中断等。
此时，游戏服务不知道 Microsoft 端是否真的消耗了数量。 如果他们再次查询库存，数量仍然可能是 1，但这并不意味着交易没有进行。 消费可能已成功，导致数量为 0，但用户可能在停机期间再次购买了易耗品，将其数量恢复到 1。 若要验证交易是否完成，我们需要使用上面添加了请求的待处理交易列表。
- 游戏服务决定何时应重试消费请求
- 游戏服务使用相同的用户、ProductId、TrackingId 和数量重新创建消费请求
- 游戏服务将请求发送到 Microsoft Store 消费 API
- 游戏服务收到消费成功且新用户余额为“0”的响应
- 游戏服务将 500 枚硬币添加到服务器上跟踪的用户货币余额中
- 游戏服务从待处理交易列表中删除消费请求，因为该物品现在已经被消费、验证，并且用户在服务上被授予了正确的游戏内货币
Microsoft Store 消费 API 在验证历史交易请求时的行为
如果消费 API 之前没有看到传入的请求（TrackingID、用户、数量和 ProductID），它会将其视为一个新的传入请求，并根据用户在系统中的当前可消费余额适当地完成该请求。
如果消费 API 看到这是对先前消费的交易（TrackingId、用户、数量和 ProductId 相同）的重试，则不会从用户余额中第二次消费该物品。 但是，服务将这样进行响应：指示请求的消费已完成并指出用户的当前剩余余额。 因此，如果没有收到响应，那么重试或重播消费请求来验证请求是否完成始终是安全的。 但是，你必须确保用户、TrackingId、数量和 Product 与上一次调用完全相同。 如果对消费 API 使用 X 预付码进行身份验证，只要新的 X 预付码与上个请求针对的是同一位 Xbox Live 用户，就可以更新并获取新的 X 预付码。 这可能是必要的，因为 X 预付码有效期只有 4 小时，之后必须获取新的预付码。
使用 Clawback 事件服务缓解易耗品退货和退款欺诈
为了帮助防止易耗品的滥用和欺诈性退货/退款，还建议将服务与 Clawback 事件服务集成。 这将允许服务在用户购买的易耗品退回或退款时接收事件，并且服务应从服务端删除该易耗品的附加价值。
若要对 Clawback 事件执行操作，需要确保在消耗请求中使用“includeOrderIds：TRUE”选项 来 collections.mp.microsoft.com/v8.0/collections/consume。 然后，易耗品管理服务需要记录事务，包括系统中的用户信息、OrderID、LineItemOrderId、ProductID 和任何其他有用信息。 然后，可以使用 Clawback 事件的 OrderID 和 LineItemOrderID 对在已完成的事务中搜索匹配项。
有关详细信息，请参阅管理服务的退款和退单拒付