# 设计您的合规集成

在轮询和游标驱动的活动动态消费之间做出选择，将 Compliance API 事件与您的 SIEM 进行关联，并规划数据保留。

---

<Note>
  Compliance API 需申请开通。Claude Enterprise 组织可访问完整 API；Claude Console 组织仅可访问[活动动态](/docs/en/manage-claude/compliance-activity-feed)。请参阅[获取 Compliance API 访问权限](/docs/en/manage-claude/compliance-api-access)。
</Note>

<Check>
  **所需权限范围：** Compliance Access Key 或 Admin API key 上的 `read:compliance_activities`。
</Check>

一个生产级的 Compliance API 集成需要做出三个设计决策：如何消费活动动态、其输出如何与安全信息和事件管理（SIEM）系统关联，以及活动和内容的长期副本存储在哪里。这些决策与端点本身无关；本页帮助您评估权衡。

本页假设您已阅读[查询活动动态](/docs/en/manage-claude/compliance-activity-feed)，其中定义了贯穿全文引用的参数和分页契约，以及[检索和删除聊天、文件和项目](/docs/en/manage-claude/compliance-content-data)，其中定义了[规划内容保留](#规划内容保留)中引用的内容端点和 `deleted_at` 语义。

## 选择动态消费模式

活动动态支持两种消费模式：由 `created_at.gte` 和 `created_at.lt` 限定的定期窗口轮询，以及游标驱动的增量读取（持久化一个响应中的游标并在下一个请求中传入）。两者返回相同的 `Activity` 对象；区别在于客户端在调用之间持久化的状态。

两种模式共享以下约束：

- 活动在发生后 1 分钟内即可查询，保留期限为 6 年。
- 每页的最大 `limit` 为 5,000。
- 游标值是不透明字符串，您不得解析。
- 请求限制为每个[父组织](/docs/en/manage-claude/compliance-api#how-the-compliance-api-works)每分钟 600 次，跨所有密钥、所有关联组织和所有 `/v1/compliance/*` 端点共享；请参阅 [429 Too Many Requests](/docs/en/manage-claude/compliance-errors#429-too-many-requests)了解响应头和重试契约。

| 模式 | 适用场景 |
| :---- | :---- |
| 窗口轮询 | 您的管道按固定计划运行，您偏好无状态工作线程，并且可以容忍重放或重叠窗口 |
| 游标驱动的增量读取 | 您希望活动发生到管道摄取之间的延迟最低，您希望避免重新读取已排空的页面，并且您有持久化的位置在运行之间存储游标 |

### 窗口轮询

将 `created_at.lt` 设置为至少 1 分钟前，以确保窗口中的每个活动都已可查询。使用 `created_at.gte` 作为下限，`created_at.lt` 作为上限，使连续窗口无缝拼接而无间隙或重叠；将前一个窗口的 `lt` 值作为下一个窗口的 `gte` 重用。

<CodeGroup>
```bash cURL nocheck
curl --fail-with-body -sS -G \
  "https://api.anthropic.com/v1/compliance/activities" \
  --header "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
  --data-urlencode "created_at.gte=2026-04-20T07:00:00Z" \
  --data-urlencode "created_at.lt=2026-04-20T08:00:00Z" \
  --data-urlencode "limit=5000"
```
</CodeGroup>

当响应的 `has_more` 为 `true` 时，窗口中的活动超过一页。可以在窗口内通过将响应的 `last_id` 作为 `after_id` 传入下一次请求来分页（当 `has_more` 为 `false` 时停止），或选择更小的时间窗口。请参阅[分页结果](/docs/en/manage-claude/compliance-activity-feed#paginate-results)了解完整契约。

即使窗口拼接干净，在其窗口关闭后才索引的活动永远不会出现在后续窗口中。根据活动 `id` 进行去重，并且要么扩大每个新窗口使其与前一个窗口重叠几分钟，要么运行定期核对任务重新查询较早的窗口。

<Warning>
  `created_at.lt` 限制过于接近当前时间会静默且永久地丢失延迟索引的活动：一旦 `created_at.gte` 推进超过它们，后续窗口将无法恢复它们。请将 1 分钟的可查询时间视为已记录的索引延迟，而非软性建议。
</Warning>

### 游标驱动的增量读取

<CodeGroup>
```bash cURL nocheck
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" \
  --data-urlencode "limit=5000" \
  --data-urlencode "before_id=$first_id"
```
</CodeGroup>

逐页浏览直到 `has_more` 为 `false`，然后持久化最终响应的 `first_id` 并在下一次运行中原样作为 `before_id` 传入以检索比保存的游标更新的活动。要向相反方向回填，请改为持久化 `last_id` 并作为 `after_id` 传入。有关游标与页面令牌的完整参考和重试语义，请参阅[分页结果](/docs/en/manage-claude/compliance-activity-feed#paginate-results)。

生产环境中的**追赶**循环通过驱动 `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)
```

游标在密钥轮换后仍然有效；请参阅[管理和轮换密钥](/docs/en/manage-claude/compliance-api-access#manage-and-rotate-keys)。

<Warning>
  每一页都与您传入的游标相邻：循环逐页向前推进到当前时间。当 `has_more` 为 `true` 时，不要将单个响应视为已追上。仅在 `has_more` 为 `false` 后才持久化游标；未获取的页面是此响应 `first_id` 与当前时间之间的更新页面，在您完成循环或再次运行之前它们保持未读状态。
</Warning>

## 与您的 SIEM 进行关联

每个 `Activity` 携带您可以与 SIEM（Splunk、Datadog、Microsoft Sentinel、Cribl 或类似系统）中已有事件进行关联的字段：

| Compliance API 字段 | 关联目标 |
| :---- | :---- |
| `actor.user_id` | 您身份提供商的稳定用户标识符 |
| `actor.email_address` | 当稳定 ID 不可用时使用目录邮箱 |
| `actor.ip_address` | 网络、VPN 和端点日志 |
| `created_at` | 跨任何来源的时间窗口关联 |

当 `actor.type` 为 `user_actor` 时，`actor.user_id` 和 `actor.email_address` 存在；读取前请检查判别器。`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 key。

## 规划内容保留

三个保留范围决定了您稍后可以检索的内容：

| 数据 | 保留期限 | 控制方 |
| :---- | :---- | :---- |
| 活动动态记录 | 6 年 | Anthropic |
| 聊天、文件和项目内容 | 组织的 claude.ai 保留策略 | 您的组织 |
| 通过 Compliance API 硬删除的内容 | 不保留；删除即时且永久 | `DELETE` 端点的调用者 |

有关 Claude 平台其余部分如何处理保留的更多信息，请参阅 [API 和数据保留](/docs/en/manage-claude/api-and-data-retention)。

按以下方式决定是导出归档还是按需 API 检索：

- 如果您的法律保留或审计范围对活动元数据超过 6 年，请在摄取活动动态页面时将其导出到您自己的归档中。
- 如果您的内容保留策略短于电子发现范围，请在保留窗口到期前导出聊天和文件内容；Compliance API 无法返回已被保留策略移除的内容。
- 如果工作流可能发出 Compliance API 硬删除（例如 DLP 执行），请先检索并归档目标内容。硬删除后没有恢复窗口；从 claude.ai 软删除的内容仍可通过 `deleted_at` 填充来检索，但 Compliance API 删除则不行。

在所有其他情况下，依赖直接 API 检索，避免维护并行副本。

### 交付保证和完整性

将活动动态视为**至少一次**：正确分页的遍历会返回每个活动至少一次，但部分失败后的重试可能会重新交付您已存储的活动。根据活动 `id` 字段进行去重。

列表端点不返回 `total_count` 字段或校验和。要证明导出运行已完成，请记录：

- 起始游标和终止 `last_id`。
- 导出的记录数。
- 运行时间戳和最后一页的 `request-id`。

内容端点（聊天、文件、项目和项目附件）仅提供 claude.ai 数据；活动动态在组织范围内呈现管理和资源事件。Compliance API 不包括：

- 来自 Claude Console 或 Claude API 工作负载的提示词文本或模型响应。
- 被组织保留策略移除的内容。
- 通过 Compliance API 硬删除的内容。

请参阅 [Compliance API 常见问题](/docs/en/manage-claude/compliance-faq#data-coverage-and-retention)了解 Compliance API 捕获和不捕获的更多内容。

为确保监管链，请将导出的记录与来源元数据一起存储：源端点、查询参数、运行时间戳和每条记录的内容哈希。

## 后续步骤

<CardGroup cols={2}>
  <Card title="查询活动动态" href="/docs/en/manage-claude/compliance-activity-feed">
    筛选参数、分页和 `Activity` 对象架构。
  </Card>
  <Card title="检索和删除聊天、文件和项目" href="/docs/en/manage-claude/compliance-content-data">
    内容和硬删除端点。
  </Card>
</CardGroup>