授予免费产品

项目
07/13/2023

在 Microsoft Store 购买 API 中使用此方法，可向给定用户授予免费应用或加载项（也称为应用内产品或 IAP）。

当前，你仅可以授予免费产品。如果你的服务尝试使用此方法授予付费产品，此方法会返回一个错误。

先决条件

若要使用此方法，你需要：

受众 URI 值为 https://onestore.microsoft.com 的 Azure AD 访问令牌。
代表要向其授予免费产品的用户的身份的 Microsoft Store ID 密钥。

有关详细信息，请参阅管理来自服务的产品授权。

请求

请求语法

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

请求头

标头	类型	说明
授权	字符串	必需。 Azure AD 访问令牌的格式为 Bearertoken<>。
主机	string	必须设置为值 purchase.mp.microsoft.com。
Content-Length	数值	请求正文的长度。
Content-Type	字符串	指定请求和响应类型。当前，唯一受支持的值为 application/json。

请求正文

参数	类型	描述	必须
availabilityId	string	从 Microsoft Store 目录中授予的产品的可用性 ID。	是
b2bKey	string	代表要向其授予产品的用户的身份的 Microsoft Store ID 密钥。	是
devOfferId	string	购买后显示在“集合”项中的开发人员指定的优惠 ID。
语言	字符串	用户的语言。	是
market	string	用户的市场。	是
orderId	guid	为订单生成的 GUID。此值对用户而言是唯一的，但不要求对所有订单都唯一。	是
productId	string	Microsoft Store 目录中的产品的 Store ID。产品的示例应用商店 ID 为 9NBLGGH42CFD。	是
quantity	int	要购买的数量。当前，唯一受支持的值为 1。如果未指定，则默认值为 1。	否
skuId	string	Microsoft Store 目录中的产品 SKU 的 Store ID。 SKU 的示例应用商店 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	string	totalAmount 和 totalTaxAmount 的货币代码。不适用于免费项目。	是
friendlyName	字符串	订单的友好名称。不适用于使用 Microsoft Store 购买 API 生成的订单。	是
isPIRequired	boolean	指示付款方式 (PI) 是否需要作为购买订单的一部分。	是
语言	字符串	订单的语言 ID（例如“en”）。	是
market	string	订单的市场 ID（例如“US”）。	是
orderId	string	标识特定用户的订单的 ID。	是
orderLineItems	list<OrderLineItemV6>	订单的行项列表。每个订单通常有 1 个行项。	是
orderState	string	订单的状态。有效状态为 Editing、CheckingOut、Pending、Purchased、Refunded、ChargedBack 和 Cancelled。	是
orderValidityEndTime	string	在提交前，订单定价有效期的结束时间。不适用于免费应用。	是
orderValidityStartTime	string	在提交前，订单定价有效期的开始时间。不适用于免费应用。	是
购买者	IdentityV6	描述购买者标识的对象。	是
totalAmount	Decimal	订单中所有项的总购买额（含税）。	是
totalAmountBeforeTax	Decimal	订单中所有项的总购买额（税前）。	是
totalChargedToCsvTopOffPI	Decimal	如果使用单独的付款方式 (PI) 和存储值 (CSV)，金额将从 CSV 中扣除。	是
totalTaxAmount	Decimal	所有行项的税款总额。	是

ClientContext 对象包含以下参数。

参数	类型	描述	必须
客户端	string	创建订单的客户端 ID。	否

OrderLineItemV6 对象包含以下参数。

参数	类型	描述	必须
代理	IdentityV6	最后编辑行项的代理。有关此对象的详细信息，请参阅下表。	否
availabilityId	string	从 Microsoft Store 目录中购买的产品的可用性 ID。	是
受益人	IdentityV6	订单的受益人标识。	否
billingState	string	订单的帐单状态。在完成时，此值设置为 Charged。	否
campaignId	string	此订单的市场活动 ID。	否
currencyCode	string	用于显示价格明细的货币代码。	是
description	字符串	行项的本地化说明。	是
devofferId	string	特定订单的优惠 ID（如果存在）。	否
fulfillmentDate	datetimeoffset	完成日期。	否
fulfillmentState	string	此项的完成状态。在完成时，此值设置为 Fulfilled。	否
isPIRequired	boolean	指示此行项是否需要付款方式。	是
isTaxIncluded	boolean	指示税款是否包括在项目的价格明细中。	是
legacyBillingOrderId	string	传统的帐单 ID。	否
lineItemId	string	此订单中项目的行项 ID。	是
listPrice	Decimal	此订单中项目的价目表。	是
productId	string	表示 Microsoft Store 目录中的行项的产品的 Store ID。产品的示例应用商店 ID 为 9NBLGGH42CFD。	是
productType	string	产品的类型。支持的值包括 Durable、Application 和 UnmanagedConsumable。	是
quantity	int	订购项的数量。	是
retailPrice	Decimal	订购项的零售价格。	是
revenueRecognitionState	string	收入识别状态。	是
skuId	string	Microsoft Store 目录中的行项的 SKU 的 Store ID。 SKU 的示例应用商店 ID 为 0010。	是
taxAmount	Decimal	行项的税额。	是
taxType	string	适用税款的税款类型。	是
标题	字符串	行项的本地化标题。	是
totalAmount	Decimal	行项的总购买额（含税）。	是

IdentityV6 对象包含以下参数。

参数	类型	描述	必须
IdentityType	string	包含值“pub”。	是
identityValue	string	指定的 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	详细信息包含有关请求正文和具有无效值的字段的信息。

通过

授予免费产品

先决条件

请求

请求语法

请求头

请求正文

请求示例

响应

响应正文

响应示例

错误代码

反馈

其他资源

通过

授予免费产品

先决条件

请求

请求语法

请求头

请求正文

请求示例

响应

响应正文

响应示例

错误代码

相关主题

反馈

其他资源