> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 沙箱事件

本节介绍如何查询沙箱生命周期中的关键事件，适用于问题排查、审计、用量分析和账单核对等场景。

## 查询沙箱事件

通过 Events API 可以获取当前账号下的沙箱事件列表，并按沙箱、模板、事件类型、状态和时间范围等条件过滤结果。

### 使用 SDK 查询事件

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={null}
  import { Sandbox } from 'ppio-sandbox/code-interpreter'

  const result = await Sandbox.getEvents({
    sandboxID: 'iq721h44siv24wmyrh5oc',
    events: ['create', 'pause', 'resume', 'connect', 'timeout', 'delete'],
    limit: 10,
    offset: 0,
  })

  console.log('Events:', result.items)

  if (result.hasMore) {
    const nextPage = await Sandbox.getEvents({
      sandboxID: 'iq721h44siv24wmyrh5oc',
      limit: 10,
      offset: 10,
    })

    console.log('Next page:', nextPage.items)
  }
  ```

  ```python Python icon="python" theme={null}
  from ppio_sandbox.code_interpreter import Sandbox

  result = Sandbox.get_events(
      sandbox_id="iq721h44siv24wmyrh5oc",
      events=["create", "pause", "resume", "connect", "timeout", "delete"],
      limit=10,
      offset=0,
  )

  print("Events:", result.items)

  if result.has_more:
      next_page = Sandbox.get_events(
          sandbox_id="iq721h44siv24wmyrh5oc",
          limit=10,
          offset=10,
      )

      print("Next page:", next_page.items)
  ```
</CodeGroup>

### 查询单个沙箱实例的事件

如果您已经创建了一个沙箱，可以直接通过该沙箱对象查询它的事件记录。

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={null}
  import { Sandbox } from 'ppio-sandbox/code-interpreter'

  const sandbox = await Sandbox.create()
  const result = await sandbox.getEvents({
    events: ['create', 'pause', 'resume', 'connect', 'timeout', 'delete'],
    limit: 10,
  })

  console.log(result.items)
  ```

  ```python Python icon="python" theme={null}
  from ppio_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create()
  result = sandbox.get_events(
      events=["create", "pause", "resume", "connect", "timeout", "delete"],
      limit=10,
  )

  print(result.items)
  ```
</CodeGroup>

## 筛选事件

使用查询参数缩小事件时间线范围。

| 参数           | 类型       | 是否必填 | 默认值 / 限制                  | 说明                                                                             |
| ------------ | -------- | ---- | ------------------------- | ------------------------------------------------------------------------------ |
| `startTime`  | `int64`  | 否    | 默认为 `endTime - 30 days`   | 查询开始时间，秒级 Unix 时间戳。查询范围包含该时间点。                                                 |
| `endTime`    | `int64`  | 否    | 默认为当前时间                   | 查询结束时间，秒级 Unix 时间戳。必须大于 `startTime`。                                           |
| `sandboxID`  | `string` | 否    | -                         | 按沙箱 ID 筛选。支持模糊匹配。                                                              |
| `templateID` | `string` | 否    | -                         | 按模板 ID 筛选。支持模糊匹配。                                                              |
| `events`     | `string` | 否    | 默认为关键事件集合                 | 逗号分隔的事件类型。当前关键事件集合包括 `create`、`pause`、`resume`、`connect`、`timeout` 和 `delete`。 |
| `state`      | `string` | 否    | -                         | 按事件状态筛选，例如 `success` 或失败状态。                                                    |
| `orderAsc`   | `bool`   | 否    | `false`                   | 是否按 `recordAt` 升序排序。默认按降序返回事件。                                                 |
| `offset`     | `int32`  | 否    | 默认 `0`，最小值 `0`            | 跳过的事件数量。                                                                       |
| `limit`      | `int32`  | 否    | 默认 `10`，最小值 `1`，最大值 `100` | 本次最多返回的事件数量。                                                                   |

<Note>
  时间字段使用秒级 Unix 时间戳，请勿传入毫秒级时间戳。

  单次查询最大时间范围为 60 天。如需查询更长时间线，请拆分为多个较小时间范围。
</Note>

## 分页

Events API 使用基于 `offset` 的分页方式。首次请求从 `offset: 0` 开始；如果 `hasMore` 为 `true`，下一页使用 `offset + limit` 继续请求。`limit` 最大值为 100。

## 响应字段

事件响应包含 `items` 数组和分页元数据。

| 字段        | 说明              |
| --------- | --------------- |
| `items`   | 符合查询条件的沙箱事件列表。  |
| `total`   | 分页前符合查询条件的事件总数。 |
| `hasMore` | 当前页之后是否还有更多事件。  |

`items` 中每个事件对象包含以下字段。

| 字段             | 说明                                                                |
| -------------- | ----------------------------------------------------------------- |
| `eventID`      | 唯一事件 ID。                                                          |
| `recordAt`     | 事件记录时间，秒级 Unix 时间戳。                                               |
| `templateID`   | 沙箱使用的模板 ID。                                                       |
| `templateName` | 沙箱使用的模板名称。                                                        |
| `sandboxID`    | 沙箱 ID。                                                            |
| `eventName`    | 事件类型，例如 `create`、`pause`、`resume`、`connect`、`timeout` 或 `delete`。 |
| `state`        | 事件状态。                                                             |
| `errorMsg`     | 事件失败或发生异常时的错误信息。无错误时通常为空。                                         |
| `statusCode`   | 与操作相关的 HTTP 状态码，如可用。                                              |

## 响应示例

```json theme={null}
{
  "items": [
    {
      "eventID": "evt_123",
      "recordAt": 1766650000,
      "templateID": "tmpl_abc",
      "templateName": "ubuntu-base",
      "sandboxID": "i3vrzzatkxojecvfuesnz",
      "eventName": "create",
      "state": "success",
      "errorMsg": "",
      "statusCode": 200
    }
  ],
  "total": 1,
  "hasMore": false
}
```