Microsoft商業市集中的 SaaS 履行作業 API v2
注意
若要能夠呼叫 SaaS 履行作業 API，您必須使用正確的資源識別碼來建立發行者的授權令牌。瞭解如何 取得發行者的授權令牌
本文說明 SaaS 履行作業 API 第 2 版。
作業對於回應透過 Webhook 作為 ChangePlan、ChangeQuantity 和恢復動作一部分的任何要求很有用。 這可讓您利用下列 API 來修補 Webhook 作業成功或失敗，以接受或拒絕要求。
這隻適用於需要 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 解析商業市集授權令牌之後，會取得此標識碼。 |
要求標頭：
| 參數 | 價值 |
|---|---|
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 未經授權。 授權令牌無效或已過期。 要求嘗試存取以不同Microsoft Entra 應用程式標識符發行之供應專案的 SaaS 訂用帳戶，該供應專案與用來建立驗證令牌的供應專案。
代碼：403 禁止。 授權令牌無效、未提供或許可權不足。 請務必提供有效的授權令牌。
此錯誤通常是未正確執行 SaaS 註冊 徵兆。
程序代碼：404 找不到。 找不到具有 subscriptionId 的 SaaS 訂用帳戶。
程式代碼：500 內部伺服器錯誤。 重試 API 呼叫。 如果錯誤持續發生，請連絡 Microsoft 支援。
取得作業狀態
此 API 可讓發行者追蹤指定異步操作的狀態：取消訂閱、ChangePlan或 ChangeQuantity。
此 API 呼叫的 operationId 可以從 Operation-Location、取得暫止 Operations API 呼叫或 webhook 呼叫中收到的 <id> 參數值所傳回的值擷取。
取得 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=<ApiVersion>
查詢參數：
| 參數 | 價值 |
|---|---|
ApiVersion |
使用 2018-08-31。 |
subscriptionId |
所購買 SaaS 訂用帳戶的唯一標識碼。 使用解析 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": ""
}
程序代碼：401 未經授權。 授權令牌無效或已過期。 要求嘗試存取以不同Microsoft Entra 應用程式標識符發行之供應專案的 SaaS 訂用帳戶，該供應專案與用來建立驗證令牌的供應專案。
代碼：403 禁止。 授權令牌無效、未提供或許可權不足。 請務必提供有效的授權令牌。
此錯誤通常是未正確執行 SaaS 註冊 徵兆。
程序代碼：404 找不到。
- 找不到具有
subscriptionId的訂用帳戶。 - 找不到具有
operationId的作業。
程式代碼：500 內部伺服器錯誤。 重試 API 呼叫。 如果錯誤持續發生，請連絡 Microsoft 支援。
更新作業的狀態
使用此 API 來更新暫止作業的狀態，以指出發行者端的作業成功或失敗。
此 API 呼叫的 operationId 可以從 Operation-Location、取得暫止 Operations API 呼叫或 webhook 呼叫中收到的 <id> 參數值所傳回的值擷取。
修補程式 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=<ApiVersion>
查詢參數：
| 參數 | 價值 |
|---|---|
ApiVersion |
使用 2018-08-31。 |
subscriptionId |
所購買 SaaS 訂用帳戶的唯一標識碼。 使用解析 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 通知合作夥伴端作業完成的呼叫。 例如，此回應可能會發出發行者端基座或方案變更的完成訊號。
程序代碼：401 未經授權。 授權令牌無效或已過期。 要求嘗試存取以不同Microsoft Entra 應用程式標識符發行之供應專案的 SaaS 訂用帳戶，該供應專案與用來建立驗證令牌的供應專案。
代碼：403 禁止。 授權令牌無效、未提供或許可權不足。 請務必提供有效的授權令牌。
此錯誤通常是未正確執行 SaaS 註冊 徵兆。
程序代碼：404 找不到。
- 找不到具有
subscriptionId的訂用帳戶。 - 找不到具有
operationId的作業。
程序代碼：409 衝突。 例如，已完成較新的更新。
程式代碼：500 內部伺服器錯誤。 重試 API 呼叫。 如果錯誤持續發生，請連絡 Microsoft 支援。
相關內容
- 如需商業市集中 SaaS 供應專案的更多選項，請參閱 商業市集計量服務 API。
- 檢閱並使用 用戶端，以取得不同的程式設計語言和範例。