> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Microsoft Store v8 Collections consume API，用于在游戏服务中将 Store 管理与开发者管理的可消耗产品从用户余额中报告为已消耗。

使用 Consume API 管理以下 Microsoft Store 可消耗产品类型：

* **Store 管理的可消耗产品：** 将数量报告为已消耗，并将其从指定用户的当前数量余额中扣除。
  用户可以反复重新购买 Store 管理的可消耗产品，而你的服务无需将其报告为已消耗或已履行。
  有关详细信息，请参阅 [Store 管理的消耗请求](#store-managed-consume-request)。

* **开发者管理的可消耗产品：** 将可消耗产品报告为已为指定用户履行。
  在用户可以重新购买开发者管理的可消耗产品之前，你的应用或服务必须将该可消耗产品报告为已为该用户履行。
  有关详细信息，请参阅[开发者管理的消耗请求](#developer-managed-consume-request)。

## 使用 `trackingId` 验证履行完成

`trackingId` 提供可重试安全的履行验证。
如果你的服务未收到确认响应，请重新发送相同的请求正文。
服务会识别先前的请求，并将重试视为确认检查。

对 API 的每个请求都应有唯一的 `trackingId`。
如果原始请求未成功，或未收到响应，则在重试请求时服务会完成所请求的事务。
如果履行是在先前的请求中完成的，API 会识别该请求并发送确认响应。
在这种情况下，API 不会第二次履行或从用户的余额中扣除。
相反，API 会响应成功，就好像该项目已用用户的剩余余额消耗一样。

因此，请在服务器或日志中缓存每个请求的值和 `trackingId`，直到收到请求已履行的确认响应。
有关示例，请参阅[游戏服务示例](https://aka.ms/gdkdl)。

当你的请求包含 `includeOrderIds` 参数时，根据可消耗产品的类型，预期行为如下：

| 可消耗产品类型  | 首次消耗请求行为          | 重试消耗请求行为                  |
| -------- | ----------------- | ------------------------- |
| Store 管理 | 返回用于履行请求的 OrderId | 返回用于履行请求的相同 OrderId       |
| 开发者管理    | 返回用于履行请求的 OrderId | 不返回 OrderID，因为此产品类型不跟踪此数据 |

如果你使用开发者管理的可消耗产品，则无法从重试请求获取订单 ID。

## 先决条件

请查看[服务到服务 API 的先决条件](https://learn.microsoft.com/reference/service-to-service-nav#prerequisites-for-service-to-service-apis)。

此 API 同时支持 Microsoft Entra ID 和委托身份验证 X-token 身份验证类型。

<Info>**开发者管理的可消耗产品的沙盒限制：** 在开发沙盒（非 RETAIL）中消耗开发者管理的可消耗产品时，不支持使用 User Store ID 或 Microsoft Entra ID 进行身份验证。在沙盒环境中，必须使用委托授权 XSTS 令牌才能成功消耗开发者管理的可消耗产品。此限制不适用于 Store 管理的可消耗产品或 RETAIL 沙盒。</Info>

如果你未在合作伙伴中心发布产品配置，调用可能成功但不返回任何结果。

### User Store ID 身份验证错误代码

| 代码  | 错误           | 内部错误代码                     | 说明                                                                                           |
| --- | ------------ | -------------------------- | -------------------------------------------------------------------------------------------- |
| 401 | Unauthorized | AuthenticationTokenInvalid | Microsoft Entra ID 访问令牌无效。在某些情况下，`ServiceError` 的详细信息包含更多信息，例如令牌过期或缺少 `appid` 声明。            |
| 401 | Unauthorized | PartnerAadTicketRequired   | 未在授权标头中将 Microsoft Entra ID 访问令牌传递给服务。                                                       |
| 401 | Unauthorized | InconsistentClientId       | 请求正文中的 Microsoft Store ID 密钥中的 `clientId` 声明与授权标头中的 Microsoft Entra ID 访问令牌中的 `appid` 声明不匹配。 |

### 使用 X-token 身份验证的错误代码

| 代码  | 错误           | 内部错误代码             | 说明                                                 |
| --- | ------------ | ------------------ | -------------------------------------------------- |
| 401 | Unauthorized | Expired Token      | X-token 已过期，需要新的 X-token 才能完成调用。                   |
| 403 | Unauthorized | Invalid Token      | 使用的令牌未被授权与此终结点进行身份验证。令牌可能针对错误的沙盒或依赖方。              |
| 429 | Throttled    | Too frequent calls | 服务在指定的调用限制内为该用户调用次数过多。有关服务何时可以为该用户再次调用服务的信息，请参阅响应。 |

## 请求

### 请求语法

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

### 请求标头

| 标头               | 类型       | 说明                                                       |
| ---------------- | -------- | -------------------------------------------------------- |
| `Authorization`  | `string` | 必需。根据所使用的身份验证类型，为委托授权 X-token 或 Microsoft Entra ID 访问令牌。 |
| `Signature`      | `string` | 使用 X-token 进行身份验证时必需。对于 User Store ID 身份验证不需要。           |
| `User-Agent`     | `string` | 可选但建议使用。有助于识别你的服务以便记录和调查。                                |
| `Host`           | `string` | 必须设置为值 `collections.mp.microsoft.com`。                   |
| `Content-Length` | `number` | 请求正文的长度。                                                 |
| `Content-Type`   | `string` | 指定请求和响应类型。目前唯一支持的值是 `application/json`。                  |

### 请求正文

| 参数                | 类型             | 说明                                                                                                                                                                                                                       | 必需                      |
| ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- |
| `beneficiary`     | `UserIdentity` | 为其消耗此项目的用户。有关详细信息，请参阅[使用 Microsoft Entra ID 和 User Store ID 进行身份验证](https://learn.microsoft.com/reference/xstore-authenticating-your-service#authenticating-with-microsoft-entra-id-and-user-store-ids)。X-token 身份验证不需要。 | 仅对 User Store ID 身份验证需要 |
| `trackingId`      | `guid`         | 由开发者提供的唯一 `trackingId`，用于冗余检查。每个请求的 GUID 都应唯一。有关详细信息，请参阅[使用 trackingId 验证履行完成](#using-trackingid-to-validate-fulfillment-completion)。                                                                                    | 是                       |
| `productId`       | `string`       | 请求所针对的可消耗产品的 `productId`。可从合作伙伴中心或通过[从服务查询用户的产品和授权](/reference/microsoft-store-apis/xstore-v9-query-for-products)获取。                                                                                                     | 是                       |
| `removeQuantity`  | `int`          | 要从用户当前余额中消耗的数量。                                                                                                                                                                                                          | 仅适用于 Store 管理的可消耗产品。    |
| `includeOrderIds` | `bool`         | 包括用于履行消耗请求的订单的 OrderId 和 LineItemId。这些值随后可与 [Clawback 事件服务](https://learn.microsoft.com/reference/xstore-managing-refunds-and-chargebacks)结果一起使用，以识别游戏服务中已退款的消耗事务。                                                       | 否                       |
| `sbx`             | `string`       | 使用 UserStoreIds 进行身份验证时的可选值，用于指定结果应作用于的沙盒。若无此值，默认为 RETAIL 沙盒。X-Token 身份验证不需要此值，因为沙盒已在 X-Token 中指定。**注意：** 对于开发者管理的可消耗产品，不支持将 `sbx` 参数指向开发沙盒的 User Store ID 身份验证。请使用 XSTS 令牌身份验证来对开发者管理的可消耗产品进行沙盒测试。                      | 否                       |

### 消耗请求示例

以下示例使用 User Store ID 进行身份验证，并要求在请求 JSON 正文中包含 beneficiary 对象。

#### Store 管理的消耗请求

```syntax theme={null}
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
}
```

#### 开发者管理的消耗请求

<Note>以下示例使用 User Store ID 身份验证。但是，此身份验证方法在开发沙盒中的开发者管理的可消耗产品上不起作用。如果你在沙盒环境中进行测试，请改用 XSTS 令牌身份验证。有关详细信息，请参阅[通过委托身份验证 XSTS 令牌进行身份验证](https://learn.microsoft.com/reference/xstore-authenticating-your-service#authenticating-with-delegated-authentication-x-tokens)。</Note>

```syntax theme={null}
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`            | string                          | 用于将集合项与用户拥有的其他项区分开的 ID。此 ID 对于每个产品是唯一的。                                                          | 是  |
| `productId`         | `string`                        | 也称为 Microsoft Store 目录中产品的 Store ID。产品的 Store ID 示例为 9NBLGGH42CFD。                               | 是  |
| `trackingId`        | `GUID`                          | 由调用方为消耗请求提供的唯一 `trackingId`。                                                                     | 是  |
| `newQuantity`       | `int`                           | 该可消耗产品的用户余额剩余数量。对于开发者管理的可消耗产品，值为 0。                                                              | 是  |
| `orderTransactions` | `List<ConsumeOrderTransaction>` | ConsumeOrderTransaction 对象的数组，指示用于履行请求的订单。仅当请求中将 `includeOrderIds` 参数设置为 true 时才返回。有关详细信息，请参阅下表。 | 否  |

`ConsumeOrderTransaction` 对象包含以下参数。

| 参数                 | 类型     | 说明                                                                            | 必需 |
| ------------------ | ------ | ----------------------------------------------------------------------------- | -- |
| `orderId`          | `GUID` | 用于全部或部分履行消耗请求的用户购买订单的 ID。                                                     | 是  |
| `orderLineItemId`  | `GUID` | 用户在购买订单中该可消耗产品的行项目 ID。此 ID 比 OrderId 对可消耗购买更唯一，因为每个 OrderID 可以有多个 LineItemId。 | 是  |
| `quantityConsumed` | `int`  | 此特定 OrderId / LineItemId 履行的请求数量                                              | 是  |

### 消耗响应示例

```syntax theme={null}
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
        }
    ]
}
```

## 相关文章

[从你的服务管理产品](https://learn.microsoft.com/reference/service-to-service-nav)

[使用 Microsoft Store API 验证你的服务](https://learn.microsoft.com/reference/xstore-authenticating-your-service)

[使用 publisherQuery (Collections v9) 查询用户的产品和授权](/reference/microsoft-store-apis/xstore-v9-query-for-products)

[从你的服务管理可消耗产品](https://learn.microsoft.com/reference/xstore-managing-consumables-and-refunds)

[从你的服务管理退款和拒付](https://learn.microsoft.com/reference/xstore-managing-refunds-and-chargebacks)


## Related topics

- [Microsoft Store 服务 API](/zh-CN/reference/microsoft-store-apis/xstore-nav.md)
- [从你的服务管理消耗品产品](/zh-CN/publishing/xstore-commerce/xstore-managing-consumables.md)
- [collections.mp.microsoft.com/v9.0/collections/publisherQuery](/zh-CN/reference/microsoft-store-apis/xstore-v9-query-for-products.md)
- [Microsoft Store v8 Collections b2bLicensePreview API](/zh-CN/reference/microsoft-store-apis/xstore-v8-query-for-products.md)
- [purchase.mp.microsoft.com/v8.0/b2b/orders/query](/zh-CN/reference/microsoft-store-apis/xstore-v8-clawbackv1.md)