> ## 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.

# 元数据

> 了解 PPIO Agent 沙箱元数据的归档使用方式，查阅该版本标记与管理沙箱信息的方法，为维护既有资源组织方式提供参考。

沙箱**元数据**为附加在沙箱实例上的任意键值对信息。

适用于以下场景：

* 将沙箱与用户会话关联。
* 为沙箱存储自定义用户数据，如 API 密钥。
* 将沙箱与用户 ID 关联并稍后需要重新 [连进沙箱](/docs/sandbox/archive/sandbox-connect)。

当您在创建沙箱时指定了元数据，可以通过如下方法列出正在运行的沙箱列表，并访问其元数据信息。

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

// 创建沙箱并指定元数据。
const sandbox = await Sandbox.create({
  metadata: {
    userId: '123',
  },
})

// 列出正在运行的沙箱并访问元数据。
const runningSandboxesPaginator = await Sandbox.list({
  query: {
    state: ["running"],
  },
})

const runningSandboxes = await runningSandboxesPaginator.nextItems()

console.log("runningSandboxes[0].metadata: ", runningSandboxes[0].metadata)

// 输出示例：
// { userId: '123' }

await sandbox.kill()
```

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

# 创建沙箱并指定元数据。
sandbox = Sandbox.create(
  metadata={
    'user_id': '123',
  },
)

# 列出正在运行的沙箱并访问元数据。
running_sandboxes_paginator = Sandbox.list(
  query=SandboxQuery(
    state=[SandboxState.RUNNING],
  ),
)
running_sandboxes = running_sandboxes_paginator.next_items()

print(running_sandboxes[0].metadata)

# 输出示例：
# { userId: '123' }

sandbox.kill()
```

## 按元数据过滤沙箱列表

您也可以基于元数据里的键值对来过滤沙箱列表，详情参考 [获取沙箱列表](/docs/sandbox/archive/sandbox-list#根据元数据过滤沙箱)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.