Microsoft商業市集上的 SaaS 履行訂用帳戶 API v2

發行項
06/14/2024

本文說明 SaaS 履行訂用帳戶 API 第 2 版。

注意

若要能夠呼叫 SaaS 履行訂用帳戶 API，您必須使用正確的資源識別碼來建立發行者的授權令牌。瞭解如何取得發行者的授權令牌

解決已購買的訂用帳戶

解析端點可讓發行者將購買識別令牌從商業市集交換（稱為已購買但尚未啟動的令牌），以持續購買的 SaaS 訂用帳戶標識碼及其詳細數據。

當客戶重新導向至合作夥伴的登陸頁面 URL 時，客戶識別令牌會傳遞為 此 URL 呼叫中的令牌 參數。合作夥伴應該使用此令牌，並提出解析它的要求。解析 API 回應包含 SaaS 訂用帳戶標識碼和其他詳細數據，可唯一識別購買。 提供登陸頁面 URL 呼叫的令牌有效期為 24 小時。 如果您收到的令牌已過期，建議您提供下列指引給終端使用者：

“我們無法識別此購買。在 Azure 入口網站或 Microsoft 365 系統管理中心重新開啟此 SaaS 訂用帳戶，然後再次選取 [設定帳戶] 或 [管理帳戶]。

呼叫解析 API 會傳回所有支持狀態中 SaaS 訂用帳戶的訂用帳戶詳細數據和狀態。

發佈 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>`

查詢參數：

參數	值
`ApiVersion`	使用 2018-08-31。

要求標頭：

參數	值
`content-type`	`application/json`
`x-ms-requestid`	從客戶端追蹤要求的唯一字串值，最好是 GUID。如果未提供此值，則會在響應標頭中產生並提供一個值。
`x-ms-correlationid`	用戶端上作業的唯一字串值。此參數會將來自用戶端作業的所有事件與伺服器端上的事件相互關聯。如果未提供此值，則會在響應標頭中產生並提供一個值
`authorization`	識別發出此 API 呼叫之發行者的唯一存取令牌。格式是`"Bearer <access_token>"`當發行者擷取令牌值時，如根據 Microsoft Entra 應用程式取得令牌中所述。
`x-ms-marketplace-token`	要解析的購買識別令牌參數。當客戶重新導向至 SaaS 合作夥伴的網站時，令牌會在登陸頁面 URL 呼叫中傳遞（例如： `https://contoso.com/signup?token=<token><authorization_token>`。要編碼的令牌值是登陸頁面 URL 的一部分，因此必須先譯碼，才能在此 API 呼叫中當做參數使用。以下是 URL 中編碼字串的範例： `contoso.com/signup?token=ab%2Bcd%2Fef`，其中 token 為 `ab%2Bcd%2Fef`。相同的令牌譯碼為： `Ab+cd/ef`

回應碼：

程序代碼：200 根據提供的傳回唯一 x-ms-marketplace-token SaaS 訂用帳戶標識碼。

回應本文範例：

{
  "id": "<guid>", // purchased SaaS subscription ID
  "subscriptionName": "Contoso Cloud Solution", // SaaS subscription name
  "offerId": "offer1", // purchased offer ID
  "planId": "silver", // purchased offer's plan ID
  "quantity": 20, // number of purchased seats, might be empty if the plan is not per seat
  "subscription": { // full SaaS subscription details, see Get Subscription APIs response body for full description
    "id": "<guid>",
    "publisherId": "contoso",
    "offerId": "offer1",
    "name": "Contoso Cloud Solution",
    "saasSubscriptionStatus": " PendingFulfillmentStart ",
    "beneficiary": {
      "emailId": "test@test.com",
      "objectId": "<guid>",
      "tenantId": "<guid>",
      "puid": "<ID of the user>"
    },
    "purchaser": {
      "emailId": "test@test.com",
      "objectId": "<guid>",
      "tenantId": "<guid>",
      "puid": "<ID of the user>"
    },
    "planId": "silver",
    "term": {
      "termUnit": "P1M",
      "startDate": "2022-03-07T00:00:00Z", //This field is only available after the saas subscription is active.
      "endDate": "2022-04-06T00:00:00Z" //This field is only available after the saas subscription is active.
    },
      "autoRenew": true/false,
    "isTest": true/false,
    "isFreeTrial": false,
    "allowedCustomerOperations": <CSP purchases>["Read"] <All Others> ["Delete", "Update", "Read"],
      "sandboxType": "None",
      "lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
      "quantity": 5,
    "sessionMode": "None"
  }
}

