purchase.mp.microsoft.com/v8.0/purchases/grant
在 Microsoft Store 购买 API 向特定用户授予免费应用程序或加载项(也称为一款应用内产品 或 IAP)。
当前,您仅可以授予免费产品。 如果你的服务尝试授予付费产品,会返回一个错误。
先决条件
注意
目前,购买 API 不支持 XSTS 令牌身份验证。
要使用此 API,需具备以下各项:
- 具有受众 URI 值
https://onestore.microsoft.com
的 Microsoft Entra ID 访问令牌 - 一个代表要向其授予免费产品的用户身份的用户购买 ID 密钥
有关详细信息,请参阅 请求一个用户 Store ID 用于服务间身份验证。
此外,要对服务可见的产品需要在合作伙伴中心中进行其他配置。
有关如何正确配置产品,请参阅使用用户 Store ID/Microsoft Entra ID 身份验证查看和管理产品所需的其他配置。
注意
如果尚未完成产品配置并通过合作伙伴中心发布,则对购买服务的调用将成功,但响应中不会有任何结果。
请求
请求语法
方法 | 请求 URI |
---|---|
POST |
https://purchase.mp.microsoft.com/v7.0/purchases/grant |
请求头文件
标头 | 类型 | 说明 |
---|---|---|
Authorization |
string |
必需。 格式为 Bearer <令牌> 的 Microsoft Entra ID 服务访问令牌。 |
Host |
string |
必须设置为值 purchase.mp.microsoft.com 。 |
Content-Length |
number |
请求正文的长度。 |
Content-Type |
string |
指定请求和响应类型。 当前,唯一受支持的值为 application/json 。 |
请求正文
参数 | 类型 | 说明 | 必需 |
---|---|---|---|
availabilityId |
string |
从 Microsoft Store 目录中授予的产品的可用性 ID。 | 是 |
b2bKey |
string |
代表要向其授予产品的用户的身份的 用户 Store ID 密钥。 | 是 |
devOfferId |
string |
购买后显示在“收藏”项中的开发者指定的优惠 ID。 | 否 |
language |
string |
用户的语言。 | 是 |
market |
string |
用户的市场。 | 是 |
orderId |
GUID |
为订单生成的 GUID。 此值对用户而言是唯一的,但不要求对所有订单都唯一。 | 是 |
productId |
string |
Microsoft Store 目录中的产品 的 Store ID。 产品的示例 Microsoft Store ID 为 9NBLGGH42CFD。 | 是 |
quantity |
int |
要购买的数量。 当前,唯一受支持的值为 1。 如果未指定,默认值为 1。 | 否 |
skuId |
string |
Microsoft Store 目录中的产品 SKU 的 Store ID。 SKU 的示例 Microsoft Store ID 为 0010。 | 是 |
sbx |
string |
使用 UserStoreIds 进行身份验证的可选值,该值指定应将结果限定到的沙盒。 不带此值的默认值为 RETAIL 沙盒。 X 令牌身份验证不需要此值,因为沙盒是在 X 令牌中指定的。 | 否 |
请求示例
POST https://purchase.mp.microsoft.com/v7.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",
"sbx" : "XDKS.1"
}
响应
响应正文
参数 | 类型 | 说明 | 必需 |
---|---|---|---|
clientContext |
ClientContextV8 |
此订单的客户端上下文信息。 这会分配到 Microsoft Entra ID 令牌中的 clientID 值。 | 是 |
createdtime |
datetimeoffset |
创建订单的时间。 | 是 |
currencyCode |
string |
totalAmount 和 totalTaxAmount 的货币代码。 不适用于免费项。 |
是 |
friendlyName |
string |
订单的友好名称。 不适用于通过使用 Microsoft Store 购买 API 生成的订单。 | 是 |
isPIRequired |
boolean |
指示付款方式 (PI) 是否需要作为购买订单的一部分。 | 是 |
language |
string |
订单的语言 ID(例如“en”)。 | 是 |
market |
string |
订单的市场 ID(例如“US”)。 | 是 |
orderId |
string |
标识特定用户的订单的 ID。 | 是 |
orderLineItems |
list<OrderLineItemV8> |
订单的行项列表。 每个订单通常有一个行项。 | 是 |
orderState |
string |
订单的状态。 有效状态为 Editing 、CheckingOut 、Pending 、Purchased 、Refunded 、ChargedBack 和 Canceled 。 |
是 |
orderValidityEndTime |
string |
在提交前,订单定价有效期的结束时间。 不适用于免费应用程序。 | 是 |
orderValidityStartTime |
string |
在提交前,订单定价有效期的开始时间。 不适用于免费应用程序。 | 是 |
purchaser |
IdentityV6 |
描述购买者身份的对象。 | 是 |
totalAmount |
decimal |
订单中所有项的总购买额(含税)。 | 是 |
totalAmountBeforeTax |
decimal |
订单中所有项的总购买额(税前)。 | 是 |
totalChargedToCsvTopOffPI |
decimal |
如果使用单独的付款方式和存储值(逗号分隔值 (CSV)),计入 CSV 的金额。 | 是 |
totalTaxAmount |
decimal |
所有行项的税款总额。 | 是 |
ClientContext
对象包含以下参数。
参数 | 类型 | 说明 | 必需 |
---|---|---|---|
client |
string |
创建订单的客户端 ID。 | 否 |
OrderLineItemV8
对象包含以下参数。
参数 | 类型 | 说明 | 必需 |
---|---|---|---|
agent |
IdentityV8 |
最后编辑行项的代理。 有关此对象的详细信息,请参阅下表。 | 否 |
availabilityId |
string |
从 Microsoft Store 目录中购买的产品的可用性 ID。 | 是 |
beneficiary |
IdentityV8 |
订单受益人的标识。 | 否 |
billingState |
string |
订单的帐单状态。 在完成时,此值设置为 Charged 。 |
否 |
campaignId |
string |
此订单的市场活动 ID。 | 否 |
currencyCode |
string |
用于价格明细的货币代码。 | 是 |
description |
string |
行项的本地化说明。 | 是 |
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。 产品的示例 Microsoft Store ID 为 9NBLGGH42CFD。 | 是 |
productType |
string |
产品的类型。 受支持的值为 Durable 、Application 和 UnmanagedConsumable 。 |
是 |
quantity |
int |
订购项的数量。 | 是 |
retailPrice |
decimal |
订购项的零售价格。 | 是 |
revenueRecognitionState |
string |
收入确认状态。 | 是 |
skuId |
string |
Microsoft Store 目录中的行项的 SKU 的 Store ID。 SKU 的示例 Microsoft Store ID 为 0010。 | 是 |
taxAmount |
decimal |
行项的税额。 | 是 |
taxType |
string |
适用税款的税务类型。 | 是 |
Title |
string |
行项的本地化标题。 | 是 |
totalAmount |
decimal |
行项的总购买额(含税)。 | 是 |
IdentityV8
对象包含以下参数。
参数 | 类型 | 说明 | 必需 |
---|---|---|---|
identityType |
string |
包含值 "pub" 。 |
是 |
identityValue |
string |
指定的用户 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: XfrNWLQlEaux6Mt.8
MS-ServerId: 030032362
Date: Tue, 13 Oct 2019 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 | Microsoft Entra ID 访问令牌无效。 在某些情况下,ServiceError 的详细信息包含更多信息,例如令牌到期或 appid 声明丢失的时间。 |
401 | 未授权 | PartnerAadTicketRequired | 在授权标头中,Microsoft Entra ID 访问令牌未传递到服务。 |
401 | 未授权 | InconsistentClientId | 请求正文中的用户 Store ID 密钥中的 clientId 声明与授权标头中的 Microsoft Entra ID 访问令牌中的 appid 声明不匹配。 |
400 | BadRequest | InvalidParameter | 详细信息包含有关请求正文和具有无效值的字段的信息。 |