--- title: Security posture 結果參考資料 url: https://platform.claude.com/docs/zh-TW/manage-claude/compliance-security-posture/results-reference description: 查詢會傳回組織目前 Security posture 結果的 Compliance API 端點：請求、回應欄位、各狀態的意義，以及錯誤。 --- 若要啟用 Compliance API，請參閱[設定 Compliance API](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-api-access)。 此端點會為組織的大多數安全控制措施各傳回一個項目，這些項目於請求當下進行評估，並附上回應中針對每項控制措施所包含的 [Security posture 聲明](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-security-posture/overview#attestations)。您需要一個涵蓋該組織、且具有 `read:compliance_org_data` 或 `read:org_audit` 範圍的 Compliance Access Key；[Security posture 可用性](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-security-posture/overview#availability)說明了可讀取哪些組織。 ## 請求 向 `/v1/compliance/organizations/{organization_id}/security_posture` 傳送 `GET` 請求。每次呼叫讀取一個組織，且回應不分頁。 ```bash cURL curl --fail-with-body -sS \ "https://api.anthropic.com/v1/compliance/organizations/91012d09-e48b-438e-a489-1bebfd8fa6f9/security_posture" \ -H "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \ -H "anthropic-version: 2026-10-21" ``` | 項目 | 規則 | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `organization_id` | 來自[列出組織](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-org-data#list-organizations)的[已連結組織](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-api#how-the-compliance-api-works)的 `uuid`；任何其他值都會傳回 404。 | | 金鑰 | [上層組織的金鑰](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-api-access#set-up-the-compliance-api)可指定任一已連結組織，而單一組織的金鑰只能指定該組織。 | | `anthropic-version` | 必要；缺少此項的請求會傳回 400。 | | 查詢參數 | 無；帶有任一查詢參數的請求會傳回 400。 | ## 回應 以下節錄範例顯示回應可能包含的其中四項控制措施。這是對持有 `read:compliance_org_data` 與 `read:compliance_user_data` 之金鑰的回應。 ```json Response { "type": "security_posture", "organization_id": "91012d09-e48b-438e-a489-1bebfd8fa6f9", "evaluated_at": "2027-02-09T09:00:02.417305Z", "comments_status": "not_enabled", "controls": [ { "id": "sso_enabled", "display_name": "Single sign-on (SSO)", "section": "identity_access", "setting_name": "sso_enabled", "status": "passed", "rating": "passed", "current_value": "On", "desired_state": "On", "attestation": null }, { "id": "directory_sync_enabled", "display_name": "Directory sync (SCIM)", "section": "identity_access", "setting_name": "directory_sync_enabled", "status": "failed_check_accepted_risk", "rating": "passed", "current_value": "Off", "desired_state": "On", "attestation": { "state": "in_force", "attested_at": "2026-10-20T15:04:00.220114Z", "comment": null, "attested_by": { "type": "user_actor", "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu" } } }, { "id": "allowed_invite_domains", "display_name": "Allowed email domains", "section": "identity_access", "setting_name": "allowed_invite_domains", "status": "descriptive", "rating": "descriptive", "current_value": "example.com", "desired_state": null, "attestation": null }, { "id": "oauth_conditional_access", "display_name": "OAuth conditional access on connected SaaS", "section": "connectors_integrations", "setting_name": null, "status": "not_attested", "rating": "not_attested", "current_value": null, "desired_state": "Completed", "attestation": { "state": "review_due", "attested_at": "2026-11-02T09:30:00.008771Z", "comment": null, "attested_by": { "type": "user_actor", "user_id": "user_01AbCdEfGhJkLmNpQrStUvWx" } } } ] } ``` 每個欄位一律存在，沒有值的欄位為 `null`，絕不會省略。時間的小數位數不是零位就是六位，因此請以時間而非字串的方式比較時間。 ### 頂層欄位 | 欄位 | 類型 | 說明 | | ----------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | 字串 | 一律為 `security_posture`。 | | `organization_id` | 字串 | 組織的 UUID。 | | `evaluated_at` | 字串（RFC 3339，UTC） | 評估所有控制措施的時間。 | | `comments_status` | 字串 | 是否已讀取聲明備註；請參閱[聲明者與備註](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-security-posture/results-reference#who-attested-and-comments)。 | | `controls` | 物件陣列 | 組織的控制措施，絕不為空。 | ### `controls[]` 欄位 | 欄位 | 類型 | 說明 | | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | 字串 | 控制措施的識別碼，對每個組織都相同且永不變更。 | | `display_name` | 字串 | 控制措施的顯示名稱，為英文顯示文字，其措辭可能變更。 | | `section` | 字串 | 控制措施所屬的區段，為本表格之後列出的十個區段之一；未來可能新增更多值，因此請將未知值視為獨立的區段。 | | `setting_name` | 字串或 null | 此控制措施所讀取之組織有效設定中該項目的 `name`；若未讀取此類項目則為 `null`。 | | `status` | 字串 | 控制措施結果的原因；請參閱[狀態值](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-security-posture/results-reference#status-values)。 | | `rating` | 字串 | 控制措施的結果，由 `status` 決定；請參閱[狀態值](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-security-posture/results-reference#status-values)。 | | `current_value` | 字串或 null | 目前值，為英文顯示文字，其措辭可能變更；在手動控制措施上或未讀取到任何值時為 `null`。 | | `desired_state` | 字串或 null | 建議值，為英文顯示文字，其措辭可能變更；若此組織沒有建議值則為 `null`。 | | `attestation` | 物件或 null | 回應中包含的聲明，在其未處於生效中時亦同；當 `status` 為 `descriptive`、`not_applicable` 或 `not_evaluated` 時，以及在[這些情況](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-security-posture/results-reference#how-an-attestation-shows-in-the-response)下為 `null`。 | `section` 為下列其中之一：`identity_access`、`data_privacy`、`capabilities`、`connectors_integrations`、`chats_desktop_mdm`、`cowork_admin_console`、`cowork_desktop_mdm`、`claude_code_admin_console`、`claude_code_managed_settings` 與 `healthy_adoption`。 若要在程式碼中比較值，請在同一組織的[有效設定](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-org-data#get-effective-organization-settings)中查詢 `setting_name`。查詢可能找不到任何結果，且兩個控制措施可能共用同一個 `setting_name`。 ### `attestation` 欄位 | 欄位 | 類型 | 說明 | | ------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `state` | 字串 | 聲明是否生效中；請參閱[聲明生效情形](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-security-posture/results-reference#attestation-states)。 | | `attested_at` | 字串（RFC 3339，UTC） | 做出聲明的時間。 | | `comment` | 字串或 null | 與聲明一起儲存的備註，最多 2,000 個字元；若沒有備註，或 `comments_status` 不是 `available`，則為 `null`。 | | `attested_by` | 物件或 null | 做出聲明的人員；當金鑰既未持有 `read:compliance_user_data` 也未持有 `read:org_audit`、該人員的帳戶已刪除或正在刪除，或端點未傳回該組織做出聲明的人員時，為 `null`。 | ### `attested_by` 欄位 | 欄位 | 類型 | 說明 | | --------- | -- | --------------------- | | `type` | 字串 | 一律為 `user_actor`。 | | `user_id` | 字串 | 使用者的 ID，以 `user_` 開頭。 | ## 狀態值 `status` 提供控制措施結果的原因，且每個狀態對應一個 `rating`。 | `status` | 控制措施類型 | 意義 | `rating` | 頁面上顯示 | | ---------------------------- | ------ | --------------------------------- | -------------- | ------------------------ | | `passed` | 自動 | 目前值符合建議值。 | `passed` | 「通過」 | | `matches_profile` | 自動 | 目前值等於建議值。 | `passed` | 「通過」 | | `exceeds_baseline` | 自動 | 目前值比建議值更嚴格。 | `passed` | 「通過」 | | `failed_check_accepted_risk` | 自動 | 自動檢查不符合要求，且已接受風險生效中。 | `passed` | 「通過」 | | `failed` | 自動或手動 | 目前值不符合建議值，或回應中未包含的某項聲明導致此結果。 | `failed` | 「未通過」，或在「已完成」聲明生效中時為「通過」 | | `review` | 自動 | 目前值比建議值更寬鬆。 | `failed` | 「未通過」 | | `attested_completed` | 手動 | 值為「已完成」（`completed`）的聲明生效中。 | `passed` | 「通過」 | | `attested_accepted_risk` | 手動 | 值為「已接受風險」（`accepted_risk`）的聲明生效中。 | `passed` | 「通過」 | | `not_attested` | 手動 | 沒有生效中的聲明。 | `not_attested` | 「未聲明」 | | `attestation_not_enabled` | 手動 | 沒有人能對此控制措施做出聲明。 | `not_attested` | 「描述性」 | | `descriptive` | 僅供參考 | 此控制措施僅予報告，不予評定。 | `descriptive` | 「描述性」 | | `not_applicable` | 任一 | 此控制措施不適用於該組織。 | `descriptive` | 「描述性」 | | `not_evaluated` | 任一 | 無法讀取該設定，或決定此控制措施是否適用的另一項設定。 | `descriptive` | 「描述性」 | 沒有任何欄位標示控制措施的類型；對於 `failed`，`current_value` 為 `null` 即表示為手動控制措施。未來可能新增更多值，因此請依 `rating` 計算具有未知 `status` 的控制措施，且未知的 `rating` 不視為「通過」。狀態 `review` 與聲明生效情形 `review_due` 彼此無關。 ## 聲明生效情形 `state` 說明回應中包含的聲明是否生效中。 | `state` | 意義 | | ----------------- | -------------------------------------- | | `in_force` | 聲明生效中。 | | `review_due` | 結束日期已到。 | | `setting_changed` | 檢查不符合要求的值並非當初已接受其風險的值，或該已接受風險已被記錄為已終止。 | | `check_passing` | 檢查符合要求，因此沒有需要接受的風險。 | 當超過一個原因適用時，回應會依 `check_passing`、`setting_changed`、`review_due` 的順序提供第一個適用者。自結束日期當天 00:00 UTC 起，聲明即不再生效。回應中沒有結束日期，因此由 `state` 決定；已儲存的結束日期即為聲明活動的 [`review_date`](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-security-posture/events-reference#attestation-activity)。請將未知的 `state` 視為未生效。 ## 聲明如何顯示於回應中 回應中會包含部分聲明並省略其他聲明，因此 `attestation` 為 `null` 並不能證明沒有人做出聲明。 | 控制措施類型 | 聲明為 | `status` | `rating` | `attestation` | | ----------- | ----------------------- | -------------------------------------------------------- | -------------- | -------------------------- | | 手動 | 無聲明 | `not_attested`，或在沒有人能做出聲明的情況下為 `attestation_not_enabled` | `not_attested` | `null` | | 手動 | 「已完成」 | `attested_completed` | `passed` | 顯示 | | 手動 | 「已接受風險」 | `attested_accepted_risk` | `passed` | 顯示 | | 手動 | 「未通過」（`control_failed`） | `failed` | `failed` | `null`：一律不顯示 | | 自動，檢查不符合要求 | 無聲明 | `failed` 或 `review` | `failed` | `null` | | 自動，檢查不符合要求 | 「已接受風險」 | `failed_check_accepted_risk` | `passed` | 顯示 | | 自動，檢查不符合要求 | 「已完成」 | `failed`，即使自動檢查給出的是 `review` | `failed` | `null`：一律不顯示 | | 自動，檢查不符合要求 | 「未通過」 | 自動檢查給出的 `status` | `failed` | `null`：一律不顯示 | | 自動，檢查符合要求 | 無聲明 | `passed`、`matches_profile` 或 `exceeds_baseline` | `passed` | `null` | | 自動，檢查符合要求 | 「已完成」 | 自動檢查給出的 `status` | `passed` | `null`：一律不顯示 | | 自動，檢查符合要求 | 「已接受風險」 | 自動檢查給出的 `status` | `passed` | 當檢查在已接受的值上符合要求時為 `null` | | 自動，檢查符合要求 | 「未通過」 | `failed` | `failed` | `null`：一律不顯示 | | 僅供參考 | 任一值 | `descriptive` | `descriptive` | `null`：一律不顯示 | | 任一，在聲明未生效期間 | 先前某列中顯示的值 | 與無聲明時相同 | 與無聲明時相同 | 顯示，且 `state` 不是 `in_force` | | 任一，在聲明未生效期間 | 先前某列中省略的值 | 與無聲明時相同 | 與無聲明時相同 | `null` | 除最後兩列外，每一列都適用於聲明生效中的期間。在自動控制措施上，當檢查所讀取的值與聲明儲存時的值不同時，該聲明即不生效。回應中在自動控制措施上包含的每項聲明都是已接受風險。[Activity Feed](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-activity-feed) 也會記錄回應中省略的各類聲明。 ## 計算結果 依 `rating` 計算控制措施時，請檢查四件事。 | 若您計算 | 也請檢查 | | -------------------- | --------------------------------------------------------------------------------------------------- | | 「通過」（`passed`） | 其中包含每個已接受風險生效中的控制措施，因此請查找 `failed_check_accepted_risk` 與 `attested_accepted_risk`。 | | 「未通過」（`failed`） | 其中包含被聲明為「未通過」（`control_failed`）的控制措施，以及在「已完成」聲明生效中時自動檢查不符合要求的控制措施，而 Security posture 頁面會將後者顯示為「通過」。 | | 「描述性」（`descriptive`） | 其中可能隱藏無法讀取的控制措施，因此請查找 `not_evaluated`。 | | 所有控制措施 | 回應中缺少的控制措施不視為「通過」，且不會被列出名稱，因此請將 `id` 值與您先前在該組織看到的值進行比對。 | ## 聲明者與備註 只有在金鑰同時持有 `read:compliance_user_data` 與 `read:compliance_org_data`，或持有 `read:org_audit` 時，才會填入 `attested_by`。僅持有 `read:compliance_user_data` 的金鑰會收到 403。`attested_by` 中的 `user_id` 與聲明活動上 `actor` 的 `user_id` 相同。`attested_by` 僅包含使用者 ID：[列出組織使用者](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-org-data#list-organization-users)會提供每位目前成員的姓名與電子郵件地址。在新增這些範圍之前，請參閱[誰可以看到進行聲明的人員](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-security-posture/overview#who-can-see-who-attested)。 此端點不會傳回任何備註，即使 Security posture 頁面上顯示了備註也一樣：每個 `comment` 都是 `null`，且 `comments_status` 為 `not_enabled` 或 `not_permitted`。因此，`not_enabled` 與為 `null` 的備註並不表示該聲明沒有備註。`comments_status` 說明如何解讀為 `null` 的備註，而結構描述定義了下列值。 | `comments_status` | 意義 | | --------------------------- | -------------------------------------------------------------------------------------------------------- | | `not_permitted` | API 金鑰既未持有 `read:compliance_user_data` 也未持有 `read:org_audit`，因此每個 `comment` 與每個 `attested_by` 都是 `null`。 | | `requires_organization_key` | API 金鑰並非在該組織中建立（例如上層組織的金鑰），因此每個 `comment` 都是 `null`。重試並無幫助。 | | `available` | 已讀取備註，因此為 `null` 的備註表示沒有備註，或該備註剛在片刻前儲存。 | | `not_enabled` | 此端點不會傳回該組織的備註，因此每個 `comment` 都是 `null`。 | | `unavailable` | 此回應無法讀取備註；稍後的請求可能會成功，但某些原因會持續存在，直到客戶採取行動為止。 | 未來可能新增更多值；請將未知值視為 `unavailable`。 ## 錯誤 錯誤使用與 [Compliance API](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors) 其他部分相同的主體；下表列出此端點以其特有方式傳回的錯誤。 | 狀態與 `error.type` | 時機 | 處理方式 | | --------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | 400 `invalid_request_error` | `anthropic-version` 缺少或無效、上層組織未啟用 Compliance API，或帶有查詢參數。 | 修正 `error.message` 所指出的問題。 | | 401 `authentication_error` | 金鑰缺少、無法辨識，或不是 Compliance Access Key 或 Admin API 金鑰。 | 在 `x-api-key` 中傳送有效的 Compliance Access Key。 | | 403 `permission_error` | 金鑰不得呼叫此端點，通常是因為它同時缺少 `read:compliance_org_data` 與 `read:org_audit`。 | 使用具有其中任一範圍的金鑰。 | | 404 `not_found_error` | 請參閱此表格後列出的原因。 | 請勿立即重試，且絕不可將其解讀為沒有「未通過」的控制措施。 | | 429 `rate_limit_error` | 共用的 Compliance API 速率限制，或此端點較低的限制已用盡；`error.message` 會說明是哪一個。 | 等待 `retry-after`；請參閱 [429 Too Many Requests](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#429-too-many-requests)。 | | 503 `overloaded_error`，且 `error.details.error_code` 為 `posture_evaluation_failed` | 無法產生結果。 | 等待 `retry-after` 後再重試；若同一組織在後續執行中再次發生此問題，請聯絡 Anthropic 支援一次。 | | 不含 `error_code` 的 503，或 504 `timeout_error` | 暫時性失敗。 | 以指數退避方式重試。 | 404 的原因： * `organization_id` 不是 UUID、未指向任何組織，或指向已刪除的組織。 * `organization_id` 指向上層組織、另一個上層組織之下的組織，或單一組織金鑰未涵蓋的組織。 * 該組織未使用 Claude Enterprise，或 Security posture 無法供其使用，例如 Claude Console 組織。 * 該組織的 Security posture 頁面已被關閉（請參閱 [Security posture 可用性](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-security-posture/overview#availability)）。 * Security posture 可供該組織使用，但此端點不為該組織提供服務。 * 無法檢查可用性；稍後的請求可能會成功。 每個 404 的主體都相同，不存在的路徑亦然。 ## 資料即時性與副作用 此端點會在您呼叫時評估所有控制措施，而 `evaluated_at` 即為該時間。 * 最近幾分鐘內的變更可能不會顯示。 * 即使沒有變更任何設定，結果也可能改變，例如當結束日期到來，或 Anthropic 變更某個建議值時。 * 若 Anthropic 改寫某個目前值的措辭，針對該值的已接受風險即不再生效。 * 呼叫不會儲存任何結果，也不會終止任何聲明。 * 每個通過金鑰、範圍與版本檢查且不含查詢參數的請求，無論成功或失敗，都會記錄一筆 `compliance_api_accessed` 活動；其 `url` 會指出所讀取的組織，而對於上層組織的金鑰，`organization_uuid` 為 `null`。