collections.mp.microsoft.com/v8.0/collections/consume

项目
06/20/2024

此消费 API 可用于托管 Microsoft Store 内以下类型的易耗品：

Microsoft Store 托管型易耗品：报告一个消耗数量并将其从指定用户的当前余量中删除。用户可重复购买 Microsoft Store 托管型 Consumable（易耗品）（您的游戏无需将其报告为已消耗或已实现）。有关详细信息，请参阅 Store 托管的消耗请求。
开发人员托管型 Consumable（易耗品）：为特定客户将一款 Consumable（易耗品）报告为已实现。在用户可以重新购买一款开发者托管型 Consumable（易耗品）之前，您的应用程序或服务必须面向该用户将 Consumable（易耗品）报告为已完成。有关详细信息，请参阅开发者托管的消耗请求。

使用 trackingId 验证实现的完成情况

trackingId 如果您的服务未收到确认，将使用它作为一种冗余检查来验证实现请求的成功履行。如果您的服务遇到未收到确认响应的状态，则它可以使用相同的请求正文（包括跟踪 ID）重新提交该请求，并在为该 Consumable（易耗品）提供游戏内项目之前重新获取确认信息。

每个消耗请求都应有唯一的跟踪 ID。它始终与生成它的消耗请求关联并且可以无限期地重新提交以用于验证。如果消耗未获取请求或未实现，则服务将以正常方式完成请求的交易。如果“实现”已在上一个请求中完成，则该“消耗”会将此项识别为确认请求，因为存在相同的值和 trackingId。在这种情况下，消耗不会从用户余量中完成第二次实现或扣减。相反，消费服务采用与消费发生时相同的格式发送一个成功响应，并将剩余的当前余量转发回来。

因此，最佳做法是保留每项请求的值和 trackingId 并将其缓存在您的服务器或日志中，直至您收到请求已被实现的确认响应。有关示例，请参阅游戏服务示例。

在重试请求中使用 includeOrderIds 参数时，根据产品的易耗品类型会发生以下情况

易耗品类型	首次使用请求行为	重试使用请求行为
应用商店托管	用于实现返回的使用请求的订单 ID	用于实现返回的使用请求的相同订单 ID
开发者管理的	用于实现返回的使用请求的订单 ID	未返回任何 ID，因为在使用此产品类型后不会跟踪此数据

因此，如果你使用的是开发人员管理的易耗品，请知悉，如果调用是验证它已被使用的重试检查，你将无法获取实现的订单 ID 信息。

先决条件

若要使用此 API，您需要使用以下身份验证方法之一。

信赖方的委派授权 XSTS 令牌 http://licensing.xboxlive.com
Microsoft Entra ID 访问令牌具有受众 URI 值的 Microsoft Store ID 密钥https://onestore.microsoft.com

有关详细信息，请参阅使用 Microsoft Store API 验证您的服务。

此外，要对服务可见的产品需要在合作伙伴中心中进行其他配置，具体取决于服务用于调用 Collections 服务的身份验证类型。请参阅以下内容，了解如何在合作伙伴中心中正确配置产品：

使用用户 Store ID/Microsoft Entra ID 身份验证查看和管理产品所需的其他配置
 使用委派验证 XSTS 令牌查看和管理产品所需的其他配置

注意

如果尚未完成产品配置并通过合作伙伴中心发布，则对集锦的调用将成功，但响应中不会有任何结果。

用户 Microsoft Store ID 身份验证错误代码

代码	错误	内部错误代码	描述
401	未授权	AuthenticationTokenInvalid	Microsoft Entra ID 访问令牌无效。在某些情况下，`ServiceError` 的详细信息包含更多信息，例如令牌到期或 `appid` 声明丢失的时间。
401	未授权	PartnerAadTicketRequired	在授权标头中， Microsoft Entra ID 访问令牌不会传递到服务。
401	未授权	InconsistentClientId	请求正文的 Microsoft Store ID 密钥中的 `clientId` 声明与授权标头的 Microsoft Entra ID 访问令牌中的 `appid` 声明不匹配。

使用 XSTS 令牌进行身份验证时的错误代码

代码	错误	内部错误代码	描述
401	未授权	过期的令牌	XSTS 令牌已过期，需要一个新的令牌才能完成此次调用。
403	未授权	无效的令牌	使用的令牌未被授权通过此端点进行身份验证。令牌可能适用于错误的 Sandboxes（沙盒）或信赖方。
429	节流	调用过于频繁	在指定的调用限制内，为用户调用服务的次数过多。有关您的服务何时可以为该用户再次调用该服务的信息，请参见响应。

请求

请求语法

方法	请求 URI
`POST`	`https://collections.mp.microsoft.com/v8.0/collections/consume`

请求头文件

标头	类型	说明
`Authorization`	`string`	必需。委派的授权 XSTS 令牌或基于正在使用的身份验证类型的 Microsoft Entra ID 访问令牌。
`Signature`	`string`	当使用 XSTS 令牌进行身份验证时为必填项。不需要用户 Microsoft Store ID 身份验证。
`User-Agent`	`string`	可选但建议使用。帮助确定用于登录和调查的服务。
`Host`	`string`	必须设置为值 `collections.mp.microsoft.com`。
`Content-Length`	`number`	请求正文的长度。
`Content-Type`	`string`	指定请求和响应类型。当前，唯一受支持的值为 `application/json`。

