使用合作伙伴中心 API 计划新商业订阅的更改

项目
06/20/2024

适用于：合作伙伴中心

本文介绍如何使用合作伙伴中心 API 为仅在续订时发生的新商业订阅计划更改。此 API 支持基于商业许可的新订阅和软件订阅。

注意

基于许可证的服务的新商业体验涵盖许多新功能，可供所有云解决方案提供商 (CSP) 使用。有关详细信息，请参阅新商业体验概述。

创建计划更改后，可以在下次续订时自动修改订阅。通过计划更改，可以选择增加或减少许可证数量、修改计费期限和频率，甚至选择升级 SKU。计划更改允许你在续订时对订阅进行修改，而不是在当前期限内立即进行修改。

重要

如果在续订日期之前进行了中期（即时）更改，将删除以前计划在续订时进行的所有计划更改。

先决条件

合作伙伴中心身份验证中所述的凭据。此方案支持使用独立应用和 App+User 凭据进行身份验证。
客户 ID (customer-tenant-id)。如果不知道客户的 ID，可以通过选择“客户”工作区，然后从客户列表中选择客户，然后选择“帐户”，在合作伙伴中心中查找该 ID。在客户的“帐户”页上，在“客户帐户信息”部分查找Microsoft ID。 Microsoft ID 与客户 ID (customer-tenant-id) 相同。
订阅 ID。
在订阅上启用自动续订。

合作伙伴中心方法

若要在合作伙伴中心为订阅计划更改，请执行以下操作：

选择客户。
选择要为其计划更改的订阅。
启用自动续订。
选择“管理续订”。
对订阅进行修改，以在续订时进行。
选择“确定”关闭侧面板。
选择“ 提交 ”以保存更改。

注意

续订在期限的最后一天之后处理，从第二天上午 12：00 UTC 开始。续订在队列中处理，可能需要长达 24 小时才能处理。

C#

若要计划客户的订阅更改，请执行以下操作：

按 ID 获取订阅。
获取计划的转换资格类型的转换资格。
创建 ScheduledNextTermInstructions 对象并将其设置为订阅的属性。
调用 Patch（） 方法，使用计划的更改更新订阅。

var selectedSubscription = subscriptionOperations.Get();
selectedSubscription.ScheduledNextTermInstructions = new ScheduledNextTermInstructions
{
    Product = new ProductTerm
    {
        ProductId = changeToProductId,
        SkuId = changeToSkuId,
        AvailabilityId = changeToAvailabilityId,
        BillingCycle = changeToBillingCycle,
        TermDuration = changeToTermDuration,
    },
    Quantity = changeToQuantity,
    customTermEndDate = DateTime,
};
var updatedSubscription = subscriptionOperations.Patch(selectedSubscription);

若要为客户的订阅计划更改，所需计划的更改是针对其他产品：

按 ID 获取订阅。
获取计划的转换资格类型的转换资格。
调用 Patch（） 方法，使用计划的更改更新订阅。

REST 请求

请求语法

