Microsoft商业市场中的 SaaS 履行操作 API v2
注意
若要能够调用 SaaS 履行操作 API，必须使用正确的资源 ID 创建发布者的授权令牌。了解如何 获取发布者的授权令牌
本文介绍 SaaS 履行操作 API 版本 2。
操作对于响应作为 ChangePlan、ChangeQuantity 和 Reinstate 操作的一部分通过 Webhook 发出的任何请求非常有用。 这提供了一个机会，通过修补 Webhook 操作并使用以下 API 成功或失败来接受或拒绝请求。
这仅适用于需要 ACK 的 Webhook 事件，例如 ChangePlan、ChangeQuantity 和 Reinstate。 对于续订、暂停和取消订阅事件，独立软件供应商（ISV）无需执行任何操作，因为它们是仅通知事件。
列出未完成的操作
获取指定 SaaS 订阅的挂起操作的列表。 发布者应通过调用 操作修补程序 API来确认返回的操作。
获取 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations?api-version=<ApiVersion>
查询参数：
| 参数 | 价值 |
|---|---|
ApiVersion |
使用 2018-08-31。 |
subscriptionId |
购买的 SaaS 订阅的唯一标识符。 使用解析 API 解析商业市场授权令牌后，会获取此 ID。 |
请求标头：
| 参数 | 价值 |
|---|---|
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 错误的请求：验证失败。
代码：401 未授权。 授权令牌无效或已过期。 请求尝试访问已发布的套餐的 SaaS 订阅，该套餐与用于创建身份验证令牌的项应用 ID 不同Microsoft条目应用 ID。
代码：403 禁止。 授权令牌无效，未提供或提供权限不足。 请确保提供有效的授权令牌。
此错误通常是未正确执行 SaaS 注册 的症状。
代码：404 找不到。 找不到具有 subscriptionId 的 SaaS 订阅。
代码：500 内部服务器错误。 重试 API 调用。 如果错误仍然存在，请联系 Microsoft支持。
获取操作状态
此 API 使发布者能够跟踪指定异步操作的状态：取消订阅、ChangePlan或 ChangeQuantity。
可以从 Operation-Location、获取挂起的操作 API 调用或 webhook 调用中收到的 <id> 参数值返回的值中检索此 API 调用的 operationId。
获取 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=<ApiVersion>
查询参数：
| 参数 | 价值 |
|---|---|
ApiVersion |
使用 2018-08-31。 |
subscriptionId |
购买的 SaaS 订阅的唯一标识符。 使用解析 API 解析商业市场授权令牌后，会获取此 ID。 |
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": ""
}
代码：401 未授权。 授权令牌无效或已过期。 请求尝试访问已发布的套餐的 SaaS 订阅，该套餐与用于创建身份验证令牌的项应用 ID 不同Microsoft条目应用 ID。
代码：403 禁止。 授权令牌无效，未提供或提供权限不足。 请确保提供有效的授权令牌。
此错误通常是未正确执行 SaaS 注册 的症状。
代码：404 找不到。
- 找不到具有
subscriptionId的订阅。 - 找不到具有
operationId的操作。
代码：500 内部服务器错误。 重试 API 调用。 如果错误仍然存在，请联系 Microsoft支持。
更新操作的状态
使用此 API 更新挂起操作的状态，以指示操作在发布方成功或失败。
可以从 Operation-Location、获取挂起的操作 API 调用或 webhook 调用中收到的 <id> 参数值返回的值中检索此 API 调用的 operationId。
修补 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=<ApiVersion>
查询参数：
| 参数 | 价值 |
|---|---|
ApiVersion |
使用 2018-08-31。 |
subscriptionId |
购买的 SaaS 订阅的唯一标识符。 使用解析 API 解析商业市场授权令牌后，会获取此 ID。 |
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 A 调用，告知合作伙伴端的操作完成情况。 例如，此响应可能表明发布者端的席位或计划的更改完成。
代码：401 未授权。 授权令牌无效或已过期。 请求尝试访问已发布的套餐的 SaaS 订阅，该套餐与用于创建身份验证令牌的项应用 ID 不同Microsoft条目应用 ID。
代码：403 禁止。 授权令牌无效，未提供或提供权限不足。 请确保提供有效的授权令牌。
此错误通常是未正确执行 SaaS 注册 的症状。
代码：404 找不到。
- 找不到具有
subscriptionId的订阅。 - 找不到具有
operationId的操作。
代码：409 冲突。 例如，更新更新已完成。
代码：500 内部服务器错误。 重试 API 调用。 如果错误仍然存在，请联系 Microsoft支持。
相关内容
- 有关商业市场中 SaaS 产品/服务的更多选项，请参阅 商业市场计量服务 API。
- 查看和使用 客户端的不同编程语言和示例。