> ## 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，因為此產品類型不會追蹤此資料 |

如果您使用開發人員管理的消耗品，則無法從重試要求取得訂單識別碼。

## 必要條件

請檢閱[服務對服務 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>

如果您未在 Partner Center 中發佈產品設定，呼叫可能會成功，但不會傳回任何結果。

### 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`。可以從 Partner Center 取得，或透過[從服務查詢使用者的產品和權利](/zh-TW/reference/microsoft-store-apis/xstore-v9-query-for-products)取得。 | 是 |
| `removeQuantity` | `int` | 要從使用者目前餘額中消耗的數量。 | 僅適用於 Store 管理的消耗品。 |
| `includeOrderIds` | `bool` | 包含用來履行消耗要求之訂單的 OrderId 和 LineItemId。接著可以將這些值與[收回事件服務](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 | 將此集合項目與使用者擁有之其他項目區分開來的識別碼。此識別碼對每個產品都是唯一的。 | 是 |
| `productId` | `string` | 也稱為 Microsoft Store 目錄中產品的 Store ID。產品的 Store ID 範例為 9NBLGGH42CFD。 | 是 |
| `trackingId` | `GUID` | 呼叫端為消耗要求提供的唯一 `trackingId`。 | 是 |
| `newQuantity` | `int` | 使用者此消耗品產品餘額的剩餘數量。對於開發人員管理的消耗品，此值為 0。 | 是 |
| `orderTransactions` | `List<ConsumeOrderTransaction>` | ConsumeOrderTransaction 物件的陣列，指出用來履行要求的訂單。只有在要求中將 `includeOrderIds` 參數設定為 true 時才會傳回。如需詳細資訊，請參閱下表。 | 否 |

`ConsumeOrderTransaction` 物件包含下列參數。

| 參數 | 類型 | 描述 | 必要 |
| - | - | - | - |
| `orderId` | `GUID` | 用來履行全部或部分消耗要求之使用者購買訂單的識別碼。 | 是 |
| `orderLineItemId` | `GUID` | 消耗品在使用者所下購買訂單中所屬明細項目的識別碼。此識別碼比 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) 查詢使用者的產品和權利](/zh-TW/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

- [collections.mp.microsoft.com/v8.0/collections/consume](/reference/microsoft-store-apis/xstore-v8-consume.md)
- [Microsoft Store service APIs](/reference/microsoft-store-apis/xstore-nav.md)
- [APIs de servicio de Microsoft Store](/es/reference/microsoft-store-apis/xstore-nav.md)
- [Managing consumable products from your service](/publishing/xstore-commerce/xstore-managing-consumables.md)
- [Microsoft Store 服务 API](/zh-CN/reference/microsoft-store-apis/xstore-nav.md)