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

  • 项目

本文介绍 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 支持人员。

后续步骤