授與免費產品

  • 發行項

在 Microsoft Store 購買 API 中使用此方法，將免費應用程式或附加元件 (也稱為應用程式內產品或 IAP) 授與指定使用者。

目前，您只能授與免費產品。 如果您的服務嘗試使用此方法來授與非免費產品，這個方法會傳回錯誤。

必要條件

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

  • Azure AD 存取權杖，具有對象 URI 值 https://onestore.microsoft.com。
  • Microsoft Store ID 金鑰，代表您要授與免費產品之使用者的身分識別。

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

要求

要求語法

方法 要求 URI
POST https://purchase.mp.microsoft.com/v6.0/purchases/grant

要求標頭

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

要求本文

參數 類型 描述 必要
availabilityId 字串 要從 Microsoft Store 目錄授與之產品的可用性識別碼。 是
b2bKey 字串 Microsoft Store ID 金鑰，代表您要授與產品之使用者的身分識別。 是
devOfferId 字串 開發人員指定的供應項目識別碼，會在購買後出現在集合項目中。
language 字串 使用者的語言。 是
market 字串 使用者的市場。 是
orderId guid 針對訂單產生的 GUID。 此值對使用者而言是唯一的，但不需要在所有訂單中都是唯一的。 是
productId 字串 Microsoft Store 目錄中產品的 Store ID。 產品的範例 Store ID 為 9NBLGGH42CFD。 是
數量 int 要購買的數量。 目前唯一支援的值是 1。 若未加以指定，預設為 1。 否
skuId 字串 Microsoft Store 目錄中 SKU 的 Store ID。 SKU 的範例 Store ID 為 0010。 是

要求範例

POST https://purchase.mp.microsoft.com/v6.0/purchases/grant HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJK……
Content-Length: 1863
Content-Type: application/json

{
    "b2bKey" : "eyJ0eXAiOiJK……",
    "availabilityId" : "9RT7C09D5J3W",
    "productId" : "9NBLGGH5WVP6",
    "skuId" : "0010",
    "language" : "en-us",
    "market" : "us",
    "orderId" : "3eea1529-611e-4aee-915c-345494e4ee76",
}

回應

回應本文

參數 類型 描述 必要
clientContext ClientContextV6 此訂單的用戶端內容資訊。 會將此從 Azure AD 權杖指派至 clientID 值。 是
createdtime datetimeoffset 建立訂單的時間。 是
currencyCode 字串 totalAmount 和 totalTaxAmount 的貨幣代碼。 不適用於免費項目。 是
friendlyName 字串 訂單的易記名稱。 不適用於使用 Microsoft Store 購買 API 所下的訂單。 是
isPIRequired 布林值 指出是否需要付款方式 (PI) 作為採購單的一部分。 是
language 字串 訂單的語言識別碼 (例如 “en”)。 是
market 字串 訂單的市場識別碼 (例如 “US”)。 是
orderId 字串 識別特定使用者訂單的識別碼。 是
orderLineItems list<OrderLineItemV6> 訂單的明細項目清單。 一般而言，每個訂單都有 1 個明細項目。 是
orderState 字串 訂單的縣/市。 有效狀態為 Editing、CheckingOut、Pending、Purchased、Refunded、ChargedBack 和 Cancelled。 是
orderValidityEndTime 字串 訂單定價在提交之前的最後一次有效時間。 不適用於免費應用程式。 是
orderValidityStartTime 字串 訂單定價在提交之前的第一次有效時間。 不適用於免費應用程式。 是
purchaser IdentityV6 描述購買者身分識別的物件。 是
totalAmount decimal 訂單中所有項目的購買總金額，包括稅金。 是
totalAmountBeforeTax decimal 訂單中所有項目的稅前購買總金額。 是
totalChargedToCsvTopOffPI decimal 如果使用個別的付款方式和預存值 (CSV)，則是向 CSV 收取的金額。 是
totalTaxAmount decimal 所有明細項目的稅金總額。 是

ClientContext 物件包含下列參數。

參數 類型 描述 必要
用戶端 字串 建立訂單的用戶端識別碼。 否

OrderLineItemV6 物件包含下列參數。