请求正文

参数	类型	说明	必需
`beneficiary`	`UserIdentity`	正在使用此项目的用户。有关详细信息，请参阅通过用户 Microsoft Store ID 为电脑游戏进行身份验证。对于 XSTS 令牌身份验证不需要。	仅适用于用户 Microsoft Store ID 身份验证
`trackingId`	`guid`	由开发者提供，用于冗余检查的唯一跟踪 ID。对于每个请求，GUID 都应是唯一的。有关更多信息，请参阅使用 trackingId 验证实现的完成情况。	是
`productId`	`string`	该请求所针对的 Consumable（易耗品）的 `productId`。可从 Partner Center（合作伙伴中心）或通过从服务中查询用户的产品和权利获取。	是
`removeQuantity`	`int`	从用户 Consumable（易耗品）的余量/余额中消耗的数量。	仅适用于 Microsoft Store 托管型 Consumable（易耗品）
`includeOrderIds`	`bool`	包含用于实现此使用请求的订单的 OrderIds 和 LineItemId。然后，这些值可以与 Clawback 事件服务结果一起使用，以识别游戏服务中已退款的消耗交易。	否
`sbx`	`string`	使用 UserStoreIds 进行身份验证的可选值，该值指定应将结果限定到的沙盒。不带此值的默认值为 RETAIL 沙盒。 X 令牌身份验证不需要此值，因为沙盒是在 X 令牌中指定的。	否

使用请求示例

以下示例使用了用户 Microsoft Store ID 身份验证方法，并要求在请求 JSON 正文中使用受益人对象。

Microsoft Store 管理的易耗品

POST https://collections.mp.microsoft.com/v8.0/collections/consume HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1...
Host: collections.mp.microsoft.com
Content-Type: application/json

{
    "beneficiary" : {
        "localTicketReference": "testReference",
        "identityValue": "eyJ0eXAiOiJ...",
        "identitytype": "b2b"
    },
    "productId": "9N0297GK108W",
    "trackingId": "1b3afaa8-8644-40e9-9073-266a3bb8804f",
    "removeQuantity": 1,
    "sandbox": "XDKS.1",
    "includeOrderIds": true
}

开发人员管理的易耗品

POST https://collections.mp.microsoft.com/v8.0/collections/consume HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1...
Content-Type: application/json
Host: collections.md.mp.microsoft.com

{
    "beneficiary" : {
        "localTicketReference" : "testReference",
        "identityValue": "eyJ0eXAiOiJ...",
        "identitytype": "b2b"
    },
    "productId" : "9NBLGGH5WVP6",
    "trackingId" : "08a14c7c-1892-49fc-9135-190ca4f10490",
    "sbx" : "XDKS.1",
    "includeOrderIds": true
}

响应

响应正文

参数	类型	说明	必需
`itemId`	字符串	用于从用户所拥有的其他项目标识此收藏项目的 ID。此 ID 对于每个产品都是唯一的。	是
`productId`	`string`	在 Microsoft Store 目录中也称为产品的 Store ID。产品的示例 Microsoft Store ID 为 9NBLGGH42CFD。	是
`trackingId`	`GUID`	此使用请求的调用方提供的唯一跟踪 ID。	是
`newQuantity`	`int`	此易耗品的用户余额的剩余数量。对于开发人员管理的易耗品，此值始终为 0。	是
`orderTransactions`	`List<ConsumeOrderTransaction>`	ConsumeOrderTransaction 对象的数组，指示用于实现使用请求的订单。仅当请求中的 includeOrderIds 参数设置为 true 时，才会返回此值。有关详细信息，请参阅下表。	否

ConsumeOrderTransaction 对象包含以下参数。

参数	类型	说明	必需
`orderId`	`GUID`	用于全部或部分实现此使用请求的用户采购订单的 ID。	是
`orderLineItemId`	`GUID`	易耗品在用户的采购订单内的行项 ID。对于易耗品采购，此 ID 比 OrderId 更具唯一性，因为每个订单 ID 可以有多个行项目 ID。	是
`quantityConsumed`	`int`	此特定 OrderId/LineItemId 已实现的使用请求量	是

使用响应示例

HTTP/1.1 200 OK
Date: Sat, 04 Sep 2021 01:59:13 GMT
Content-Type: application/json; charset=utf-8
Server: Kestrel
Content-Length: 140
MS-CorrelationId: c7ed3826-c332-4394-af7e-32800e492695
MS-RequestId: 0702fbcf-01ec-4591-995e-13b92149df4d
MS-CV: rJGMXgDq8E2A1EmX.0
X-Content-Type-Options: nosniff
MS-ServerId: 6

{
    "newQuantity": 0,
    "itemId": "c95fef434d1241d6bdb09090b130b6f4",
    "trackingId": "1b3afaa8-8644-40e9-9073-266a3bb8804f",
    "productId": "9N0297GK108W",
    "orderTransactions": [
        {
            "orderId": "8060a406-85c8-4d01-a105-ff11725499c9",
            "orderLineItemId": "cb054aa0-7392-4cc6-af06-53b285e39259",
            "quantityConsumed": 1
        }
    ]
}

管理来自服务的产品

使用 Microsoft Store API 验证您的服务

使用 PublisherQuery（集锦 v9）查询用户的产品和权利。

从服务管理易耗品

管理服务的退款和退单拒付