使用合作夥伴中心 API 排程新商務訂閱的變更

發行項
07/19/2024

適用於：合作夥伴中心

本文說明如何使用合作夥伴中心 API 來排程新商務訂閱的變更，這些變更只會在續約時進行。此 API 支援新的商務授權型和軟體訂閱。

注意

授權型服務的新商務體驗包含許多新功能，且適用於所有雲端解決方案提供者（CSP）。如需詳細資訊，請參閱新的商務體驗概觀。

建立排程的變更可讓您在下次更新時自動修改訂用帳戶。藉由排程變更，您可以選擇增加或減少授權數目、修改計費期限和頻率，甚至選擇升級 SKU。排程變更可讓您在續約時修改訂用帳戶，而不是在目前期間立即進行修改。

重要

如果您在續約日期之前進行中期（立即）變更，則會刪除先前排定在續約時進行的所有排程變更。

必要條件

認證，如合作夥伴中心驗證所述。此案例支援使用獨立應用程式和 App+使用者認證進行驗證。
客戶識別碼 (customer-tenant-id)。如果您不知道客戶的標識碼，您可以在合作夥伴中心中選取 [客戶] 工作區，然後從客戶清單中查看客戶，然後從 [帳戶]。在客戶的 [帳戶] 頁面上，在 [客戶帳戶資訊] 區段中尋找Microsoft標識碼。 Microsoft 識別碼與客戶識別碼 (customer-tenant-id) 相同。
訂用帳戶標識碼。
訂用帳戶上已啟用自動更新。

合作夥伴中心方法

若要在合作夥伴中心排程訂用帳戶的變更：

選取客戶。
選取您想要排程變更的訂用帳戶。
啟用自動更新。
選取 [ 管理更新]。
對訂閱進行修改，以在續約時進行。
選取 [ 確定 ] 以關閉側邊面板。
選取 [ 提交 ] 以儲存變更。

注意

續約會在字詞的最後一天之後處理，從第二天上午 12：00 UTC 開始。更新會在佇列中處理，最多可能需要 24 小時才能處理。

C#

若要排程客戶的訂用帳戶變更：

依標識碼取得訂用帳戶。
取得已排程轉換資格類型的轉換資格。
建立 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);

若要排程客戶訂用帳戶的變更，其中所需的排程變更是針對不同的產品：

依標識碼取得訂用帳戶。
取得已排程轉換資格類型的轉換資格。
呼叫 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）供應專案：

GetTransitionEligibility 可傳回 CatalogItemID。

a. 請務必設定排程的資格類型，否則預設值為立即。
使用 CatalogItemID 來擷取 availabilityID。

注意

如果您使用 GET Availabilities 來判斷 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: aaaa0000-bb11-2222-33cc-444444dddddd
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: aaaa0000-bb11-2222-33cc-444444dddddd
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"},
}

共用方式為