程序代碼：400 不正確的要求。 x-ms-marketplace-token 遺失、格式不正確、無效或過期。

代碼：403 禁止。授權令牌無效、過期或未提供。要求嘗試存取以不同Microsoft Entra 應用程式標識符發行之供應專案的 SaaS 訂用帳戶，該供應專案與用來建立授權令牌的供應專案。

此錯誤通常是未正確執行 SaaS 註冊的徵兆。

程式代碼：500 內部伺服器錯誤。重試 API 呼叫。如果錯誤持續發生，請連絡 Microsoft支持人員。

啟用訂用帳戶

為終端使用者設定 SaaS 帳戶之後，發行者必須在Microsoft端呼叫啟動訂用帳戶 API。除非此 API 呼叫成功，否則不會向客戶收費。

發佈 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>`

查詢參數：

參數	值
`ApiVersion`	使用 2018-08-31。
`subscriptionId`	所購買 SaaS 訂用帳戶的唯一標識碼。使用解析 API 解析商業市集授權令牌之後，會取得此標識碼。

要求標頭：

參數	值
`content-type`	`application/json`
`x-ms-requestid`	從客戶端追蹤要求的唯一字串值，最好是 GUID。如果未提供此值，則會在響應標頭中產生並提供一個值。
`x-ms-correlationid`	用戶端上作業的唯一字串值。此字串會將客戶端作業中的所有事件與伺服器端上的事件相互關聯。如果未提供此值，則會在響應標頭中產生並提供一個值。
`authorization`	識別發出此 API 呼叫之發行者的唯一存取令牌。格式是`"Bearer <access_token>"`當發行者擷取令牌值時，如根據 Microsoft Entra 應用程式取得令牌中所述。

回應碼：

程序代碼：200 更新訂閱的要求，並標示為「已訂閱」。獨立軟體供應商（ISV）可以在幾分鐘后檢查訂用帳戶的狀態（查看取得作業以檢查訂用帳戶狀態）。這可讓您明確回答是否已成功更新訂用帳戶。無法訂閱會自動傳送「取消訂閱」Webhook。

此呼叫沒有回應本文。

程序代碼：400 不正確的要求：驗證失敗。

SaaS 訂用帳戶處於暫停狀態。

此錯誤通常是未正確執行 SaaS 註冊的徵兆。

程序代碼：404 找不到。 SaaS 訂用帳戶處於 未訂閱 狀態。

程式代碼：500 內部伺服器錯誤。重試 API 呼叫。如果錯誤持續發生，請連絡 Microsoft支持人員。

取得所有訂用帳戶的清單

此 API 會針對發行者在商業市集中發佈的所有供應專案，擷取所有已購買的 SaaS 訂用帳戶清單。會傳回所有可能狀態的 SaaS 訂用帳戶。也會傳回未訂閱的 SaaS 訂用帳戶，因為此資訊不會在Microsoft端刪除。

API 會傳回每頁 100 個分頁結果。

獲取 `https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>`

查詢參數：

參數	值
`ApiVersion`	使用 2018-08-31。
`continuationToken`	選擇性的參數。若要擷取結果的第一頁，請保留空白。使用參數中 `@nextLink` 傳回的值來擷取下一頁。

要求標頭：

參數	值
`content-type`	`application/json`
`x-ms-requestid`	從客戶端追蹤要求的唯一字串值，最好是 GUID。如果未提供此值，則會在響應標頭中產生並提供一個值。
`x-ms-correlationid`	用戶端上作業的唯一字串值。此參數會將來自用戶端作業的所有事件與伺服器端上的事件相互關聯。如果未提供此值，則會在響應標頭中產生並提供一個值。
`authorization`	識別發出此 API 呼叫之發行者的唯一存取令牌。格式是`"Bearer <access_token>"`當發行者擷取令牌值時，如根據 Microsoft Entra 應用程式取得令牌中所述。

回應碼：

程序代碼：200 根據發行者的授權令牌，傳回此發行者所提供之所有供應專案之所有現有訂閱的清單。

回應本文範例：

{
  "subscriptions": [
    {
      "id": "<guid>", // purchased SaaS subscription ID
      "name": "Contoso Cloud Solution", // SaaS subscription name
      "publisherId": "contoso", // publisher ID
      "offerId": "offer1", // purchased offer ID
      "planId": "silver", // purchased plan ID
      "quantity": 10, // purchased amount of seats, is empty if plan is not per seat
      "beneficiary": { // email address, user ID and tenant ID for which SaaS subscription was purchased.
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "purchaser": { // email address, user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) purchase
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "term": { // The period for which the subscription was purchased.
        "startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
        "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
        "termUnit": "P1M" // where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values
      },
      "autoRenew": true,
      "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
      "sessionMode": "None", // not relevant
      "isFreeTrial": true, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. (Optional field -– if not returned, the value is false.)
      "isTest": false, // not relevant
      "sandboxType": "None", // not relevant
      "saasSubscriptionStatus": "Subscribed" // Indicates the status of the operation. Can be one of the following: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
    },
    // next SaaS subscription details, might be a different offer
    {
      "id": "<guid1>",
      "name": "Contoso Cloud Solution1",
      "publisherId": "contoso",
      "offerId": "offer2",
      "planId": "gold",
      "quantity": "",
      "beneficiary": {
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "purchaser": {
        "emailId": "purchase@csp.com ",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "term": {
        "startDate": "2019-05-31", /This field is only available after the saas subscription is active.
        "endDate": "2020-04-30",  //This field is only available after the saas subscription is active.
        "termUnit": "P1Y"
      },
      "autoRenew": false,
      "allowedCustomerOperations": ["Read"],
      "sessionMode": "None",
      "isFreeTrial": false,
      "isTest": false,
      "sandboxType": "None",
      "saasSubscriptionStatus": "Suspended"
    }
  ],
  "@nextLink": "https:// https://marketplaceapi.microsoft.com/api/saas/subscriptions/?continuationToken=%5b%7b%22token%22%3a%22%2bRID%3a%7eYeUDAIahsn22AAAAAAAAAA%3d%3d%23RT%3a1%23TRC%3a2%23ISV%3a1%23FPC%3aAgEAAAAQALEAwP8zQP9%2fFwD%2b%2f2FC%2fwc%3d%22%2c%22range%22%3a%7b%22min%22%3a%22%22%2c%22max%22%3a%2205C1C9CD673398%22%7d%7d%5d&api-version=2018-08-31" // url that contains continuation token to retrieve next page of the SaaS subscriptions list, if empty or absent, this is the last page. ISV can use this url as is to retrieve the next page or extract the value of continuation token from this url.
}

如果找不到此發行者的已購買 SaaS 訂用帳戶，則會傳回空的回應本文。

代碼：403 禁止。授權令牌無法使用、無效或已過期。

此錯誤通常是未正確執行 SaaS 註冊的徵兆。

程式代碼：500 內部伺服器錯誤。重試 API 呼叫。如果錯誤持續發生，請連絡 Microsoft支持人員。

取得訂用帳戶

此 API 會針對發行者在商業市集中發佈的 SaaS 供應專案，擷取指定的已購買 SaaS 訂用帳戶。使用此呼叫依標識碼取得特定 SaaS 訂用帳戶的所有可用資訊，而不是呼叫用來取得所有訂用帳戶清單的 API。

獲取 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

查詢參數：

參數	值
`ApiVersion`	使用 2018-08-31。
`subscriptionId`	所購買 SaaS 訂用帳戶的唯一標識碼。使用解析 API 解析商業市集授權令牌之後，會取得此標識碼。

要求標頭：

參數	值
`content-type`	`application/json`
`x-ms-requestid`	從客戶端追蹤要求的唯一字串值，最好是 GUID。如果未提供此值，則會在響應標頭中產生並提供一個值。
`x-ms-correlationid`	用戶端上作業的唯一字串值。此參數會將來自用戶端作業的所有事件與伺服器端上的事件相互關聯。如果未提供此值，則會在響應標頭中產生並提供一個值。
`authorization`	識別發出此 API 呼叫之發行者的唯一存取令牌。格式是`"Bearer <access_token>"`當發行者擷取令牌值時，如根據 Microsoft Entra 應用程式取得令牌中所述。

回應碼：

程序代碼：200 根據 subscriptionId 提供的傳回 SaaS 訂用帳戶的詳細數據。

回應本文範例：

{
  "id": "<guid>", // purchased SaaS subscription ID
  "name": "Contoso Cloud Solution", // SaaS subscription name
  "publisherId": "contoso", // publisher ID
  "offerId": "offer1", // purchased offer ID
  "planId": "silver", // purchased plan ID
  "quantity": 10, // purchased amount of seats is empty if plan is not per seat
  "beneficiary": { // email address, user ID and tenant ID for which SaaS subscription is purchased.
    "emailId": "test@contoso.com",
    "objectId": "<guid>",
    "tenantId": "<guid>",
    "puid": "<ID of the user>"
  },
  "purchaser": { // email address ,user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) scenario
    "emailId": "test@test.com",
    "objectId": "<guid>",
    "tenantId": "<guid>",
    "puid": "<ID of the user>"
  },
  "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
  "sessionMode": "None", // not relevant
  "isFreeTrial": false, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. Optional field – if not returned the value is false.
  "autoRenew": true,
  "isTest": false, // not relevant
  "sandboxType": "None", // not relevant
  "created": "2022-03-01T22:59:45.5468572Z",
     "lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
  "saasSubscriptionStatus": " Subscribed ", // Indicates the status of the operation: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
  "term": { // the period for which the subscription was purchased
    "startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
    "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
    "termUnit": "P1M" //where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values.
  }
}

此錯誤通常是未正確執行 SaaS 註冊的徵兆。

程序代碼：404 找不到。找不到具有指定 subscriptionId 之的 SaaS 訂用帳戶。

程式代碼：500 內部伺服器錯誤。重試 API 呼叫。如果錯誤持續發生，請連絡 Microsoft支持人員。

列出可用的方案

此 API 會擷取此供應專案的特定購買所 subscriptionId 識別之 SaaS 供應專案的所有方案。使用此呼叫來取得 SaaS 訂用帳戶的受益者可以更新訂用帳戶的所有私人和公用方案清單。傳回的方案可在與已購買的方案相同的地理位置中取得。

此呼叫會傳回該客戶除了已購買的方案外，還傳回可供該客戶使用的方案清單。清單可以呈現給發行者網站上的使用者。終端使用者可以將訂用帳戶方案變更為傳回清單中任何一個方案。將計劃變更為不在清單中的方案無法運作。

此 API 也會擷取相關聯的使用中私人供應專案識別碼（如果您使用 planId 篩選呼叫 API）。使用 planId 篩選來呼叫 API 時，會在 sourceOffers 節點的回應本文中顯示作用中的私人供應專案標識符 GUID。傳入篩選參數的 planId 應該符合客戶購買的 planId。

獲取 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>`

