概述

使用 Sandbox.list() 方法可以列出和查询所有正在运行或已暂停的沙箱实例。该方法返回一个分页器对象,支持过滤、分页等高级查询功能。

基本用法

列出所有沙箱并获取第一页结果。

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  const paginator = await Sandbox.list()
  const items = await paginator.nextItems()

  console.log(`Found ${items.length} sandboxes`)
  items.forEach(sandbox => {
    console.log('Sandbox ID:', sandbox.sandboxId)
    console.log('Template ID:', sandbox.templateId)
    console.log('State:', sandbox.state)
    console.log('Started at:', sandbox.startedAt)
    console.log('Metadata:', sandbox.metadata)
  })
}

main()

查询参数

按状态过滤

使用 query.state 参数过滤特定状态的沙箱。

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  // List only running sandboxes
  const paginator = await Sandbox.list({
    query: { state: ['running'] }
  })
  const items = await paginator.nextItems()

  console.log(`${items.length} running sandboxes`)
}

main()

按元数据过滤

使用 query.metadata 参数根据自定义元数据筛选沙箱。

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  // Filter by single metadata field
  const paginator = await Sandbox.list({
    query: { metadata: { userId: '123' } }
  })
  const items = await paginator.nextItems()

  console.log(`Found ${items.length} sandboxes for user 123`)
}

main()

多条件过滤

指定多个元数据字段时,必须全部匹配(AND 逻辑)。

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  // Multiple metadata filters (AND logic)
  const paginator = await Sandbox.list({
    query: {
      metadata: {
        userId: '123',
        env: 'dev'
      }
    }
  })
  const items = await paginator.nextItems()
}

main()

分页处理

检查是否有更多页

使用 hasNext/has_next 属性检查是否还有更多数据。

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  const paginator = await Sandbox.list()
  const firstPage = await paginator.nextItems()

  console.log(`First page: ${firstPage.length} items`)

  if (paginator.hasNext) {
    const secondPage = await paginator.nextItems()
    console.log(`Second page: ${secondPage.length} items`)
  }
}

main()

遍历所有页

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  const paginator = await Sandbox.list()
  const allSandboxes: any[] = []

  do {
    const items = await paginator.nextItems()
    allSandboxes.push(...items)
  } while (paginator.hasNext)

  console.log(`Total: ${allSandboxes.length} sandboxes`)
}

main()

自定义页大小

使用 limit 参数设置每页返回的最大项数(默认和最大值为 100)。

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  const paginator = await Sandbox.list({ limit: 50 })
  const items = await paginator.nextItems()

  console.log(`Fetched ${items.length} items (max 50)`)
}

main()

使用分页令牌

使用 nextToken/next_token 继续上一次的查询。

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  const paginator = await Sandbox.list({ limit: 10 })
  const firstPage = await paginator.nextItems()
  const token = paginator.nextToken

  console.log('Next token:', token)

  // Use token to get next page
  if (token) {
    const nextPaginator = await Sandbox.list({
      limit: 10,
      nextToken: token
    })
    const secondPage = await nextPaginator.nextItems()
  }
}

main()

SDK 版本差异

本文档基于 v2.x+ 版本。