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

项目
04/30/2024

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

解析已购买的订阅

通过解析终结点，发布者可将商业市场中的购买标识令牌（在已购买但尚未激活部分中称为令牌）交换为持久性的已购买 SaaS 订阅 ID 及其详细信息。

当客户重定向到合作伙伴的登陆页 URL 时，客户标识令牌将在此 URL 调用中作为 token 参数传递。发布者应使用此令牌，并发出请求来解析此令牌。解析 API 响应包含 SaaS 订阅 ID 以及用于唯一标识购买项的其他详细信息。 登录页 URL 调用提供的令牌有效期为 24 小时。 如果收到的令牌已过期，我们建议向最终用户提供以下指导：

“我们无法识别此购买项。在Azure 门户或Microsoft 365 管理中心重新打开此 SaaS 订阅，然后再次选择“配置帐户”或“管理帐户”。

调用解析 API 会返回所有受支持的状态中的 SaaS 订阅的订阅详细信息和状态。

Post `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`	要解析的购买标识 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 应用 ID 发布的套餐的 SaaS 订阅。

此错误体现出的症状通常是无法正常执行 SaaS 注册。

代码：500 内部服务器错误。重试 API 调用。如果错误依然出现，请联系 Microsoft 支持人员。

激活订阅

为最终用户配置 SaaS 帐户后，发布者必须在 Microsoft 端调用激活订阅 API。除非此 API 调用成功，否则不会对客户计费。

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

查询参数：

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

请求标头：

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

响应代码：

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

此调用没有响应正文。

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

SaaS 订阅处于挂起状态。

代码：403 禁止。授权令牌无效、已过期或未提供。该请求尝试访问随用于创建授权令牌的不同 Microsoft Entra 应用 ID 发布的套餐的 SaaS 订阅。

此错误体现出的症状通常是无法正常执行 SaaS 注册。

代码：404 找不到。 SaaS 订阅处于“已取消订阅”状态。

代码：500 内部服务器错误。重试 API 调用。如果错误依然出现，请联系 Microsoft 支持人员。

获取所有订阅的列表

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

该 API 分页返回结果，每页包含 100 条结果。

Get `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 来获取这些信息。

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

查询参数：

参数	值
`ApiVersion`	使用 2018-08-31。
`subscriptionId`	购买的 SaaS 订阅的唯一标识符。此 ID 是使用解析 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.
  }
}

代码：403 禁止。授权令牌无效、已过期或未提供。该请求尝试访问随用于创建授权令牌的不同 Microsoft Entra 应用 ID 发布的套餐的 SaaS 订阅。

此错误体现出的症状通常是无法正常执行 SaaS 注册。

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

代码：500 内部服务器错误。重试 API 调用。如果错误依然出现，请联系 Microsoft 支持人员。

列出可用计划

此 API 检索某个 SaaS 产品/服务的所有计划，这些计划由此产品/服务的特定购买项的 subscriptionId 标识。使用此调用可以获取 SaaS 订阅受益人可为订阅更新的所有私用和公用计划的列表。返回的计划与已购买的计划位于同一地理位置。

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

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

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

查询参数：

参数	值
`ApiVersion`	使用 2018-08-31。
`subscriptionId`	购买的 SaaS 订阅的唯一标识符。此 ID 是使用解析 API 解析商业市场授权令牌后获取的。
`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 订阅，该订阅与用于创建授权令牌的不同 Microsoft Entra 应用 ID 不同。

此错误体现出的症状通常是无法正常执行 SaaS 注册。

代码：500 内部服务器错误。重试 API 调用。如果错误依然出现，请联系 Microsoft 支持人员。

更改订阅的计划

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

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

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

查询参数：

参数	值
`ApiVersion`	使用 2018-08-31。
`subscriptionId`	购买的 SaaS 订阅的唯一标识符。此 ID 是使用解析 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，以确定更改计划请求是成功还是失败。应每隔几秒轮询一次，直到收到的最终操作状态为 Failed、Succeed 或 Conflict。最终操作状态应该很快就会返回，但某些情况下可能要在几分钟后才返回。