查詢參數：

參數	值
`ApiVersion`	使用 2018-08-31。
`subscriptionId`	所購買 SaaS 訂用帳戶的唯一標識碼。使用解析 API 解析商業市集授權令牌之後，會取得此標識碼。
`planId (Optional)`	您想要擷取之特定方案的方案標識碼。這是選擇性的，如果忽略則會傳回所有計劃。

要求標頭：

參數	值
`content-type`	`application/json`
`x-ms-requestid`	從客戶端追蹤要求的唯一字串值，最好是 GUID。如果未提供此值，則會在響應標頭中產生並提供一個值。
`x-ms-correlationid`	用戶端上作業的唯一字串值。此參數會將來自用戶端作業的所有事件與伺服器端上的事件相互關聯。如果未提供此值，則會在響應標頭中產生並提供一個值。
`authorization`	識別發出此 API 呼叫之發行者的唯一存取令牌。格式是`"Bearer <access_token>"`當發行者擷取令牌值時，如根據 Microsoft Entra 應用程式取得令牌中所述。

回應碼：

程序代碼：200 傳回現有 SaaS 訂用帳戶的所有可用方案清單，包括已購買的方案。

傳遞無效的（選擇性） planId 會傳回空的計劃清單。

回應本文範例：

{
  "plans": [
    {
      "planId": "Platinum001",
      "displayName": "plan display name",
      "isPrivate": true, //returns true for private plans and customized plans created within a private offer.
      "description": "plan description",
      "minQuantity": 5,
      "maxQuantity": 100,
      "hasFreeTrials": false,
      "isPricePerSeat": true,
      "isStopSell": false,
      "market": "US",
      "planComponents": {
        "recurrentBillingTerms": [
          {
            "currency": "USD",
            "price": 1,
            "termUnit": "P1M",
            "termDescription": "term description",
            "meteredQuantityIncluded": [
              {
                "dimensionId": "Dimension001",
                "units": "Unit001"
              }
            ]
          }
        ],
        "meteringDimensions": [
          {
            "id": "MeteringDimension001",
            "currency": "USD",
            "pricePerUnit": 1,
            "unitOfMeasure": "unitOfMeasure001",
            "displayName": "unit of measure display name"
          }
        ]
      },
      "sourceOffers": [ //sourceOffers is returned when planId is passed as filter parameter (note that this is the plan that customer has purchased).
        {
          "externalId": "<guid>" //private offer id, returned when purchase is made through private offer.
        }
      ]
    }
  ]
}

