Microsoft商业市场中的 SaaS 履行订阅 API v2

项目
01/31/2025

本文介绍 SaaS 履行订阅 API 版本 2。

注意

若要能够调用 SaaS 履行订阅 API，必须使用正确的资源 ID 创建发布者的授权令牌。了解如何获取发布者的授权令牌

解决已购买的订阅

解析终结点使发布者能够将购买标识令牌从商业市场（称为令牌购买但尚未激活）交换到永久购买的 SaaS 订阅 ID 及其详细信息。

当客户重定向到合作伙伴的登陆页 URL 时，客户标识令牌将作为此 URL 调用中的令牌参数传递。合作伙伴应使用此令牌并发出解析请求。解析 API 响应包含 SaaS 订阅 ID 和其他详细信息，用于唯一标识购买。登陆页 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 合作伙伴的网站（例如：`https://contoso.com/signup?token=<token><authorization_token>`），令牌将传递到登陆页 URL 调用中。要编码的令牌值是登陆页面 URL 的一部分，因此需要先对其进行解码，然后再将其用作此 API 调用中的参数。下面是 URL 中编码字符串的示例：`contoso.com/signup?token=ab%2Bcd%2Fef`，其中令牌`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 缺失、格式不正确、无效或已过期。

代码：401 未授权。授权令牌无效或已过期。请求尝试访问已发布的套餐的 SaaS 订阅，该套餐与用于创建身份验证令牌的项应用 ID 不同Microsoft条目应用 ID。

代码：403 禁止。授权令牌无效，未提供或提供权限不足。请确保提供有效的授权令牌。

此错误通常是未正确执行 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解析商业市场授权令牌后，将获取此 ID。

请求标头：

参数	价值
`content-type`	`application/json`
`x-ms-requestid`	用于跟踪来自客户端的请求的唯一字符串值，最好是 GUID。如果未提供此值，则会在响应标头中生成并提供一个值。
`x-ms-correlationid`	客户端上操作的唯一字符串值。此字符串将客户端操作中的所有事件与服务器端的事件相关联。如果未提供此值，则会在响应标头中生成并提供一个值。
`authorization`	用于标识发出此 API 调用的发布者的唯一访问令牌。发布者检索令牌值时，格式 `"Bearer <access_token>"`，如获取基于 Microsoft Entra 应用的令牌中所述。

响应代码：

代码：200 请求更新订阅并标记为“已订阅”。独立软件供应商（ISV）可以在几分钟后检查订阅的状态（阅读获取操作以检查订阅状态）。这为你提供了是否成功更新订阅的明确答案。订阅失败会自动发送“取消订阅”Webhook。

此调用没有响应正文。

代码：400 错误的请求：验证失败。

SaaS 订阅处于暂停状态。

代码：403 禁止。授权令牌无效，未提供或提供权限不足。请确保提供有效的授权令牌。

此错误通常是未正确执行 SaaS 注册的症状。

代码：404 找不到。 SaaS 订阅处于 未订阅 状态。

代码：500 内部服务器错误。重试 API 调用。如果错误仍然存在，请联系 Microsoft支持。

获取所有订阅的列表

此 API 检索发布者在商业市场中发布的所有产品/服务的所有已购买 SaaS 订阅的列表。返回所有可能状态的 SaaS 订阅。还会返回未订阅的 SaaS 订阅，因为此信息不会在Microsoft端删除。

API 返回分页结果，必须传递 continuationToken 以获取后续结果。

获取 `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 订阅。使用此调用通过 ID 获取特定 SaaS 订阅的所有可用信息，而不是调用用于获取所有订阅列表的 API。

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

查询参数：

参数	价值
`ApiVersion`	使用 2018-08-31。
`subscriptionId`	购买的 SaaS 订阅的唯一标识符。使用解析 API 解析商业市场授权令牌后，会获取此 ID。

请求标头：

参数	价值
`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.
  }
}

代码：403 禁止。授权令牌无效，未提供或提供权限不足。请确保提供有效的授权令牌。

此错误通常是未正确执行 SaaS 注册的症状。

代码：404 找不到。找不到具有指定 subscriptionId 的 SaaS 订阅。

代码：500 内部服务器错误。重试 API 调用。如果错误仍然存在，请联系 Microsoft支持。

列出可用计划

此 API 检索由特定购买产品/服务的 subscriptionId 标识的 SaaS 产品/服务的所有计划。使用此调用可获取 SaaS 订阅的受益者可更新订阅的所有专用和公共计划的列表。返回的计划与已购买的计划位于同一地理位置。

除了已购买的计划外，此调用还会返回该客户可用的计划列表。该列表可以提供给发布者网站上的最终用户。最终用户可以将订阅计划更改为返回列表中的任一计划。将计划更改为不在列表中的计划不起作用。

此 API 还会检索关联的活动专用产品/服务 ID（如果使用 planId 筛选器调用 API）。使用 planId 筛选器调用 API 会显示 sourceOffers 节点下响应正文中的活动专用产品/服务 ID GUID。在筛选器参数中传递的 planId 应与客户购买的 planId 匹配。

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

查询参数：

参数	价值
`ApiVersion`	使用 2018-08-31。
`subscriptionId`	购买的 SaaS 订阅的唯一标识符。使用解析 API 解析商业市场授权令牌后，会获取此 ID。
`planId (Optional)`	要提取的特定计划的计划 ID。这是可选的，如果忽略则返回所有计划。

请求标头：

参数	价值
`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 禁止。授权令牌无效，未提供或提供权限不足。请确保提供有效的授权令牌。

此错误通常是未正确执行 SaaS 注册的症状。

代码：500 内部服务器错误。重试 API 调用。如果错误仍然存在，请联系 Microsoft支持。

更改订阅上的计划

使用此 API 将为 SaaS 订阅购买的现有计划更新为新计划（公共计划或专用计划）。当在商业市场中购买的 SaaS 订阅的发布者端更改计划时，发布者必须调用此 API。

此 API 只能针对 Active 订阅调用。任何计划都可以更改为任何其他现有计划（公共或专用计划），但不能更改为自身。对于专用计划，必须在合作伙伴中心将客户的租户定义为计划的受众的一部分。

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

查询参数：

参数	价值
`ApiVersion`	使用 2018-08-31。
`subscriptionId`	购买的 SaaS 订阅的唯一标识符。使用解析 API 解析商业市场授权令牌后，会获取此 ID。

请求标头：

参数	价值
`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 订阅由云解决方案提供商（CSP）购买。必须使用 CSP 提供程序来执行此操作。

代码：403 禁止。授权令牌无效，未提供或提供权限不足。请确保提供有效的授权令牌。

此错误通常是未正确执行 SaaS 注册的症状。

代码：404 找不到。找不到具有指定 subscriptionId 的 SaaS 订阅。

代码：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 解析商业市场授权令牌后，会获取此 ID。

请求标头：

参数	价值
`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 错误的请求：验证失败。

新数量不在允许的范围内。
新数量缺失或为 0。
新数量与当前数量相同。
SaaS 订阅状态未订阅。
要更新的 SaaS 订阅由云解决方案提供商（CSP）购买。必须使用 CSP 提供程序来执行此操作。

代码：403 禁止。授权令牌无效，未提供或提供权限不足。请确保提供有效的授权令牌。

此错误通常是未正确执行 SaaS 注册的症状。

代码：404 找不到。找不到具有指定 subscriptionId 的 SaaS 订阅。

代码：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 解析商业市场授权令牌后，会获取此 ID。

请求标头：

参数	价值
`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 找不到。找不到具有 subscriptionId 的 SaaS 订阅。

代码：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>`