# 元数据管理
<subtitle>为沙箱附加自定义键值对，便于关联会话、标记任务并按条件筛选。</subtitle>

元数据（metadata）是一组附加在沙箱上的自定义键值对。它不会改变沙箱运行行为，但可以帮助您在业务系统中识别、关联和筛选沙箱。

常见用途包括：

- **会话关联**：将沙箱与终端用户会话、对话或任务 ID 绑定。
- **用户关联**：记录业务侧的用户 ID、租户 ID 或项目 ID。
- **任务分类**：标注沙箱用途，例如 `data-analysis`、`code-agent`、`preview`。
- **批量管理**：配合 `Sandbox.list()` 查找某一批沙箱并执行清理、恢复或监控操作。

> 不建议在 metadata 中存放 API Key、访问令牌、密码等敏感信息。metadata 更适合保存用于检索和分类的业务标识。

## 创建沙箱时设置元数据

创建沙箱时，可以通过 `metadata` 参数传入自定义键值对。

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create(
    metadata={
        "user_id": "user_123",
        "session_id": "session_abc",
        "task_type": "data-analysis",
    },
)

print(sandbox.sandbox_id)
```

## 读取沙箱元数据

可以通过 `get_info()` 获取沙箱详情，并读取其中的 `metadata` 字段。

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create(
    metadata={
        "user_id": "user_123",
        "task_type": "data-analysis",
    },
)

info = sandbox.get_info()
print(info.metadata)

# 输出示例：
# {
#     "user_id": "user_123",
#     "task_type": "data-analysis",
# }
```

## 通过列表接口访问元数据

`Sandbox.list()` 返回的沙箱信息中也包含 metadata。您可以在业务逻辑中根据 metadata 做进一步处理。

```python
from ucloud_sandbox import Sandbox

paginator = Sandbox.list()
running_sandboxes = paginator.next_items()

for sbx in running_sandboxes:
    if sbx.metadata.get("task_type") == "data-analysis":
        print("Found analysis sandbox:", sbx.sandbox_id)
```

## 按元数据过滤沙箱

配合 `SandboxQuery`，可以直接按 metadata 查询符合条件的沙箱。更多列表查询方式请参考 [列表查询](/docs/agent-sandbox/sdk/sandbox/08-list.md)。

```python
from ucloud_sandbox import Sandbox, SandboxQuery

paginator = Sandbox.list(
    query=SandboxQuery(
        metadata={
            "user_id": "user_123",
            "task_type": "data-analysis",
        },
    ),
)

sandboxes = paginator.next_items()

for sbx in sandboxes:
    print(sbx.sandbox_id, sbx.metadata)
```

## 使用建议

- 使用稳定的 key 命名，例如 `user_id`、`session_id`、`task_type`。
- metadata 的值建议保持简短，便于索引和筛选。
- 如果需要按多个维度查找沙箱，创建时就把这些维度写入 metadata。
- 任务结束后仍应及时销毁不再需要的沙箱，metadata 只负责标记，不会自动管理生命周期。