程序代碼：找不到 404。找不到 subscriptionId。

代碼：403 禁止。授權令牌無效、過期或未提供。要求可能會嘗試存取未訂閱或以與用來建立授權令牌之供應專案不同的Microsoft Entra 應用程式標識碼發佈的供應專案 SaaS 訂用帳戶。

此錯誤通常是未正確執行 SaaS 註冊的徵兆。

程式代碼：500 內部伺服器錯誤。重試 API 呼叫。如果錯誤持續發生，請連絡 Microsoft支持人員。

變更訂用帳戶上的方案

使用此 API，將針對 SaaS 訂用帳戶購買的現有方案更新為新方案（公開或私人）。當在發行者端變更在商業市集中購買的 SaaS 訂閱時，發行者必須呼叫此 API。

此 API 只能針對作用中訂用帳戶呼叫。任何方案都可以變更為任何其他現有的方案（公用或私人），但不能變更為本身。針對私人方案，客戶的租用戶必須在合作夥伴中心內定義為方案的一部分。

補丁 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

查詢參數：

參數	值
`ApiVersion`	使用 2018-08-31。
`subscriptionId`	所購買 SaaS 訂用帳戶的唯一標識碼。使用解析 API 解析商業市集授權令牌之後，會取得此標識碼。

要求標頭：