当操作准备好在商业市场端成功完成时，合作伙伴还会收到 Webhook 通知。只有在收到通知后，发布者才能在发布者端进行计划更改。

响应头：

参数	值
`Operation-Location`	用于获取操作状态的 URL。例如： `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`

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

新计划不存在，或者不可用于此特定 SaaS 订阅。
新计划与当前计划相同。
SaaS 订阅状态不是“已订阅”。
SaaS 订阅的更新操作未包含在 allowedCustomerOperations 中。

代码：403 禁止。授权令牌无效、已过期或未提供。该请求尝试访问随用于创建授权令牌的不同 Microsoft Entra 应用 ID 发布的套餐的 SaaS 订阅。

此错误体现出的症状通常是无法正常执行 SaaS 注册。

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

代码：500 内部服务器错误。重试 API 调用。如果错误依然出现，请联系 Microsoft 支持人员。

注意

每次可以更改计划或座席数量，但不能同时更改两者。

只有在收到最终用户对更改的显式批准后，才能调用此 API。

更改 SaaS 订阅的座席数量

使用此 API 可以更新（增加或减少）为 SaaS 订阅购买的座席数量。在发布者端更改在商业市场中创建的 SaaS 订阅的座席数量后，发布者必须调用此 API。

席位数量不能超过当前计划中允许的数量。如果超过，则发布者应该先更改计划，然后再更改座席数量。

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

查询参数：

参数	值
`ApiVersion`	使用 2018-08-31。
`subscriptionId`	购买的 SaaS 订阅的唯一标识符。此 ID 是使用解析 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，以确定更改数量请求是成功还是失败。应每隔几秒轮询一次，直到收到的最终操作状态为 Failed、Succeed 或 Conflict。最终操作状态应该很快就会返回，但某些情况下可能要在几分钟后才返回。

当操作准备好在商业市场端成功完成时，合作伙伴还会收到 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 找不到。找不到具有 subscriptionId 的 SaaS 订阅。

代码：500 内部服务器错误。重试 API 调用。如果错误依然出现，请联系 Microsoft 支持人员。

注意

每次只能更改计划或数量，而不能同时更改两者。

只有在收到最终用户对更改的显式批准后，才能调用此 API。

取消订阅

使用此 API 可以取消订阅指定的 SaaS 订阅。发布者不一定要使用此 API，我们建议将客户定向到商业市场来取消 SaaS 订阅。

如果发布者决定在发布者端取消在商业市场中购买的 SaaS 订阅，则必须调用此 API。完成此调用后，订阅的状态在 Microsoft 端变为 “取消订阅 ”。

如果在购买后的 72 小时内取消订阅，则不会向客户计费。

如果订阅在上一宽限期后取消，则会对客户计费。客户在取消后立即失去对 Microsoft 端 SaaS 订阅的访问权限。

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

查询参数：

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

请求标头：

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

响应代码：

代码：202 已接受并以异步方式处理取消订阅请求。合作伙伴应轮询 Operation-Location URL，以确定此请求是成功还是失败。应每隔几秒轮询一次，直到收到的最终操作状态为 Failed、Succeed 或 Conflict。最终操作状态应该很快就会返回，但某些情况下可能要在几分钟后才返回。

合作伙伴还会在商业市场端成功完成操作时收到 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

解析已购买的订阅

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

激活订阅

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

获取所有订阅的列表

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

获取订阅

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

列出可用计划

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

更改订阅的计划

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

更改 SaaS 订阅的座席数量

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

取消订阅

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

后续步骤

反馈

反馈

其他资源

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

解析已购买的订阅

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

激活订阅

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

获取所有订阅的列表

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

获取订阅

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

列出可用计划

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

更改订阅的计划

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

更改 SaaS 订阅的座席数量

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

取消订阅

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

后续步骤

反馈

反馈

其他资源

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

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

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

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

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

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

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

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