免費授予產品

發行項
03/24/2024

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

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

必要條件

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

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

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

Request

要求語法

方法	要求 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 目錄中明細項目的 SKU Store 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: aaaa0000-bb11-2222-33cc-444444dddddd
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	詳細資料包含要求本文的相關資訊，以及哪些欄位具有無效的值。

共用方式為

免費授予產品

必要條件

Request

要求語法

要求標頭

要求本文

要求範例

回應

回應本文

回應範例

錯誤碼

意見反應

其他資源

共用方式為

免費授予產品

必要條件

Request

要求語法

要求標頭

要求本文

要求範例

回應

回應本文

回應範例

錯誤碼

相關主題

意見反應

其他資源