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

使用 Consume API 來管理下列 Microsoft Store 消耗品類型：

Store 管理的消耗品： 將某個數量回報為已消耗，並從指定使用者的目前數量餘額中移除。使用者可以重複購買 Store 管理的消耗品，而您的服務不需要將它們回報為已消耗或已履行。如需詳細資訊，請參閱 Store 管理的消耗要求。
開發人員管理的消耗品： 為指定的使用者將消耗品產品回報為已履行。在使用者可以再次購買開發人員管理的消耗品產品之前，您的應用程式或服務必須為該使用者將該消耗品產品回報為已履行。如需詳細資訊，請參閱開發人員管理的消耗要求。

使用 `trackingId` 驗證履行完成

trackingId 提供可安全重試的履行驗證。如果您的服務沒有收到確認回應，請重新傳送相同的要求本文。服務會辨識先前的要求，並將重試視為確認檢查。對 API 的每個要求都應該有唯一的 trackingId。如果原始要求未成功，或未收到回應，服務會在重試要求時完成所要求的交易。如果履行已在先前的要求中完成，API 會辨識該要求並傳送確認回應。在此情況下，API 不會第二次履行或從使用者的餘額中扣除。相反地，API 會以成功回應，如同項目已被消耗，並附上使用者的剩餘餘額。因此，請在您的伺服器上或記錄中快取每個要求的值和 trackingId，直到您收到要求已履行的確認回應為止。如需範例，請參閱遊戲服務範例。當您的要求包含 includeOrderIds 參數時，根據消耗品的產品類型，預期會有下列行為：

消耗品類型	第一次消耗要求行為	重試消耗要求行為
Store 管理	傳回用來履行要求的 OrderId	傳回用來履行要求的相同 OrderId
開發人員管理	傳回用來履行要求的 OrderId	不會傳回 OrderID，因為此產品類型不會追蹤此資料

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

必要條件

請檢閱服務對服務 API 的必要條件。此 API 同時支援 Microsoft Entra ID 和委派驗證 X-token 驗證類型。

開發人員管理之消耗品的沙箱限制： 當您在開發沙箱 (非 RETAIL) 中消耗開發人員管理的消耗品產品時，不支援使用 User Store ID 或 Microsoft Entra ID 進行驗證。在沙箱環境中，您必須使用委派授權 XSTS 權杖，才能成功消耗開發人員管理的消耗品產品。此限制不適用於 Store 管理的消耗品或 RETAIL 沙箱。

如果您未在 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 進行驗證。X-token 驗證不需要。	僅適用於 User Store ID 驗證
`trackingId`	`guid`	開發人員提供、用於重複性檢查的唯一 `trackingId`。每個要求的 GUID 都應該是唯一的。如需詳細資訊，請參閱使用 trackingId 驗證履行完成。	是
`productId`	`string`	要求所針對之消耗品的 `productId`。可以從 Partner Center 取得，或透過從服務查詢使用者的產品和權利取得。	是
`removeQuantity`	`int`	要從使用者目前餘額中消耗的數量。	僅適用於 Store 管理的消耗品。
`includeOrderIds`	`bool`	包含用來履行消耗要求之訂單的 OrderId 和 LineItemId。接著可以將這些值與收回事件服務的結果搭配使用，以在您的遊戲服務中識別已退款的消耗交易。	否
`sbx`	`string`	使用 UserStoreIds 進行驗證時的選用值，用來指定結果應限定的沙箱。若沒有此值，預設為 RETAIL 沙箱。X-Token 驗證不需要此值，因為沙箱已在 X-Token 中指定。注意：對於開發人員管理的消耗品，不支援以 `sbx` 參數鎖定開發沙箱的 User Store ID 驗證。請使用 XSTS 權杖驗證對開發人員管理的消耗品進行沙箱測試。	否

消耗要求範例

下列範例使用 User Store ID 進行驗證，並需要在要求 JSON 本文中包含 beneficiary 物件。

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
}

開發人員管理的消耗要求

下列範例使用 User Store ID 驗證。不過，此驗證方法不適用於開發沙箱中開發人員管理的消耗品。如果您在沙箱環境中進行測試，請改用 XSTS 權杖驗證。如需詳細資料，請參閱透過委派驗證 XSTS 權杖進行驗證。

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 所履行的要求數量	是

消耗回應範例

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 (Collections v9) 查詢使用者的產品和權利從您的服務管理消耗品從您的服務管理退款和退單

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

使用 `trackingId` 驗證履行完成

必要條件

User Store ID 驗證錯誤碼

使用 X-token 驗證時的錯誤碼

要求

要求語法

要求標頭

要求本文

消耗要求範例

Store 管理的消耗要求

開發人員管理的消耗要求

回應

回應本文

消耗回應範例

相關文章

​使用 trackingId 驗證履行完成

​必要條件

​User Store ID 驗證錯誤碼

​使用 X-token 驗證時的錯誤碼

​要求

​要求語法

​要求標頭

​要求本文

​消耗要求範例

​Store 管理的消耗要求

​開發人員管理的消耗要求

​回應

​回應本文

​消耗回應範例

​相關文章

使用 `trackingId` 驗證履行完成

必要條件

User Store ID 驗證錯誤碼

使用 X-token 驗證時的錯誤碼

要求

要求語法

要求標頭

要求本文

消耗要求範例

Store 管理的消耗要求

開發人員管理的消耗要求

回應

回應本文

消耗回應範例

相關文章