參數 類型 描述 必要
代理程式 IdentityV6 上次編輯明細項目的專員。 如需此物件的詳細資訊，請參閱下表。 否
availabilityId 字串 要從 Microsoft Store 目錄購買之產品的可用性識別碼。 是
beneficiary IdentityV6 訂單受益者的身分識別。 否
billingState 字串 訂單的計費狀態。 完成時，這會設定為 Charged。 否
campaignId 字串 此訂單的行銷活動識別碼。 否
currencyCode 字串 用於價格詳細資料的貨幣代碼。 是
描述 字串 明細項目的當地語系化描述。 是
devofferId 字串 特定訂單的供應項目識別碼，如果有的話。 否
fulfillmentDate datetimeoffset 履行發生的日期。 否
fulfillmentState 字串 此項目的履行狀態。 完成時，這會設定為 Fulfilled。 否
isPIRequired 布林值 指出此明細項目是否需要付款方式。 是
isTaxIncluded 布林值 指出項目定價詳細資料中是否包含稅金。 是
legacyBillingOrderId 字串 舊版計費識別碼。 否
lineItemId 字串 此訂單中項目的明細項目識別碼。 是
listPrice decimal 此訂單中項目的標價。 是
productId 字串 代表 Microsoft Store 目錄中明細項目的產品Store ID。 產品的範例 Store ID 為 9NBLGGH42CFD。 是
productType 字串 產品的類型。 支援的值為 Durable、Application 和 UnmanagedConsumable。 是
數量 int 訂購的項目數量。 是
retailPrice decimal 已訂購項目的零售價格。 是
revenueRecognitionState 字串 收入確認狀態。 是
skuId 字串 Microsoft Store 目錄中明細項目的 SKUStore ID。 SKU 的範例 Store ID 為 0010。 是
taxAmount decimal 明細項目的稅額。 是
taxType 字串 適用稅金的稅金類型。 是
標題 字串 明細項目的當地語系化標題。 是
totalAmount decimal 明細項目的購買總金額，包括稅金。 是

IdentityV6 物件包含下列參數。

參數 類型 描述 必要
identityType 字串 包含值 "pub"。 是
identityValue 字串 來自指定 Microsoft Store ID 金鑰 publisherUserId 的字串值。 是

回應範例

Content-Length: 1203
Content-Type: application/json
MS-CorrelationId: fb2e69bc-f26a-4aab-a823-7586c19f5762
MS-RequestId: c1bc832c-f742-47e4-a76c-cf061402f698
MS-CV: XjfuNWLQlEuxj6Mt.8
MS-ServerId: 030032362
Date: Tue, 13 Oct 2015 21:21:51 GMT

{
    "clientContext": {
        "client": "86b78998-d05a-487b-b380-6c738f6553ea"
    },
    "createdTime": "2015-10-13T21:21:51.1863494+00:00",
    "currencyCode": "USD",
    "isPIRequired": false,
    "language": "en-us",
    "market": "us",
    "orderId": "3eea1529-611e-4aee-915c-345494e4ee76",
    "orderLineItems": [{
        "availabilityId": "9RT7C09D5J3W",
        "beneficiary": {
            "identityType": "pub",
            "identityValue": "user1"
        },
        "billingState": "Charged",
        "currencyCode": "USD",
        "description": "Jewels, Jewels, Jewels - Consumable 2",
        "fulfillmentDate": "2015-10-13T21:21:51.639478+00:00",
        "fulfillmentState": "Fulfilled",
        "isPIRequired": false,
        "isTaxIncluded": true,
        "lineItemId": "2814d758-3ee3-46b3-9671-4fb3bdae9ffe",
        "listPrice": 0.0,
        "payments": [],
        "productId": "9NBLGGH5WVP6",
        "productType": "UnmanagedConsumable",
        "quantity": 1,
        "retailPrice": 0.0,
        "revenueRecognitionState": "None",
        "skuId": "0010",
        "taxAmount": 0.0,
        "taxType": "NoApplicableTaxes",
        "title": "Jewels, Jewels, Jewels - Consumable 2",
        "totalAmount": 0.0
    }],
    "orderState": "Purchased",
    "orderValidityEndTime": "2015-10-14T21:21:51.1863494+00:00",
    "orderValidityStartTime": "2015-10-13T21:21:51.1863494+00:00",
    "purchaser": {
        "identityType": "pub",
        "identityValue": "user1"
    },
    "testScenarios": "None",
    "totalAmount": 0.0,
    "totalTaxAmount": 0.0
}

錯誤碼

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