--- title: 設計您的合規整合 url: https://platform.claude.com/docs/zh-TW/manage-claude/compliance-integration-patterns description: 在輪詢與游標驅動的 Activity Feed 取用方式之間做出選擇，將 Compliance API 事件與您的 SIEM 進行關聯，並規劃保留策略。 --- 若要啟用 Compliance API，請參閱[設定 Compliance API](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-api-access)。 **所需範圍：** Compliance Access Key 或 Admin API 金鑰上的 `read:compliance_activities`。 一個正式環境的 Compliance API 整合需要做出三項設計選擇：如何取用 Activity Feed（活動摘要）、其輸出如何與您的「security information and event management」（安全資訊與事件管理）系統，即 SIEM 進行關聯，以及活動與內容的長期副本存放於何處。這些選擇與端點本身無關；本頁協助您評估其中的取捨。 本頁假設您已閱讀以下頁面： * [查詢 Activity Feed](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-activity-feed)，其中定義了本文通篇引用的參數與分頁契約。 * [擷取與刪除聊天、檔案和專案](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-content-data)，其中定義了聊天、檔案和專案端點，以及[規劃內容保留](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-integration-patterns#plan-content-retention)中引用的 `deleted_at` 語意。 * [擷取工作階段逐字稿](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-sessions)，其中定義了本機與遠端工作階段端點。 ## 選擇摘要取用模式 Activity Feed 支援兩種取用模式：以 `created_at.gte` 和 `created_at.lt` 為界的定期視窗輪詢（window polling），以及游標驅動的增量讀取（cursor-driven incremental reads），後者會保存某次回應中的游標並在下一次請求時傳入。兩者回傳的 `Activity` 物件完全相同；差異在於您的用戶端在呼叫之間所保存的狀態。 兩種模式共享以下限制： * 活動在發生後 1 分鐘內即可查詢，並保留 6 年。記錄不具追溯性：記錄從您的組織首次啟用 Compliance API 時開始，啟用前的活動不會回填。 * 每頁的最大 `limit` 為 5,000。 * 游標值是不透明的字串，您不得解析它們。 * 每個[父組織](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-api#how-the-compliance-api-works)的請求上限為每分鐘 600 次，由所有金鑰、所有連結的組織以及所有 `/v1/compliance/*` 端點共用；與本機工作階段端點不同，遠端工作階段端點在此之上還有第二層請求額度。請參閱 [429 Too Many Requests](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#429-too-many-requests) 以了解回應標頭與重試契約。 | 模式 | 適用情境 | | --------- | -------------------------------------------------------------------- | | 視窗輪詢 | 您的管線依固定排程執行、您偏好無狀態的工作程序，且您可以容忍重播或重疊的視窗 | | 游標驅動的增量讀取 | 您希望活動發生與管線擷取之間的延遲（latency）最低、您希望避免重新讀取已經取完的頁面，且您有一個持久的位置可在各次執行之間保存游標 | ### 視窗輪詢 將 `created_at.lt` 設定為至少過去 1 分鐘，以確保視窗中的每個活動都已可查詢。使用 `created_at.gte` 作為下界、`created_at.lt` 作為上界，使連續的視窗能無縫銜接、不留空隙也不重疊；將前一個視窗的 `lt` 值重複用作下一個視窗的 `gte`。 ```bash cURL curl --fail-with-body -sS -G \ "https://api.anthropic.com/v1/compliance/activities" \ --header "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \ --header "anthropic-version: 2023-06-01" \ --data-urlencode "created_at.gte=2026-04-20T07:00:00Z" \ --data-urlencode "created_at.lt=2026-04-20T08:00:00Z" \ --data-urlencode "limit=5000" ``` 當回應中 `has_more: true` 時，表示該視窗包含超過一頁的活動。您可以在視窗內分頁，將回應的 `last_id` 作為下一次請求的 `after_id` 傳入（當 `has_more` 為 `false` 時停止），或選擇較小的時間視窗。完整契約請參閱[分頁結果](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-activity-feed#paginate-results)。 即使銜接得很乾淨，在其視窗關閉後才完成索引的活動也永遠不會出現在之後的視窗中。請依活動 `id` 去除重複，並且要麼將每個新視窗加寬，使其與前一個視窗重疊幾分鐘，要麼執行定期的對帳程序，重新查詢較舊的視窗。 `created_at.lt` 界限若過於接近當下，會無聲且永久地遺漏延遲索引的活動：一旦 `created_at.gte` 推進超過它們，之後的任何視窗都無法將其找回。請將 1 分鐘可查詢性的數字視為文件記載的索引延遲，而非軟性建議。 ### 游標驅動的增量讀取 ```bash cURL first_id="activity_01XyDMpzjS89pFZXqSFUBDr6" # first_id from a previous response curl --fail-with-body -sS -G \ "https://api.anthropic.com/v1/compliance/activities" \ --header "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \ --header "anthropic-version: 2023-06-01" \ --data-urlencode "limit=5000" \ --data-urlencode "before_id=$first_id" ``` 逐頁讀取直到 `has_more` 為 `false`，然後保存最後一次回應中的 `first_id`，並在下一次執行時原封不動地將其作為 `before_id` 傳入，以擷取比已儲存游標更新的活動。若要反方向走訪以進行回填，請改為保存 `last_id` 並將其作為 `after_id` 傳入。完整的游標與頁面權杖對照參考及重試語意，請參閱[分頁結果](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-activity-feed#paginate-results)。 正式環境的**追趕（catch-up）**迴圈會以 `has_more` 和 `first_id` 驅動迭代，擷取自您上次輪詢以來記錄的活動： ```text cursor = stored_cursor loop: page = GET /v1/compliance/activities?before_id={cursor}&limit=5000 store(page.data) if page.first_id is not null: cursor = page.first_id if not page.has_more: break persist(cursor) ``` 游標在金鑰輪替後仍然有效；請參閱[管理與輪替金鑰](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-api-access#manage-and-rotate-keys)。 每一頁都與您傳入的游標相鄰：迴圈朝當下向前走訪，一次一頁。當 `has_more` 為 `true` 時，不要將單一回應視為已追上進度。僅在 `has_more` 為 `false` 之後才保存游標；尚未擷取的頁面是介於此回應的 `first_id` 與當下之間較新的頁面，在您完成迴圈或再次執行之前，它們都維持未讀狀態。 ## 與您的 SIEM 進行關聯 每個 `Activity` 都帶有可與您 SIEM（Splunk、Datadog、Microsoft Sentinel、Cribl 或類似系統）中既有事件進行聯結的欄位： | Compliance API 欄位 | 聯結目標 | | --------------------- | ---------------------- | | `actor.user_id` | 您的身分識別提供者的穩定使用者識別碼 | | `actor.email_address` | 無法取得穩定 ID 時的目錄電子郵件 | | `actor.ip_address` | 網路、VPN 與端點日誌 | | `actor.user_agent` | 端點與裝置清冊，以及發出請求的用戶端應用程式 | | `created_at` | 跨任何來源的時間視窗關聯 | 當 `actor.type` 為 `user_actor` 時，`actor.user_id` 和 `actor.email_address` 會存在。`actor.ip_address` 和 `actor.user_agent` 在某些 actor 類型上不存在，例如 `anthropic_actor` 和 `scim_directory_sync_actor`。在讀取這些欄位之前，請先檢查鑑別器（discriminator）。`user_id` 是使用者帳戶的穩定、不透明識別碼：它在每個 Compliance API 端點與活動酬載中保持一致，且不會因使用者的電子郵件或顯示名稱變更而改變。請使用 `user_id` 而非 `email_address` 作為主要聯結鍵。 對 Compliance API 本身的呼叫會產生 `compliance_api_accessed` 活動。請將這些活動與其他活動類型一併擷取，讓您的 SIEM 記錄誰在何時查詢了合規資料。傳入 `activity_types[]=compliance_api_accessed` 以限定查詢範圍，然後在您的用戶端中，從每個 `actor.type` 為 `api_actor` 的活動讀取 `actor.api_key_id`，以將該次存取歸屬於特定的 Compliance Access Key 或 Admin API 金鑰。 ## 規劃內容保留 五種保留期限決定了您日後可以擷取的內容： | 資料 | 保留期限 | 控制方 | | -------------------------------------- | --------------------------------------------------------- | --------------------------------- | | Activity Feed 記錄 | 6 年 | Anthropic | | 聊天、檔案和專案內容 | 依您組織的 claude.ai 保留政策，除非使用者提早刪除 | 您的組織 | | 本機工作階段逐字稿（在使用者電腦上的工作階段） | 預設為 6 年，若您的組織設定了有限的自訂對話保留期間，則依該期間；在已啟用 HIPAA 就緒的組織中為 30 天 | 預設為 Anthropic；若您的組織設定了自訂期間，則為您的組織 | | 遠端工作階段逐字稿（在雲端的工作階段） | 6 年，除非使用者提早刪除該工作階段 | Anthropic | | 透過 Compliance API「hard-delete」（硬刪除）的內容 | 不保留；刪除會立即生效且無法復原 | `DELETE` 端點的呼叫者 | 若要了解 Claude Platform 其他部分如何處理保留，請參閱 [API 與資料保留](https://platform.claude.com/docs/zh-TW/manage-claude/api-and-data-retention)。 請依下列方式在「匯出並封存」與「隨需 API 擷取」之間做出決定： * 如果您對活動中繼資料或工作階段記錄的「legal hold」（法律保全）或稽核期限超過 6 年，請在擷取 Activity Feed 頁面與工作階段記錄時，將其匯出至您自己的封存。 * 如果您的內容保留政策短於您的「eDiscovery」（電子證據開示）期限，請在保留期限到期前匯出聊天與檔案內容；Compliance API 無法回傳已被保留政策移除的內容。本機工作階段記錄也是如此：若您的組織設定了有限的自訂對話保留期間，本機工作階段記錄會依循該期間，即使該期間短於 6 年。設定一經變更，本機工作階段端點就會停止回傳早於您組織目前期間的訊息，而且之後延長期間也無法還原已過期的記錄，因此請匯出任何您必須保留超過該期間的記錄。 * 如果您必須在使用者於 claude.ai 中刪除聊天內容或遠端工作階段記錄後仍保留它們（例如在法律保全下），請在擷取時將聊天、檔案、artifact 和遠端工作階段內容匯出至您自己的封存；Compliance API 無法回傳使用者已刪除的內容。 * 如果某個工作流程可能會發出 Compliance API 硬刪除（例如「data loss prevention」（資料外洩防護），即 DLP 的強制執行），請先擷取並封存目標內容。硬刪除之後沒有復原期。 在其他所有情況下，請依賴直接的 API 擷取，避免維護平行副本。 ### 傳遞保證與完整性 請將 Activity Feed 視為**至少一次（at-least-once）**：正確分頁的走訪會至少回傳每個活動一次，但在部分失敗後的重試可能會重新傳遞您已儲存的活動。請依活動 `id` 欄位去除重複。 列表端點不會回傳 `total_count` 欄位或校驗和。若要證明某次匯出執行是完整的，請記錄： * 起始游標與終止的 `last_id`。 * 匯出的記錄數量。 * 執行時間戳記與最後一頁的 `request-id`。 活動數量並非完整性檢查。`claude_*_viewed` 活動類型（例如 `claude_chat_viewed`）遵循各應用程式的載入模式（請參閱[了解 Activity 物件](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-activity-feed#understand-the-activity-object)）。某段期間有聊天訊息但沒有 `claude_chat_viewed` 活動，本身並不表示資料遺失。請改為依賴走訪以及[視窗輪詢](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-integration-patterns#window-polling)中所述的重疊或對帳程序。 內容端點（聊天、檔案、專案、專案附件，以及本機與遠端工作階段逐字稿）僅提供 Claude Enterprise 資料。Activity Feed 則呈現全組織範圍的管理與資源事件。Compliance API 不包含： * 來自 Claude Console，或來自以 API 金鑰驗證的 Claude API 工作負載的提示文字或模型回應。 * 本機工作階段中從未傳送至 Anthropic 的裝置端活動，例如 Claude 未讀取的本機檔案。 * 以 Claude Console API 金鑰驗證、透過第三方雲端平台（Amazon Bedrock、Google Cloud 或 Microsoft Foundry）執行，或在 [Claude Code 雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web)中執行的 Claude Code 使用情況；Claude Code 雲端工作階段是在雲端基礎架構上執行，而非在使用者的電腦上執行。 * 已啟用 [HIPAA 就緒](https://platform.claude.com/docs/zh-TW/manage-claude/api-and-data-retention#hipaa-readiness)的組織中來自 Cowork 和 Claude Code 以外產品的本機工作階段，以及適用[零資料保留](https://platform.claude.com/docs/zh-TW/manage-claude/api-and-data-retention#zero-data-retention-zdr-scope)的本機工作階段。 * 工作階段逐字稿中的思考區塊，以及圖片或其他二進位內容（逐字稿僅包含使用者提示、助理回應和工具活動；本機工作階段逐字稿會在省略二進位內容之處顯示一個預留位置 `text` 區塊）。 * claude.ai 以擷取文字形式儲存的聊天附件原始檔案，例如部分 Word、PowerPoint 和 PDF 上傳檔案（檔案內容端點會回傳擷取出的文字；請參閱[擷取檔案與 artifact](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-content-data#retrieve-files-and-artifacts)）。 * 本機工作階段的系統提示（會以一則標記訊息代替）。 * 工作階段逐字稿（本機或遠端）中的工具定義與 MCP 伺服器設定，以及本機工作階段逐字稿中 `text` 區塊上的引用中繼資料。 * 組織的[客戶管理加密金鑰](https://platform.claude.com/docs/zh-TW/manage-claude/cmek)目前無法使用時，該組織中的本機工作階段逐字稿內容。這些請求會回傳 [503 Service Unavailable](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-errors#local-sessions-temporarily-unavailable)，但工作階段中繼資料仍會列出。 * 已被您組織的保留政策移除的內容。 * 使用者在 claude.ai 中刪除的聊天內容（這些聊天仍會列出，並填入 `deleted_at`）。 * 使用者刪除的遠端工作階段（已刪除的工作階段不再列出，且訊息端點會對其回傳 404）。 * 透過 Compliance API 硬刪除的內容。 請參閱 [Compliance API 常見問題](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-faq#data-coverage-and-retention)，以進一步了解 Compliance API 會擷取與不會擷取的內容。 為了維護監管鏈（chain of custody），請將匯出的記錄連同來源中繼資料一併儲存：來源端點、查詢參數、執行時間戳記，以及每筆記錄的內容雜湊值。 ## 後續步驟 篩選參數、分頁，以及 `Activity` 物件結構描述。 聊天、檔案和專案端點，包括硬刪除。 列出您的使用者在 Claude 應用程式與代理（例如 Cowork 和 Claude Code）中執行的工作階段，並擷取其逐字稿。