purchase.mp.microsoft.com/v7.0/purchases/grant

使用 Microsoft Store 购买 API 将免费应用或加载项授予用户帐户。只有免费产品可以直接授予用户帐户。尝试授予付费产品将返回错误。

先决条件

请查看服务到服务 API 的先决条件。此 API 仅支持 Microsoft Entra ID 身份验证类型。如果你未在 Partner Center 中发布产品配置，调用可能成功但不返回任何结果。

请求

请求语法

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

请求标头

标头	类型	说明
`Authorization`	`string`	必需。Microsoft Entra ID 服务访问令牌，格式为 `Bearer` <token>。
`Host`	`string`	必须设置为值 `purchase.mp.microsoft.com`。
`Content-Length`	`number`	请求正文的长度。
`Content-Type`	`string`	指定请求和响应类型。目前唯一支持的值为 `application/json`。

请求正文

参数	类型	说明	必需
`availabilityId`	`string`	Microsoft Store 目录中要授予的产品的可用性 ID。	是
`b2bKey`	`string`	User Store ID 密钥，表示你要为其授予产品的用户的标识。	是
`devOfferId`	`string`	开发者指定的套餐 ID，购买后会显示在收藏项目中。	否
`language`	`string`	用户的语言。	是
`market`	`string`	用户的市场。	是
`orderId`	`GUID`	为订单生成的 GUID。此值对用户而言是唯一的，但不要求在所有订单中唯一。	是
`productId`	`string`	Microsoft Store 目录中产品的 Store ID。产品的 Store ID 示例为 9NBLGGH42CFD。	是
`quantity`	`int`	要购买的数量。目前唯一支持的值为 1。如果未指定，则默认值为 1。	否
`skuId`	`string`	Microsoft Store 目录中产品 SKU 的 Store ID。SKU 的 Store ID 示例为 0010。	是
`sbx`	`string`	使用 UserStoreId 进行身份验证时的可选值，用于指定结果的沙盒范围。如果不提供此值，则默认为 RETAIL 沙盒。X-Token 身份验证不需要此值，因为沙盒已在 X-Token 中指定。	否

请求示例

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。产品的 Store ID 示例为 9NBLGGH42CFD。	是
`productType`	`string`	产品的类型。支持的值为 `Durable`、`Application` 和 `UnmanagedConsumable`。	是
`quantity`	`int`	所订购项目的数量。	是
`retailPrice`	`decimal`	所订购项目的零售价。	是
`revenueRecognitionState`	`string`	收入确认状态。	是
`skuId`	`string`	Microsoft Store 目录中该行项目 SKU 的 Store ID。SKU 的 Store ID 示例为 0010。	是
`taxAmount`	`decimal`	行项目的税额。	是
`taxType`	`string`	适用税款的税种。	是
`Title`	`string`	行项目的本地化标题。	是
`totalAmount`	`decimal`	行项目的含税购买总额。	是

IdentityV8 对象包含以下参数。

参数	类型	说明	必需
`identityType`	`string`	包含值 `"pub"`。	是
`identityValue`	`string`	指定的 User 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	Unauthorized	AuthenticationTokenInvalid	Microsoft Entra ID 访问令牌无效。在某些情况下，ServiceError 的详细信息包含更多信息，例如令牌已过期或缺少 appid 声明。
401	Unauthorized	PartnerAadTicketRequired	未在授权标头中将 Microsoft Entra ID 访问令牌传递给服务。
401	Unauthorized	InconsistentClientId	User Store ID 密钥中的 `clientId` 声明与访问令牌中的 `appid` 不匹配。
400	BadRequest	InvalidParameter	详细信息包含有关请求正文以及哪些字段具有无效值的信息。

从服务管理产品请求用于服务到服务身份验证的 User Store ID 续订 Microsoft Store ID 密钥

Microsoft Store APIs

先决条件

请求

请求语法

请求标头

请求正文

请求示例

响应

响应正文

响应示例

错误代码

相关文章

​先决条件

​请求

​请求语法

​请求标头

​请求正文

​请求示例

​响应

​响应正文

​响应示例

​错误代码

​相关文章

先决条件

请求

请求语法

请求标头

请求正文

请求示例

响应

响应正文

响应示例

错误代码

相关文章