# 自定义元数据
<subtitle>为文件附加自定义键值对元数据，并在读取时获取。</subtitle>

您可以在将文件写入沙箱时使用 `metadata` 选项附加自定义键值对元数据。元数据会与文件一起持久化，并由 `files.get_info()`、`files.list()` 和 `files.rename()` 返回。

## 前置条件

自定义文件元数据需要使用 envd 版本 `v0.6.2` 或更高版本的模板。如果您使用的是在 envd `v0.6.2` 之前创建的自定义模板，需要重新构建它。

您可以使用 `ucloud-sandbox-cli template list` 命令检查模板的 envd 版本。

## 写入带有元数据的文件

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create()

info = sandbox.files.write("report.txt", "hello", metadata={"author": "alice", "purpose": "demo"})
print(info.metadata)  # {"author": "alice", "purpose": "demo"}
```

## 写入多个带有元数据的文件

写入多个文件时，相同的元数据会应用到上传中的每个文件。

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create()

sandbox.files.write_files(
    [
        { "path": "a.txt", "data": "A" },
        { "path": "b.txt", "data": "B" },
    ],
    metadata={"source": "import"},
)
```

## 读取元数据

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create()

sandbox.files.write("report.txt", "hello", metadata={"author": "alice"})

info = sandbox.files.get_info("report.txt")
print(info.metadata)  # {"author": "alice"}
```

## 限制

- 元数据键和值必须是可打印的 US-ASCII 字符。
- 键会被沙箱转换为小写，因此读取时的大小写可能与写入时不同。
- 覆盖文件会替换其元数据——不会保留之前写入的元数据。
- 元数据存储为沙箱内文件的 `user.e2b.*` 扩展属性，因此您也可以在沙箱内使用标准工具（如 `getfattr` 和 `setfattr`）读取或设置它。