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 不正確的要求：驗證失敗。
代碼：403 禁止。 授權令牌無效、過期或未提供。 要求嘗試存取以不同Microsoft Entra 應用程式標識符發行之供應專案的 SaaS 訂用帳戶，該供應專案與用來建立授權令牌的供應專案。
此錯誤通常是未正確執行 SaaS 註冊 的徵兆。
程序代碼：404 找不到。 找不到的 SaaS 訂用 subscriptionId 帳戶。
程式代碼：500 內部伺服器錯誤。 重試 API 呼叫。 如果錯誤持續發生，請連絡 Microsoft支持人員。
取得作業狀態
此 API 可讓發行者追蹤指定異步操作的狀態： 取消訂閱、 ChangePlan 或 ChangeQuantity。
operationId這個 API 呼叫的 可以擷取自 Operation-Location 傳回的值、取得暫止的 Operations API 呼叫，或 <id> Webhook 呼叫中收到的參數值。
獲取 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": ""
}
代碼：403 禁止。 授權令牌無效、過期或未提供。 要求嘗試存取以不同Microsoft Entra 應用程式標識符發行之供應專案的 SaaS 訂用帳戶，該供應專案與用來建立授權令牌的供應專案。
此錯誤通常是未正確執行 SaaS 註冊 的徵兆。
程序代碼：404 找不到。
- 找不到 具有的訂用
subscriptionId帳戶。 - 找不到與
operationId的作業。
程式代碼：500 內部伺服器錯誤。 重試 API 呼叫。 如果錯誤持續發生，請連絡 Microsoft支持人員。
更新作業的狀態
使用此 API 來更新暫止作業的狀態，以指出發行者端的作業成功或失敗。
operationId這個 API 呼叫的 可以擷取自 Operation-Location 傳回的值、取得暫止的 Operations API 呼叫，或 <id> Webhook 呼叫中收到的參數值。
補丁 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 通知合作夥伴端作業完成的呼叫。 例如，此回應可能會發出發行者端基座或方案變更的完成訊號。
程序代碼：403
- 禁止： 授權令牌無法使用、無效或已過期。 要求可能會嘗試存取不屬於目前發行者的訂用帳戶。
- 禁止： 授權令牌無效、過期或未提供。 要求嘗試存取以不同Microsoft Entra 應用程式標識符發行之供應專案的 SaaS 訂用帳戶，該供應專案與用來建立授權令牌的供應專案。
此錯誤通常是未正確執行 SaaS 註冊 的徵兆。
程序代碼：404 找不到。
- 找不到 具有的訂用
subscriptionId帳戶。 - 找不到與
operationId的作業。
程序代碼：409 衝突。 例如，已完成較新的更新。
程式代碼：500 內部伺服器錯誤。 重試 API 呼叫。 如果錯誤持續發生，請連絡 Microsoft支持人員。
相關內容
- 如需商業市集中 SaaS 供應專案的更多選項，請參閱商業市集計量服務 API。
- 檢閱和使用不同程式設計語言和範例的用戶端。