共用方式為

把消耗品報告為已履行

  • 發行項

在 Microsoft Store 集合 API 中使用此方法，針對指定的客戶將消耗性產品回報為已履行。 使用者可以再次購買消耗性產品之前，您的應用程式或服務必須先對該使用者將消耗性產品回報為已履行。

您可以使用此方法將消耗性產品回報為已履行的方式有兩種：

  • 提供消耗性產品的專案識別碼 (如查詢產品中的 itemId 所傳回一樣) 和您提供的唯一追蹤 ID。 如果多次嘗試使用相同的追蹤 ID，即使已耗用該項目，也會傳回相同的結果。 如果您不確定耗用要求是否成功，您的服務應該重新提交具有相同追蹤 ID 的要求。 追蹤 ID 一律會與該取用要求綁定，而且可以無限期重新提交。
  • 提供產品識別碼 (如查詢產品中的 productId 參數所傳回的值)，以及下方要求本文區段中 transactionId 參數描述所列來源之中取得的交易識別碼。

Microsoft.StoreServices 程式庫透過 StoreServicesClient.CollectionsConsumeAsync API 提供此方法的功能。

必要條件

若要使用此方法，您將需要：

  • Azure AD 存取權杖，具有對象 URI 值 https://onestore.microsoft.com。
  • Microsoft Store 識別碼金鑰，代表您想要回報消費性產品為已履行的使用者識別。

如需詳細資訊，請參閱從服務管理產品權利。

Request

要求語法

方法 要求 URI
POST https://collections.mp.microsoft.com/v6.0/collections/consume

要求標頭

標題 類型 描述
授權 字串 必要。 持有人<權杖>形式的 Azure AD 存取權杖。
Host 字串 必須設定為值 collections.mp.microsoft.com。
Content-Length 值 要求本文的長度。
內容-類型 字串 指定要求和回應類型。 目前唯一支援的值是 application/json。

要求本文

參數 類型 描述 必要
beneficiary UserIdentity 正在耗用這個項目的使用者。 如需詳細資訊，請參閱下表。 Yes
itemId 字串 查詢產品所傳回的 itemId 值。 搭配 trackingId 使用此參數 No
trackingId guid 開發人員提供的唯一追蹤 ID。 搭配 itemId 使用此參數。 No
productId 字串 查詢產品所傳回的 productId 值。 搭配 transactionId 使用此參數 No
transactionId guid 從下列其中一個來源取得的交易識別碼值。 搭配 productId 使用此參數。 No

UserIdentity 物件包含下列參數。

參數 類型 描述 必要
identityType 字串 指定字串值 b2b。 Yes
identityValue 字串 Microsoft Store 識別碼金鑰代表您想要回報消費性產品為已履行的使用者識別。 Yes
localTicketReference 字串 傳回回應的要求識別碼。 建議您在 Microsoft Store 識別符金鑰中使用與 userId 宣告 相同的值。 Yes

要求範例

下列範例使用 itemId 和 trackingId。

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

{
    "beneficiary": {
        "localTicketReference": "testreference",
        "identityValue": "eyJ0eXAiOi…..",
        "identityType": "b2b"
    },
    "itemId": "44c26106-4979-457b-af34-609ae97a084f",
    "trackingId": "44db79ca-e31d-49e9-8896-fa5c7f892b40"
}

下列範例使用 productId 和 transactionId。

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

{
    "beneficiary" : {
        "localTicketReference" : "testReference",
        "identityValue" : "eyJ0eXAiOiJ…..",
        "identitytype" : "b2b"
    },
    "productId" : "9NBLGGH5WVP6",
    "transactionId" : "08a14c7c-1892-49fc-9135-190ca4f10490"
}

回應

如果已成功執行使用量，則不會傳回任何內容。

回應範例

HTTP/1.1 204 No Content
Content-Length: 0
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: e488cd0a-9fb6-4c2c-bb77-e5100d3c15b1
MS-CV: 5.1
MS-ServerId: 030011326
Date: Tue, 22 Sep 2015 20:40:55 GMT

錯誤碼

代碼 錯誤 內部錯誤碼 描述
401 未經授權 AuthenticationTokenInvalid Azure AD 存取權杖無效。 在某些情況下，ServiceError 的詳細資料將包含詳細資訊，例如權杖過期或 appid 宣告遺失時。
401 未經授權 PartnerAadTicketRequired Azure AD 存取權杖未傳遞至授權標頭中的服務。
401 未經授權 InconsistentClientId 要求主文中 Microsoft Store 識別碼金鑰中的 clientId 宣告，以及授權標頭中 Azure AD 存取權杖中的 appid 宣告不符。