適合的職務:資安管理員 |安全閱讀器 |管理代理
適用於:合作夥伴中心
合作夥伴中心的安全合規 API 讓您能取得合作夥伴組織的合規任務、檢視回應時間評估,並更新任務狀態。 它支援重新設計的安全工作空間中所使用的統一任務模型自動化,將安全需求與警示呈現為可執行的任務。
本文介紹任務模型、支援的操作、JSON 資源,以及 REST 請求與回應範例。 API 屬性名稱和值會保留其精確的外殼,即使工作區使用不同的顯示標籤。
重新設計體驗中的概念
以下概念將安全工作空間體驗與本文中的 API 資源連結起來。
| 概念 | 工作空間中的意義 | API 表示 |
|---|---|---|
| 任務 | 一個獨立且可執行的工作單元,包含範圍、生命週期狀態,並在可提供時有截止日期。 完成取決於對基礎病況的驗證,而非僅靠人工證明。 |
一個合規任務,由 標識為 taskId。 |
| 工作群組 | 相關任務依根本原因或分類分組。 群組進度是根據其任務(Tasks)來計算,而非可獨立編輯的群組狀態。 | 任務屬性如 taskGroupId、 taskGroupTitle、 taskGroupClassification和 。 本文中的操作不會回傳獨立的任務群組資源或群組進度摘要。 |
| 出現次數 | 這是一個有助於辨識源系統中需要注意的底層狀況的實例。 狀態管理於任務層級。 | 此 API 參考中沒有獨立的 Occurrence 資源或 Occurrence 狀態操作。 不要以為飼料專屬 details 會提供標準化的出現事件集合。 |
| 整體合規性 | 工作區的完成/未完成指示器,並標示「截至」的時間戳。 重新設計的體驗不再使用數值安全分數。 | 本文未定義整體合規性或數值分數運算。 反應時間評估僅評估反應時間要求。 |
| 數據新鮮度 | 這是底層原始資料被刷新的時間,而非使用者開啟頁面或客戶端取得回應的時間。 |
lastRefreshDateTime 任務組資料; calculatedAt 以及 expiresAt 進行反應時間評估。 這些時間戳記不能互換。 |
任務生命週期與狀態
工作空間稱生命週期值為狀態;API 將其暴露為 status。 在 API 請求與回應中使用以下精確且大小寫區分字串。
| Status | Meaning | 這個 API 可以設定嗎? |
|---|---|---|
New |
任務已經被創造出來,但尚未被承認或執行。 | No. |
In Progress |
合夥人已經承擔起責任,工程正在進行中。 這對應於目前警報體驗中所描述的「調查」確認動作。 | 是的,但須遵守以下過渡限制。 |
Ignore |
對於合格任務,夥伴已認定該事件為已知且合法。 忽略任務並不會解決該狀況,也不會免除相關使用費用的責任。 | 是的,只有當 isIgnorable 是 時 true。 |
Ready for Review |
合夥人已完成所需工作,並等待基礎病況的驗證。 | 是的,但須遵守以下過渡限制。 |
Complete |
Microsoft 已確認根本問題已解決。 | No. 完成過程由系統管理。 |
要以程式化方式處理任務:
- 列出合規任務 並選擇需要關注的任務。
- 取得任務詳情 以檢視其當前狀態、特定資訊、筆記及近期活動。
-
將狀態設定為
In Progress工作開始的時候。 - 在適當的來源系統中修復該狀況,例如 Microsoft Entra、Azure 入口網站或合作夥伴中心。
- 將狀態設定為
Ready for Review工作完成時,然後在驗證來源後再次取回任務,以檢查其狀態與資料新鮮度。
Important
成功的狀態更新是確認工作流程變更,而非底層工作的完成。 不要將 Ready for Review 或 Ignore 視為 Complete。 對於已知且合法的事件,僅在允許的情況下使用 Ignore 。 被忽略的任務必須回到 , In Progress 才能移動到 Ready for Review;完成任務無法透過此操作改變。
轉換期間的 API 範圍
重新設計的工作區和 API 不一定會暴露相同的操作。 請將本文中的操作與架構視為此 API 的合約,而非假設每個工作區動作都有相應的 API 版本。
| 能力 | 此 API 的支援 |
|---|---|
| 取得任務及其詳細資訊 | 清單與詳細操作,包括任務群組識別碼、可用範圍資訊及刷新時間戳記。 |
| 更新任務狀態 | 狀態操作 、 In ProgressReady for Review、 以及(在允許的情況下)。 Ignore 每個請求針對一個任務;此處未定義任何批量狀態操作。 |
| 查看筆記與活動 | 任務細節包含現有筆記及最多 50 個保留活動條目。 活動日誌可能會被截斷。 |
| 新增附註或註解 | 本文的操作不支持。 在狀態請求中不要附註。 |
| 檢視或變更事件 | 此處未定義獨立的發生操作。 在原始碼系統中做出必要的變更。 |
| 審查回應時間 | 合作夥伴對首次記錄狀態變更的時間評估。 這並非整體合規結果。 |
| 管理訂閱 | 這些行動沒有支援。 在適當的原始碼系統中管理訂閱。 |
| 啟用工作區預覽 | 此處未定義預覽切換操作。 API 存取需要合作夥伴組織的啟用。 |
在工作空間轉換過程中,請將這些合作夥伴中心端點與目前的 Microsoft Graph 測試版 API 區分,用於安全警示、需求及安全分數。 本文並未定義退休日期、一對一將現有警示 ID 映射到任務 ID,或是每個現有操作的替換。 從此 API 取得不透明的任務 ID;不要從現有的提醒或訂閱識別碼來建構它們。
Note
工作區描述了將任務移至進行中時,24 小時警示確認的要求。 此處描述的回應時間端點衡量首次記錄的狀態變更,包括可測量任務無變化的經過時間。 解讀 API 結果時請使用 評估規則 ;不要假設端點只測量已 In Progress 收到回應的任務轉換或轉移。
資源慣例
以下資源描述本文操作回傳或接受的 JSON 資料。 與其他 合作夥伴中心 REST 資源相同,屬性表定義請求與回應元素。
JSON 屬性名稱與狀態值是區分大小寫的。 時間戳記為 UTC ISO 8601 字串,例如 2026-10-01T12:00:00.000Z。 可空欄位可包含 null;不要假設每個任務都有客戶、訂閱、截止日期或解決資訊。
合規任務
描述一項合規任務,包括其目前狀態、嚴重程度、截止日期,以及相關的客戶或訂閱。 列表操作與詳細操作皆回傳這些屬性。
| Property | 類型 | Description |
|---|---|---|
taskId |
字串 | 不透明的任務識別碼。 請保持不動、以 URL 編碼的方式,用於詳細和狀態請求。 |
taskGroupId |
字串 | 任務群組識別碼。 |
taskGroupTitle |
字串或空 | 顯示任務小組標題。 |
taskGroupClassification |
字串或空 |
Fraud分類如 ;並不能從此例推斷出完整的枚舉。 |
isEligibilityRequirement |
布林值 | 任務組是否被標記為資格要求。 |
requirementId |
字串 | 需求識別碼,可用於清單篩選器。 |
taskTitle |
字串或空 | 顯示任務標題。 |
status |
字串 | 目前任務狀態:New、、In Progress、Ready for ReviewComplete、或Ignore。 |
isIgnorable |
布林值 | 動態是否允許忽略該任務。 |
customerTenantId |
字串或空 | 客戶租戶識別碼(如有)。 |
customerName |
字串或空 | 客戶顯示名稱(如有)提供。 |
subscriptionId |
字串或空 | 訂閱識別碼(如有)提供。 |
subscriptionName |
字串或空 | 訂閱顯示名稱(如有)。 |
severity |
字串或空 |
Informational、High、MediumLow、,或在無法使用或未被識別時使用空。 |
deadlineDateTime |
時間戳記或空 | 計算好的任務截止日期(如有時)。 |
createdDate |
時間戳記 | 任務建立時間。 |
lastModifiedDate |
時間戳記或空 | 最後任務修改時間。 |
lastRefreshDateTime |
時間戳記或空 | 任務群組資料更新時間;不是客戶取任務的時間。 |
resolvedDate |
時間戳記或空 | 解決時間(如有)。 |
version |
字串 | 不透明儲存版本。 保留其價值,包括嵌入的引言;不要去解析它。 |
Important
任務 ID 是不透明的字串,不是 GUID。 從清單或詳細回應複製 taskId 一次,並以 URL 編碼為單一路徑段。 不要構造 ID、拆分成商業識別碼、加白或 base64 編碼。 範例中的編碼冒號是刻意的。
合規任務細節
描述單一合規任務,包含特定資訊流的細節、備註及近期活動。 包含所有 合規任務 屬性及以下屬性。
| Property | 類型 | Description |
|---|---|---|
details |
物件 | 動態專屬細節欄位。 詳細回應範例是用於使用異常偵測;其他需求可能會回傳不同的欄位或空物件。 |
notes |
字串或空 | 現有的任務筆記。 此 API 的狀態操作無法更新筆記。 |
activityLog |
合規任務活動資源陣列 | 最多保留50項活動條目,最新者優先。 |
activityLogTruncated |
布林值 | 當活動歷史被截斷時,這點成立。 不要把陣列當作完整的稽核追蹤。 |
合規任務活動
描述合規任務的變更記錄。 可選值可以為空值。
| Property | 類型 | Description |
|---|---|---|
date |
時間戳記 | 活動的日期和時間。 |
action |
字串 | 記錄動作,例如 FeedCreated。 |
oldStatus |
字串或空 | 變更前的任務狀態(如有)。 |
newStatus |
字串或空 | 變更後的任務狀態(如有)。 |
changeReason |
字串或空 | 變更的原因,若有的話。 |
notes |
字串或空 | 與活動相關的筆記(如有)。 |
合規任務收集
描述一頁合規任務。
| Property | 類型 | Description |
|---|---|---|
value |
合規任務資源陣列 | 任務在目前頁面。 空結果為 {"value":[]}。 |
@odata.nextLink |
字串 | 下一頁的網址。 只有在有更多結果出現時才會出現。 請跟隨回傳的連結,而非自行構建續寫標記。 |
該集合沒有總計數特性。 關於延續行為與到期,請參見頁碼。
反應時間評估
描述您的合作夥伴組織在合規任務首次狀態變更前的平均時間。 這是合作夥伴整體評估,而非單一任務的經過時間、最終解決時間或 HTTP API 延遲。
| Property | 類型 | Description |
|---|---|---|
completion |
字串 | 評估結果: complete、 notComplete,或 unknown。 不是任務狀態。 |
thresholdSeconds |
整數 | 評估門檻目前為86,400秒(24小時)。 |
averageDurationSeconds |
整數或零 | 平均測量持續時間以秒計,四捨五入為整整一秒。 當無法測量時為零。 |
sampleCount |
整數或零 | 平均中包含可測量任務樣本數量。 |
availability |
字串 | 基礎計算證據的可用性: available、 partial、 或 unavailable。 請分開 completion檢查。 |
reason |
字串或空 | 對於缺失或部分證據的解釋,例如noHistory、insufficientHistory、partialHistorytruncatedHistory或registryPartial。 不需要時就用 Null。 |
definitionVersion |
整數 | 測量定義的版本。 |
activeFeedSetVersion |
字串或空 | 不透明版本,標示評估中使用的主動給料集。 |
windowStart |
時間戳記或空 | 包含測量隊列窗口開始。 |
windowEnd |
時間戳記或空 | 測量隊列窗口結束,獨家。 |
calculatedAt |
時間戳記或空 | 計算時間。 |
expiresAt |
時間戳記或空 | 評估期限。 |
關於測量規則與證據限制,請參見「回應時間評估」。
任務狀態更新請求
描述更新合規任務工作流程狀態的請求體。
| Property | 類型 | Required | Description |
|---|---|---|---|
status |
字串 | Yes | 正確 In Progress, Ready for Review或 Ignore。 |
只 status供應。 關於允許的轉換與限制,請參見 更新合規任務的狀態。
任務狀態更新結果
描述確認狀態更新。
| Property | 類型 | Description |
|---|---|---|
taskId |
字串 | 更新任務的不透明識別碼。 |
status |
字串 | 任務狀態已確認。 |
lastModifiedDate |
時間戳記 | 任務調整時間。 |
version |
字串 | 更新後的不透明儲存版本,包含嵌入的引號。 |
錯誤
描述一般的合規 API 故障。 驗證/多重驗證失敗與前門故障可能使用不同的實體;不要假設每個錯誤都符合這個形狀。
| Property | 類型 | Description |
|---|---|---|
code |
整數 | 數值錯誤碼。 結合 HTTP 狀態碼與回應主體來決定下一步動作。 |
description |
字串 | 錯誤的說明。 |
source |
字串 | 產生錯誤的服務識別碼,例如 PCFraudEvents。 |
關於 HTTP 狀態碼及範例錯誤內容,請參見 回應成功與錯誤代碼。
Operations
請使用以下 REST 操作來處理這些資源。
| 運算 | Method | 要求 URI |
|---|---|---|
| 列出合規任務 | GET | /v1/compliance/tasks |
| 取得合規任務 | GET | /v1/compliance/tasks/{taskId} |
| 做回應時間評估 | GET | /v1/compliance/responseTime |
| 更新合規任務的狀態 | PUT | /v1/compliance/tasks/{taskId}/status |
Prerequisites
- 設定一個 Microsoft Entra 應用程式以存取合作夥伴中心 API。 關於設定指引,請參閱 合作夥伴中心的「設定 API 存取」。
- 依照 合作夥伴中心認證說明,使用 App+User 認證取得存取權杖。 這些操作不支援僅應用程式的認證。
- 被委派的使用者必須符合多重身份驗證(MFA)並有權限查看合規/安全資訊。 更新狀態需要管理權限;唯讀權限不足以達成。
- 該 API 必須啟用給合作夥伴組織。 請求會對已認證夥伴的租戶進行,而非透過請求參數或標頭選擇的租戶。
關於多重因素整合的指引,請參閱 啟用安全應用模型。
REST 請求慣例
生產基地的網址為 https://api.partnercenter.microsoft.com。 以下範例使用此網址。 範例並未確定特定合作夥伴組織的可用性;該 API 必須為該組織啟用。
請求標頭
以下標頭適用於這些操作。 關於一般標頭定義,請參見 合作夥伴中心 REST 標頭。 並非每個合作夥伴中心標頭都適用於所有營運。
| Header | Usage |
|---|---|
Authorization |
Required.
Bearer <token>,使用透過合作夥伴中心認證取得的存取權杖。 千萬不要發佈或記錄真正的代幣。 |
Accept |
請使用 application/json。 |
Content-Type |
PUT 所需條件: application/json。 GET 請求沒有請求內容。 |
MS-CorrelationId |
為每次通話提供新的 GUID,以便在故障排除時對應日誌與網路追蹤。 |
MS-RequestId |
提供一個 GUID,標示請求。 關於一般的重試慣例,請參見合作夥伴中心 REST 標頭參考;如需狀態更新,請依照以下端點專屬的復原指引。 |
Note
狀態更新操作不需要 If-Match。 不要以為請求 ID 或回傳的 ETag 就能讓不確定的狀態更新可以安全重播。 在決定是否重試前,先取得任務。
列出合規任務
取得合作夥伴組織的合規任務分頁清單,包括每個任務的狀態、嚴重性、截止日期,以及可用的客戶或訂閱資訊。 使用篩選器依狀態、工作群組、需求、客戶租戶或訂閱方式縮小結果範圍。 利用回傳的任務 ID 來取得細節或更新任務狀態。
REST 要求
| Method | 要求 URI |
|---|---|
| GET | https://api.partnercenter.microsoft.com/v1/compliance/tasks |
查詢參數
| Name | 類型 | Required | Description |
|---|---|---|---|
$top |
整數 | No | 頁面大小從1到100不等。 預設值:100。 |
$filter |
字串 | No | 以下將介紹支援的等號表達式。 最大長度:1,000 字元。 |
$skiptoken |
字串 | No | 不透明延續標記於 @odata.nextLink。 請跟隨回傳的連結,而不是產生代幣。 |
支援的濾波器欄位:status、 requirementIdtaskGroupIdcustomerTenantIdsubscriptionId和 。 用於 eq 單引號字串值及 and 謂詞間。 括號 or 內的群組 僅支援狀態值,例如:
requirementId eq 'UsageAnomalyDetection' and (status eq 'New' or status eq 'In Progress')
支援的狀態過濾器值為 New、 In Progress、 Ready for ReviewCompleteIgnore、 和 。 將一個值中的字面撇號跳脫為兩個撇號,並以 URL 編碼查詢值。 此端點支援有限的 OData 語法,而非一般 OData:$orderby、$skip$select且不支援重複查詢參數。
要求本文
None.
範例請求
GET https://api.partnercenter.microsoft.com/v1/compliance/tasks?$top=1&$filter=requirementId%20eq%20%27UsageAnomalyDetection%27%20and%20status%20eq%20%27New%27 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-CorrelationId: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa
MS-RequestId: bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb
REST 響應
若成功,此方法會在回應體中回傳 200 個 OK 及 合規任務集合 。 空結果為 {"value":[]};不存在總計數性質。
回應範例
{
"value": [
{
"taskId": "usage-anomaly-detection::11111111-1111-4111-8111-111111111111-22222222-2222-4222-8222-222222222222",
"taskGroupId": "usage-anomaly-detection",
"taskGroupTitle": "Usage Anomaly Detection",
"taskGroupClassification": "Fraud",
"isEligibilityRequirement": false,
"requirementId": "UsageAnomalyDetection",
"taskTitle": "Action Required: Subscription Usage Anomaly Detected",
"status": "New",
"isIgnorable": true,
"customerTenantId": null,
"customerName": "Contoso Customer",
"subscriptionId": "11111111-1111-4111-8111-111111111111",
"subscriptionName": null,
"severity": "High",
"deadlineDateTime": "2026-10-15T12:00:00.000Z",
"createdDate": "2026-09-15T12:00:00.000Z",
"lastModifiedDate": "2026-09-15T12:00:00.000Z",
"lastRefreshDateTime": "2026-10-01T11:00:00.000Z",
"resolvedDate": null,
"version": "\"33333333-3333-4333-8333-333333333333\""
}
],
"@odata.nextLink": "https://api.partnercenter.microsoft.com/v1/compliance/tasks?$top=1&$filter=requirementId%20eq%20%27UsageAnomalyDetection%27%20and%20status%20eq%20%27New%27&$skiptoken=55555555-5555-4555-8555-555555555555"
}
Pagination
@odata.nextLink持續進行相同的認證,直到該屬性消失為止。 在瀏覽過程中,請勿更改頁面大小或篩選。 續集在第一頁後一小時失效;讀取另一頁不會延長該期限。 無效、過期或不相容的代幣會回傳 400 個;從最初的清單請求重新開始。 主動饋線配置的變更可能會使續寫失效。 分頁變動清單並非時間點快照。
取得合規任務
利用清單端點回傳的任務 ID 取得單一合規任務。 回應包含任務的摘要屬性,以及特定動態的細節、現有備註和近期活動歷史。 使用此操作來調查任務或刷新其當前狀態,然後再決定是否更新狀態。
REST 要求
| Method | 要求 URI |
|---|---|
| GET | https://api.partnercenter.microsoft.com/v1/compliance/tasks/{taskId} |
URI 參數
| Name | 類型 | Required | Description |
|---|---|---|---|
taskId |
字串 | Yes | 不透明的任務識別碼,由列表或詳細回應回傳,網址編碼為單一路徑段一次。 |
要求本文
None. 不支援查詢參數。
範例請求
GET https://api.partnercenter.microsoft.com/v1/compliance/tasks/usage-anomaly-detection%3A%3A11111111-1111-4111-8111-111111111111-22222222-2222-4222-8222-222222222222 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-CorrelationId: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa
MS-RequestId: bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb
REST 響應
若成功,此方法會在回應主體中回傳 200 個 OK 及 合規任務細節 。
ETag回應標頭與 version。
回應範例
{
"details": {
"alertId": "11111111-1111-4111-8111-111111111111-22222222-2222-4222-8222-222222222222",
"alertDisplayName": "Action Required: Subscription Usage Anomaly Detected",
"severity": "High",
"subscriptionId": "11111111-1111-4111-8111-111111111111",
"customerName": "Contoso Customer",
"detectedTime": "2026-09-15T12:00:00.000Z",
"description": "Unusual subscription usage was detected. Review the affected subscription."
},
"notes": null,
"activityLog": [
{
"date": "2026-09-15T12:00:00.000Z",
"action": "FeedCreated",
"oldStatus": null,
"newStatus": "New",
"changeReason": null,
"notes": null
}
],
"activityLogTruncated": false,
"taskId": "usage-anomaly-detection::11111111-1111-4111-8111-111111111111-22222222-2222-4222-8222-222222222222",
"taskGroupId": "usage-anomaly-detection",
"taskGroupTitle": "Usage Anomaly Detection",
"taskGroupClassification": "Fraud",
"isEligibilityRequirement": false,
"requirementId": "UsageAnomalyDetection",
"taskTitle": "Action Required: Subscription Usage Anomaly Detected",
"status": "New",
"isIgnorable": true,
"customerTenantId": null,
"customerName": "Contoso Customer",
"subscriptionId": "11111111-1111-4111-8111-111111111111",
"subscriptionName": null,
"severity": "High",
"deadlineDateTime": "2026-10-15T12:00:00.000Z",
"createdDate": "2026-09-15T12:00:00.000Z",
"lastModifiedDate": "2026-09-15T12:00:00.000Z",
"lastRefreshDateTime": "2026-10-01T11:00:00.000Z",
"resolvedDate": null,
"version": "\"33333333-3333-4333-8333-333333333333\""
}
做回應時間評估
取得合作夥伴組織對合規任務首次狀態變更的評估,並以當前 24 小時門檻為基準。 評估涵蓋過去30天內開啟的任務,並包含尚未變更狀態的可衡量任務經過的時間。 它回傳平均時長、樣本數、評估結果及證據可用性;它不會測量最終解析時間或 API 延遲。
REST 要求
| Method | 要求 URI |
|---|---|
| GET | https://api.partnercenter.microsoft.com/v1/compliance/responseTime |
不支援查詢參數。
要求本文
None.
範例請求
GET https://api.partnercenter.microsoft.com/v1/compliance/responseTime HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-CorrelationId: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa
MS-RequestId: bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb
REST 響應
若成功,此方法會回傳 200 個 OK 及回應體中的 回應時間評估 。
回應範例
{
"completion": "notComplete",
"thresholdSeconds": 86400,
"averageDurationSeconds": 108000,
"sampleCount": 10,
"availability": "available",
"reason": null,
"definitionVersion": 1,
"activeFeedSetVersion": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"windowStart": "2026-09-01T12:00:00.000Z",
"windowEnd": "2026-10-01T12:00:00.000Z",
"calculatedAt": "2026-10-01T12:00:00.000Z",
"expiresAt": "2026-10-01T12:10:00.000Z"
}
評定規則
目前的定義考慮的是過去 30 天內在活躍動態中開啟的任務,排除最初已完成的任務。 它衡量從錄製的開場事件到首次記錄的狀態變更的時間;一個可測量且無變動的任務,會將經過時間貢獻至計算時間。 缺少或縮短的歷史資料會減少可用性。 因此,平均 值不限於已執行的任務 ,也不代表最終解決的時間。
根據可測量的證據,平均在 86,400 秒或以下的時效為 complete;超過此時間則為 notComplete。 部分餵食登記處的評估值為 unknown。 若無歷史記錄,目前實作可返回 completion: "complete" 為 availability: "unavailable" 零平均;請勿將此視為測量的零秒回應時間。 成功的評估對象可能代表部分或無法取得的證據;依賴失敗則可回傳 503。
更新合規任務的狀態
將任務的工作流程狀態更新為「進行中」、「準備審查」或「忽略」,視任務目前狀態及其訂閱源是否允許忽略而定。 此操作需取得管理權限,並回傳確認狀態、修改時間及版本。 更改狀態會記錄你的工作流程進度;它無法修復根本問題,也無法標記任務為完成。
REST 要求
| Method | 要求 URI |
|---|---|
| PUT | https://api.partnercenter.microsoft.com/v1/compliance/tasks/{taskId}/status |
URI 參數
| Name | 類型 | Required | Description |
|---|---|---|---|
taskId |
字串 | Yes | 不透明的任務識別碼,由列表或詳細回應回傳,網址編碼為單一路徑段一次。 |
不支援查詢參數。
要求本文
使用包含所需status屬性的任務狀態更新請求。
只status供供應。 附加/重複屬性、缺失或非字串狀態,以及格式錯誤的 JSON 會回傳 400 個。
-
New且Complete無法由此操作設定;完整是系統管理的。 - 完成任務無法透過此操作更改。
- 忽略僅在訂閱允許
isIgnorable時才被允許()。 - 被忽略的任務可以維持「忽略」或重新開啟「進行中」,但不能直接進入「準備審查」。
- 伺服器內部會檢查並行性。 此端點不要求客戶端
If-Match標頭;回傳版本並非有文件記錄的客戶端前提條件。
範例請求
PUT https://api.partnercenter.microsoft.com/v1/compliance/tasks/usage-anomaly-detection%3A%3A11111111-1111-4111-8111-111111111111-22222222-2222-4222-8222-222222222222/status HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json
MS-CorrelationId: cccccccc-cccc-4ccc-8ccc-cccccccccccc
MS-RequestId: dddddddd-dddd-4ddd-8ddd-dddddddddddd
{
"status": "In Progress"
}
REST 響應
若成功,此方法會回傳 200 OK ,並會在回應實體 中更新任務狀態 。
ETag回應標頭與回傳版本相符。
回應範例
{
"taskId": "usage-anomaly-detection::11111111-1111-4111-8111-111111111111-22222222-2222-4222-8222-222222222222",
"status": "In Progress",
"lastModifiedDate": "2026-10-01T12:05:00.000Z",
"version": "\"44444444-4444-4444-8444-444444444444\""
}
Important
狀態更新記錄工作流程變更;它本身並未解決根本問題。 遇到衝突、逾時或回應無法確認更新時,先取得任務再決定是否重試。 有些失敗可能發生在原始碼狀態已被儲存後。 不要盲目重打PUT。
回應成功和錯誤碼
請參閱 合作夥伴中心的 REST 錯誤代碼 以獲得一般指引。 以下情況是針對這些操作的:
| HTTP 狀態 | 意義/客戶行動 |
|---|---|
| 200 | 成功完成清單、詳細資料、評估或狀態更新。 |
| 400 | 無效 ID、不支援/重複查詢參數、無效的篩選/頁面大小/延續、無效的正文,或不允許的狀態轉換。 請修正這個請求;對於無效的續作,請重新開始分頁。 |
| 401 | 驗證缺失或無效、需要額外驗證,或缺少多重身份驗證(MFA)。 取得合適的認證用戶憑證。 |
| 403 | 呼叫者不是受支援的委派夥伴使用者,租戶驗證失敗或權限被拒絕。 |
| 404 | 任務對已認證的合作夥伴/在活躍的動態中無法顯示,或是 API 未啟用。 |
| 409 | 無法確認是否同時變更或來源同步。 重試前先刷新任務。 |
| 415 | PUT 請求缺少所需的 JSON 內容類型。 |
| 503 | 合規資料、授權、分頁儲存或必要的依賴資料暫時無法取得。 寫入時,請檢查回應並重新整理再嘗試。 |
任務未找到的主體範例:
{
"code": 600026,
"description": "Compliance task not found.",
"source": "PCFraudEvents"
}
一般的合規性故障會使用 錯誤 資源。 驗證/多重驗證失敗和前門故障可能會使用不同的實體。 回應設定為 Cache-Control: no-store, private 和 Vary: Authorization。
Troubleshooting
當請求失敗時,請檢查請求網址、API 版本、標頭和 JSON 格式。 結合 HTTP 狀態碼與回應主體來決定下一步動作。 關於一般的 REST 除錯指引,請參見 測試與除錯。
記錄請求時間、操作、HTTP 狀態,以及請求與關聯識別碼,以便追蹤失敗呼叫。 在擷取日誌或網路追蹤時,請保護存取權杖。
對於清單請求,請使用未更改的返回 @odata.nextLink 。 如果續集過期,請從最初的請求重新開始。 對於結果不確定的狀態更新,請先取得任務目前狀態再嘗試。