通过

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 详细信息包含有关请求正文和具有无效值的字段的信息。

管理来自服务的产品

请求用户 Store ID 用于服务间身份验证。

更新 Microsoft Store ID 密钥