方法	请求 URI
PATCH	{baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{subscription-id} HTTP/1.1

URI 参数

下表列出了调用 API 所需的查询参数。

名称	类型	必需	说明
customer-tenant-id	guid	Y	对应于客户的 GUID。
subscription-id	guid	Y	对应于订阅的 GUID。

请求标头

有关详细信息，请参阅合作伙伴中心 REST 标头。

请求正文

请求正文中需要完整的订阅资源，并 scheduledNextTermInstructions 定义了属性。若要计划订阅的更改，请确保 AutoRenewEnabled 属性设置为 true。

有关销售结束时与转换（EndofSaleWithConversions）产品/服务的可用性 ID：

GetTransitionEligibility 返回 CatalogItemID。

a. 请确保设置计划的资格类型，否则默认值为即时。
使用 CatalogItemID 提取 availabilityID。

注意

如果使用 GET 可用性来确定 scheduledNextTerm 指令的可用性，并且所有术语均为 EOS 状态，则会收到空列表。确定有效路径的最佳方式是调用 GetTransitionEligibilty API 以返回有效选项。

字段	类型	必需	说明
scheduledNextTermInstructions	object	Y	定义订阅的下一个术语说明。该属性包含 `product` 对象和 `quantity` 字段。

请求示例

PATCH https://api.partnercenter.microsoft.com/v1/customers/<customer-tenant-id>/subscriptions/<subscription-id> HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: ca7c39f7-1a80-43bc-90d8-ee7d1cad3831
MS-CorrelationId: ec8f62e5-1d92-47e9-8d5d-1924af105f2c
If-Match: <etag>
Content-Type: application/json
Content-Length: 1029
Expect: 100-continue
Connection: Keep-Alive

{
    "id": "6e7aa601-629e-461b-8933-0898c3cc3c7c",
    "offerId": "DZH318Z0BXWC:0001:DZH318Z0BMJX",
    "offerName": "offer Name",
    "friendlyName": "friendly Name",
    "quantity": 1,
    "customTermEndDate": "2019-01-09T00:21:45.9263727",
    "unitType": "License(s)",
    "hasPurchasableAddons": false,
    "creationDate": "2019-01-04T01:00:12.6647304Z",
    "effectiveStartDate": "2019-01-09T00:21:45.9263727+00:00",
    "commitmentEndDate": "2019-02-08T00:21:45.9263727+00:00",
    "status": "active",
    "autoRenewEnabled": true,
    "scheduledNextTermInstructions": { 
      "product": { 
         "productId":  "DG7GMGF0DVSV", 
         "skuId":  "000P", 
         "availabilityId":  "DG7GMGF0F3Q9", 
         "billingCycle":  "Annual", 
         "termDuration":  "P3Y",
         "promotionId": "39NFJQT1PFPJ:000H:39NFJQT1Q5DK"
        }, 
      "quantity":  1 
      "customTermEndDate" : "2019-01-09T00:21:45.9263727",
     },  // original value = null 
    "isTrial": false,
    "billingType": "license",
    "billingCycle": "monthly",
    "termDuration": "P1M",
    "refundOptions": [{
        "type": "Full",
        "expiresAt": "2019-01-10T00:21:45.9263727+00:00"
    }],
    "isMicrosoftProduct": false,
    "partnerId": "",
    "contractType": "subscription",
    "publisherName": "publisher Name",
    "orderId": "ImxjLNL4_fOc-2KoyOxGTZcrlIquzls11",
    "attributes": {"objectType": "Subscription"},
}

REST 响应

如果请求成功，此方法在响应正文中返回更新的订阅资源属性。

响应的成功和错误代码

每个响应都附带一个 HTTP 状态代码，用于指示成功或失败以及其他调试信息。使用网络跟踪工具读取此代码、错误类型和其他参数。有关完整列表，请参阅错误代码。

响应示例

HTTP/1.1 200 OK
Content-Length: 1322
Content-Type: application/json; charset=utf-8
MS-RequestId: ca7c39f7-1a80-43bc-90d8-ee7d1cad3831
MS-CorrelationId: ec8f62e5-1d92-47e9-8d5d-1924af105f2c
X-Locale: en-US

{
    "id": "6e7aa601-629e-461b-8933-0898c3cc3c7c",
    "offerId": "DZH318Z0BXWC:0001:DZH318Z0BMJX",
    "offerName": "offer Name",
    "friendlyName": "friendly Name",
    "quantity": 1,
    "customTermEndDate": "2019-01-09T00:21:45.9263727",
    "unitType": "License(s)",
    "hasPurchasableAddons": false,
    "creationDate": "2019-01-04T01:00:12.6647304Z",
    "effectiveStartDate": "2019-01-09T00:21:45.9263727+00:00",
    "commitmentEndDate": "2019-02-08T00:21:45.9263727+00:00",
    "status": "active",
    "autoRenewEnabled": true,
    "scheduledNextTermInstructions": { 
      "product": { 
         "productId":  "DG7GMGF0DVSV", 
         "skuId":  "000P", 
         "availabilityId":  "DG7GMGF0F3Q9", 
         "billingCycle":  "Annual", 
         "termDuration":  "P3Y",
         "promotionId": "39NFJQT1PFPJ:000H:39NFJQT1Q5DK"
        }, 
      "quantity":  1 
      "customTermEndDate": "2019-01-09T00:21:45.9263727",
     },  // original value = null 
    "isTrial": false,
    "billingType": "license",
    "billingCycle": "monthly",
    "termDuration": "P1M",
    "refundOptions": [{
        "type": "Full",
        "expiresAt": "2019-01-10T00:21:45.9263727+00:00"
    }],
    "isMicrosoftProduct": false,
    "partnerId": "",
    "contractType": "subscription",
    "publisherName": "publisher Name",
    "orderId": "ImxjLNL4_fOc-2KoyOxGTZcrlIquzls11",
    "attributes": {"objectType": "Subscription"},
}

通过