參數	值
`content-type`	`application/json`
`x-ms-requestid`	從客戶端追蹤要求的唯一字串值，最好是 GUID。如果未提供此值，則會在響應標頭中產生並提供一個值。
`x-ms-correlationid`	用戶端上作業的唯一字串值。此參數會將來自用戶端作業的所有事件與伺服器端上的事件相互關聯。如果未提供此值，則會在響應標頭中產生並提供一個值。
`authorization`	識別發出此 API 呼叫之發行者的唯一存取令牌。格式是`"Bearer <access_token>"`當發行者擷取令牌值時，如根據 Microsoft Entra 應用程式取得令牌中所述。

要求承載範例：

{
  "planId": "gold" // the ID of the new plan to be purchased
}

回應碼：

程序代碼：202 已接受並異步處理變更計劃的要求。合作夥伴應該輪詢 Operation-Location URL ，以判斷變更計劃要求的成功或失敗。輪詢應該每隔幾秒鐘執行一次，直到作業收到失敗、成功或衝突的最終狀態為止。 最終作業狀態應該很快傳回，但在某些情況下可能需要幾分鐘的時間。

當動作準備好在商業市集端成功完成時，合作夥伴也會收到 Webhook 通知。只有這樣，發行者才會在發行者端進行方案變更。

