# 列出沙箱
<subtitle>使用 `Sandbox.list()` 列出沙箱，并按状态或元数据筛选。</subtitle>

您可以使用 `Sandbox.list()` 方法列出沙箱。

> 获取到正在运行或已暂停的沙箱信息后，可以使用 `Sandbox.connect()` 重新连接。更多说明请参考 [手动连接沙箱](/docs/agent-sandbox/sdk/sandbox/09-connect-to-running-sandbox.md)。

## 列出沙箱

`Sandbox.list()` 方法支持分页。更多分页技巧请参考 [高级分页](#高级分页)。

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create(
    metadata={
        "name": "My Sandbox",
    },
)

paginator = Sandbox.list()

# 获取第一页沙箱，包含运行中和已暂停的沙箱
first_page = paginator.next_items()

running_sandbox = first_page[0]

print("Running sandbox metadata:", running_sandbox.metadata)
print("Running sandbox id:", running_sandbox.sandbox_id)
print("Running sandbox started at:", running_sandbox.started_at)
print("Running sandbox template id:", running_sandbox.template_id)

# 获取下一页沙箱
next_page = paginator.next_items()
```

上面的代码会输出类似内容：

```text
Running sandbox metadata: {'name': 'My Sandbox'}
Running sandbox id: ixjj3iankaishgcge4jwn-b0b684e9
Running sandbox started at: 2024-10-15 21:13:07.311861+00:00
Running sandbox template id: 3e4rngfa34txe0gxc1zf
```

## 筛选沙箱

可以按沙箱当前状态筛选。`state` 参数可以包含 `running`、`paused`，也可以同时包含两者。

```python
from ucloud_sandbox import Sandbox, SandboxQuery, SandboxState

# 创建一个沙箱
sandbox = Sandbox.create()

# 列出运行中或已暂停的沙箱
paginator = Sandbox.list(
    query=SandboxQuery(
        state=[SandboxState.RUNNING, SandboxState.PAUSED],
    ),
)

# 获取第一页沙箱，包含运行中和已暂停的沙箱
sandboxes = paginator.next_items()
```

也可以按创建沙箱时指定的 metadata 键值对筛选。

```python
from ucloud_sandbox import Sandbox, SandboxQuery

# 创建带 metadata 的沙箱
sandbox = Sandbox.create(
    metadata={
        "env": "dev",
        "app": "my-app",
        "user_id": "123",
    },
)

# 列出 user_id 为 123 且 env 为 dev 的沙箱
paginator = Sandbox.list(
    query=SandboxQuery(
        metadata={
            "user_id": "123",
            "env": "dev",
        },
    ),
)

# 获取第一页沙箱，包含运行中和已暂停的沙箱
sandboxes = paginator.next_items()
```

指定多个 metadata 键值对时，只会返回全部匹配的沙箱。更多 metadata 说明请参考 [元数据管理](/docs/agent-sandbox/sdk/sandbox/metadata.md)。

## 高级分页

如果需要更细粒度的分页控制，可以设置每页数量 `limit`，并指定偏移参数 `next_token` 作为分页起点。默认和最大单页数量为 **100**。

```python
from ucloud_sandbox import Sandbox

paginator = Sandbox.list(
    limit=100,
    next_token="<base64-encoded-token>",
)

# 是否还有下一页
paginator.has_next

# 下一页 token
paginator.next_token

# 获取下一页
paginator.next_items()
```

您也可以通过循环检查 `has_next`，不断获取下一页，直到没有更多分页。

```python
from ucloud_sandbox import Sandbox

paginator = Sandbox.list()

# 遍历所有分页
sandboxes = []
while paginator.has_next:
    items = paginator.next_items()
    sandboxes.extend(items)
```