Docker Sandboxes

Audit Logs API 用于获取云端交付的 Docker AI Governance 事件，以支持自动化、调查和报告。 该 API 返回的数据与托管审计日志视图中显示的事件数据相同。

前置条件 ​

使用该 API 之前，你需要：

不支持 Personal Access Token 和 Docker 账户会话令牌。

创建访问令牌 ​

为要获取事件的那个组织创建 OAT：

  1. 登录 Docker Home 并选择你的组织。
  2. 选择 Identity & auth，然后选择 Access tokens。
  3. 选择 Generate access token。
  4. 在 AI Governance 组织权限下，选择 View audit logs。
  5. 选择 Generate token，然后把令牌保存在凭据管理器中。

有关令牌过期、轮换和管理的说明，请参阅 组织访问令牌。

为示例设置变量：

bash
ORG="<YOUR_ORGANIZATION_NAME>"
OAT="<YOUR_ORGANIZATION_ACCESS_TOKEN>"

在 bearer 头中传入原始 OAT。不要把它换成其他令牌。

列出审计事件 ​

请求你的组织的前 25 个事件：

console
$ curl --get "https://api.docker.com/v2/auditlogs/governance/$ORG" \
  --header "Authorization: Bearer $OAT" \
  --data-urlencode "page_size=25" | jq .

事件按时间倒序返回。响应包含一个事件数组和一个指向下一页的不透明游标：

json
{
  "events": [
    {
      "audit_event_id": "95e7257f-93c9-4f29-bde7-88830e2dae80",
      "org_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
      "event_type": "docker.marlin.audit.event.v1.AuditRecord",
      "category": "AUDIT_CATEGORY_EVALUATION",
      "decision": "AUDIT_DECISION_DENY",
      "action_type": "network_egress",
      "enforcement_mode": "enforce",
      "audit_session_id": "8a3bc076-79d0-4502-baf3-cc6ad35fb578",
      "username": "jordandoe",
      "created_at": "2026-08-25T18:42:31.123Z",
      "ingested_at": "2026-08-25T18:42:31.456Z",
      "payload": {
        "resource_id": "example.com:443",
        "agent": "claude",
        "network_egress": { "protocol": "tcp" }
      }
    }
  ],
  "next_page_token": "eyJ0cyI6IjIwMjYtMDgtMjVUMTg6NDI6MzEuMTIzWiIsImVpZCI6Ijk1ZTcyNTdmLTkzYzktNGYyOS1iZGU3LTg4ODMwZTJkYWU4MCIsImZyb20iOiIyMDI2LTA4LTAxVDAwOjAwOjAwWiIsInRvIjoiMjAyNi0wOC0yNVQyMzo1OTo1OVoifQ"
}

有关 category、decision、action 和 payload 字段，请参阅 审计记录参考。

筛选事件 ​

使用查询参数缩小结果集：

参数匹配行为
from, to处于包含端点的 RFC 3339 时间范围内的事件
audit_session_id完全匹配的会话 ID
username完全匹配的 Docker 用户名
decision完全匹配的审计判定
enforcement_mode完全匹配的 audit、warn 或 enforce 模式
action_type完全匹配的行为类型
query在用户名、行为类型、判定和事件类型上进行的不区分大小写的文本搜索
resource_id不区分大小写的资源 ID 前缀
agent完全匹配的智能体值

例如，获取某个时间范围内被拒绝的网络事件：

console
$ curl --get "https://api.docker.com/v2/auditlogs/governance/$ORG" \
  --header "Authorization: Bearer $OAT" \
  --data-urlencode "decision=AUDIT_DECISION_DENY" \
  --data-urlencode "action_type=network_egress" \
  --data-urlencode "from=2026-08-01T00:00:00Z" \
  --data-urlencode "to=2026-08-25T23:59:59Z" | jq .

每次请求覆盖的时间范围不超过 30 天。如果省略 to，它默认为请求发起时间。如果省略 from，它默认为 to 之前 30 天。from 时间戳必须早于 to。要获取更长的历史记录， 请针对最长 30 天的各个时间范围分别发起请求。

query 搜索使用相同的时间范围默认值。去除空白字符后，搜索词必须包含 3 到 256 字节。 resource_id 和 agent 的值在去除空白字符后各自不得超过 256 字节。

获取下一页 ​

该 API 默认最多返回 25 个事件，并把 page_size 上限设为 100。page_size 为 0 时使用 默认值；负值会被拒绝。超过 100 的值最多返回 100 个事件。

当 next_page_token 不为空时，原样把它作为 page_token 传入：

console
$ curl --get "https://api.docker.com/v2/auditlogs/governance/$ORG" \
  --header "Authorization: Bearer $OAT" \
  --data-urlencode "page_size=25" \
  --data-urlencode "page_token=$NEXT_PAGE_TOKEN" | jq .

在翻阅同一个结果集时保持筛选条件不变。游标会保留首次请求的时间范围，包括默认时间戳。 后续页面可以省略 from 和 to；如果提供，则必须与游标的时间范围一致。当 next_page_token 为空时停止。

请求限制 ​

该 API 和 gateway 各自对每个组织强制执行每秒 5 个请求的限制。组织内的所有客户端和令牌 共享这些限制。每次翻页请求都计入其中。gateway 还限制每个源 IP 地址每分钟 600 个请求。 同时也适用 gateway 的平台限制。

超出限制的请求会收到 429 Too Many Requests。应用层限流响应包含以下字段：

字段含义
coderate_limit_exceeded
policyaudit_governance
scopeorganization
limit配置的请求配额
window_seconds配额窗口的时长（秒）
retry_after_seconds重试前需要等待的秒数（当重置时间已知时）

请使用 code 和结构化字段来处理应用层限流，而不是匹配便于阅读的 error 消息。当重置 时间已知时，响应会包含 Retry-After 头，其延迟时间相同，并向上取整到整秒。被拒绝的请求 不会延长配额窗口。

gateway 的限流响应可能具有不同的响应体，并且省略 Retry-After。如果存在 Retry-After， 请等待其中的延迟时间。否则，请使用指数退避重试，而不是立即反复发送请求。

处理查询错误 ​

400 Bad Request 响应表示参数无效，或分页令牌与提供的时间范围不匹配。重试前请修正请求。

遇到 503 Service Unavailable 时，请使用指数退避重试。如果响应提示搜索超时，请使用更窄 的时间范围或更简单的查询。408 Request Timeout 响应表示超出了请求截止时间。

API 参考 ​

有关完整的请求和响应结构，请参阅 Audit Logs API 参考。