回應標頭：

參數	值
`Operation-Location`	取得作業狀態的 URL。例如，`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`

程序代碼：400 不正確的要求：驗證失敗。

新方案不存在或不適用於此特定 SaaS 訂用帳戶。
新方案與目前的方案相同。
SaaS 訂用帳戶狀態未訂閱。
SaaS 訂用帳戶的更新作業不包含在中 allowedCustomerOperations。

此錯誤通常是未正確執行 SaaS 註冊的徵兆。

程序代碼：404 找不到。找不到的 SaaS 訂用 subscriptionId 帳戶。

程式代碼：500 內部伺服器錯誤。重試 API 呼叫。如果錯誤持續發生，請連絡 Microsoft支持人員。

注意

方案或基座數量可以一次變更，而不是兩者。

只有在使用者取得變更的明確核准之後，才能呼叫此 API。

變更 SaaS 訂用帳戶的基座數量

使用此 API 來更新針對 SaaS 訂用帳戶購買的基座數量（增加或減少）。當發行者從商業市集中建立的 SaaS 訂閱的發行者端變更基座數目時，發行者必須呼叫此 API。

基座數量不能超過目前方案中允許的數量。在此情況下，發行者應該先變更方案，再變更基座數量。

補丁 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

查詢參數：

參數	值
`ApiVersion`	使用 2018-08-31。
`subscriptionId`	已購買 SaaS 訂用帳戶的唯一標識碼。使用解析 API 解析商業市集授權令牌之後，會取得此標識碼。

要求標頭：

參數	值
`content-type`	`application/json`
`x-ms-requestid`	從客戶端追蹤要求的唯一字串值，最好是 GUID。如果未提供此值，則會在響應標頭中產生並提供一個值。
`x-ms-correlationid`	用戶端上作業的唯一字串值。此參數會將來自用戶端作業的所有事件與伺服器端上的事件相互關聯。如果未提供此值，則會在響應標頭中產生並提供一個值。
`authorization`	識別發出此 API 呼叫之發行者的唯一存取令牌。格式是`"Bearer <access_token>"`當發行者擷取令牌值時，如根據 Microsoft Entra 應用程式取得令牌中所述。

要求承載範例：

{
  "quantity": 5 // the new amount of seats to be purchased
}

回應碼：

程序代碼：202 已接受並異步處理變更數量的要求。合作夥伴應該輪詢 Operation-Location URL ，以判斷變更數量要求的成功或失敗。輪詢應該每隔幾秒鐘執行一次，直到作業收到失敗、成功或衝突的最終狀態為止。 最終作業狀態應該很快傳回，但在某些情況下可能需要幾分鐘的時間。

當動作準備好在商業市集端成功完成時，合作夥伴也會收到 Webhook 通知。只有這樣，發行者才會在發行者端進行數量變更。

回應標頭：

參數	值
`Operation-Location`	連結至資源以取得作業的狀態。例如： `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31` 。

程序代碼：400 不正確的要求：驗證失敗。

新數量大於或低於目前的計劃限制。
遺漏新的數量。
新的數量與目前的數量相同。
SaaS 訂用帳戶狀態未訂閱。
SaaS 訂用帳戶的更新作業不包含在中 allowedCustomerOperations。

代碼：403 禁止。授權令牌無效、過期或未提供。要求嘗試存取不屬於目前發行者的訂用帳戶。

此錯誤通常是未正確執行 SaaS 註冊的徵兆。

程序代碼：404 找不到。找不到的 SaaS 訂用 subscriptionId 帳戶。

程式代碼：500 內部伺服器錯誤。重試 API 呼叫。如果錯誤持續發生，請連絡 Microsoft支持人員。

注意

一次只能變更方案或數量，而不是兩者。

只有在使用者取得變更的明確核准之後，才能呼叫此 API。

取消訂用帳戶

使用此 API 取消訂閱指定的 SaaS 訂用帳戶。發行者不需要使用此 API，建議您將客戶導向至商業市集，以取消 SaaS 訂用帳戶。

