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 支持人员。
相关内容
- 有关商业市场中 SaaS 产品/服务的其他选项,请参阅商业市场计量服务 API。
- 查看并使用适用于不同编程语言的客户端和示例。