Microsoft 商业市场中的 SaaS 履行操作 API v2

注意

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

本文介绍 SaaS 履行操作 API 版本 2。

操作对于响应作为 ChangePlan、ChangeQuantity 和 Reinstate 操作的一部分通过 Webhook 发出的任何请求非常有用。 这提供了一个机会,即通过使用以下 API,使用 Success 或 Failure 修补该 Webhook 操作来接受或拒绝请求。

这仅适用于需要 ACK 的 Webhook 事件,例如 ChangePlan、ChangeQuantity 和 Reinstate。 对于续订、暂停和取消订阅事件,独立软件供应商(ISV)无需执行任何操作,因为它们是仅通知事件。

列出未完成的操作

获取指定 SaaS 订阅的等待中操作列表。 发布者应该通过调用操作修补 API 来确认返回的操作。

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

查询参数

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

请求标头:

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

响应代码

代码:200,返回针对指定 SaaS 订阅的等待中操作。

响应有效负载示例:

{
  "operations": [
    {
      "id": "<guid>", //Operation ID, should be provided in the operations patch API call
      "activityId": "<guid>", //not relevant
      "subscriptionId": "<guid>", // subscriptionId of the SaaS subscription that is being reinstated
      "offerId": "offer1", // purchased offer ID
      "publisherId": "contoso",
      "planId": "silver", // purchased plan ID
      "quantity": 20, // purchased amount of seats, will be empty is not relevant
      "action": "Reinstate",
      "timeStamp": "2018-12-01T00:00:00", // UTC
      "status": "InProgress" // the only status that can be returned in this case
    }
  ]
}

如果没有任何操作等待执行,则返回空 json。

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

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

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

代码:404 找不到。 找不到包含的 subscriptionId SaaS 订阅。

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

获取操作状态

发布者可以使用此 API 跟踪指定异步操作的状态:Unsubscribe、ChangePlan 或 ChangeQuantity

此 API 调用的 operationId 可以从 Operation-Location 返回的值、获取等待中操作 API 调用,或者在 Webhook 调用中收到的 <id> 参数值检索到

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

查询参数

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

请求标头:

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

响应代码

代码:200 获取指定 SaaS 操作的详细信息。

响应有效负载示例:

Response body:
{
  "id  ": "<guid>", //Operation ID, should be provided in the patch operation API call
  "activityId": "<guid>", //not relevant
  "subscriptionId": "<guid>", // subscriptionId of the SaaS subscription for which this operation is relevant
  "offerId": "offer1", // purchased offer ID
  "publisherId": "contoso",
  "planId": "silver", // purchased plan ID
  "quantity": 20, // purchased amount of seats
  "action": "ChangePlan", // Can be ChangePlan, ChangeQuantity or Reinstate
  "timeStamp": "2018-12-01T00:00:00", // UTC
  "status": "InProgress", // Possible values: NotStarted, InProgress, Failed, Succeeded, Conflict (new quantity / plan is the same as existing)
  "errorStatusCode": "",
  "errorMessage": ""
}

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

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

代码:404 找不到。

  • 找不到订阅 subscriptionId
  • 找不到具有 operationId 的操作。

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

更新操作的状态

使用此 API 可以更新等待中操作的状态,以在发布者端指示该操作是成功还是失败。

此 API 调用的 operationId 可以从 Operation-Location 返回的值、获取等待中操作 API 调用,或者在 Webhook 调用中收到的 <id> 参数值检索到

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

查询参数

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

请求标头:

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

请求有效负载示例

{
  "status": "Success" // Allowed Values: Success/Failure. Indicates the status of the operation on ISV side.
}

响应代码

代码:200 用于告知已在合作伙伴端完成某项操作的调用。 例如,此响应可以指出已在发布者端完成座席数量或计划的更改。

代码:403

  • 已禁止。 授权令牌不可用、无效或已过期。 请求可能尝试访问不属于当前发布服务器的订阅。
  • 已禁止。 授权令牌无效、已过期或未提供。 该请求尝试访问随用于创建授权令牌的不同Microsoft Entra 应用 ID 发布的套餐的 SaaS 订阅。

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

代码:404 找不到。

  • 找不到订阅 subscriptionId
  • 找不到具有 operationId 的操作。

代码:409 冲突。 例如,已履行较新的更新。

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