如果發行者決定在發行者端的商業市集中實作取消購買的 SaaS 訂閱，則必須呼叫此 API。完成此呼叫之後，訂用帳戶的狀態會在 Microsoft端變成 [取消訂閱 ]。

如果訂閱在購買后的72小時內取消，則不會向客戶收取費用。

如果訂用帳戶在上述寬限期之後取消，則會向客戶收取費用。客戶在取消后立即失去Microsoft端 SaaS 訂用帳戶的存取權。

刪除 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

查詢參數：

參數	值
`ApiVersion`	使用 2018-08-31。
`subscriptionId`	所購買 SaaS 訂用帳戶的唯一標識碼。使用解析 API 解析商業市集授權令牌之後，會取得此標識碼。

要求標頭：

參數	值
`content-type`	`application/json`
`x-ms-requestid`	從客戶端追蹤要求的唯一字串值，最好是 GUID。如果未提供此值，則會在響應標頭中產生並提供一個值。
`x-ms-correlationid`	用戶端上作業的唯一字串值。此參數會將來自用戶端作業的所有事件與伺服器端上的事件相互關聯。如果未提供此值，則會在響應標頭中產生並提供一個值。
`authorization`	識別發出此 API 呼叫之發行者的唯一存取令牌。格式是`"Bearer <access_token>"`當發行者擷取令牌值時，如根據 Microsoft Entra 應用程式取得令牌中所述。

回應碼：

程序代碼：202 已接受並異步處理取消訂閱的要求。合作夥伴應該輪詢 Operation-Location URL ，以判斷此要求的成功或失敗。輪詢應該每隔幾秒鐘執行一次，直到作業收到失敗、成功或衝突的最終狀態為止。 最終作業狀態應該很快傳回，但在某些情況下可能需要幾分鐘的時間。

合作夥伴也會在商業市集端成功完成動作時收到 Webhook 通知。只有在發行者取消發行者端的訂閱時，發行者才會取消。

程序代碼：200 訂用帳戶已處於未訂閱狀態。

回應標頭：

參數	值
`Operation-Location`	連結至資源以取得作業的狀態。例如： `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31` 。

程序代碼：400 不正確的要求。此 SaaS 訂用帳戶的刪除不在 allowedCustomerOperations 清單中。

代碼：403 禁止。授權令牌無效、過期或無法使用。

此錯誤通常是未正確執行 SaaS 註冊的徵兆。

程序代碼：404 找不到。找不到的 SaaS 訂用 subscriptionId 帳戶。

程序代碼：409

無法完成刪除，因為訂用帳戶因為擱置作業而鎖定。

程式代碼：500 內部伺服器錯誤。重試 API 呼叫。如果錯誤持續發生，請連絡 Microsoft支持人員。

如需商業市集中 SaaS 供應專案的詳細資訊，請參閱商業市集計量服務 API
檢閱和使用不同程式設計語言和範例的用戶端
如需測試指引，請參閱在 SaaS 服務上實作 Webhook

共用方式為

Microsoft商業市集上的 SaaS 履行訂用帳戶 API v2

解決已購買的訂用帳戶

發佈 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>`

啟用訂用帳戶

發佈 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>`

取得所有訂用帳戶的清單

獲取 `https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>`

取得訂用帳戶

獲取 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

列出可用的方案

獲取 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>`

變更訂用帳戶上的方案

補丁 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

變更 SaaS 訂用帳戶的基座數量

補丁 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

取消訂用帳戶

刪除 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

意見反應

其他資源

共用方式為

Microsoft商業市集上的 SaaS 履行訂用帳戶 API v2

解決已購買的訂用帳戶

發佈 https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>

啟用訂用帳戶

發佈 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>

取得所有訂用帳戶的清單

獲取 https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>

取得訂用帳戶

獲取 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

列出可用的方案

獲取 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>

變更訂用帳戶上的方案

補丁 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

變更 SaaS 訂用帳戶的基座數量

補丁 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

取消訂用帳戶

刪除 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

相關內容

意見反應

其他資源

發佈 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>`

發佈 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>`

獲取 `https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>`

獲取 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

獲取 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>`

補丁 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

補丁 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

刪除 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`