Gemini Environments API

环境为安全运行代理代码、工具和服务提供隔离的执行上下文。

以 Markdown 格式查看 查看 OpenAPI 规范

CreateEnvironment

post https://generativelanguage.googleapis.com/v1beta/environments

创建环境。

请求正文

请求正文中包含结构如下的数据：

网络 EnvironmentNetworkEgressAllowlist 或枚举 (字符串)  （可选）

环境的网络配置。

沙盒的出站网络配置。接受包含“允许名单”数组的对象以限制流量，或接受字符串“disabled”以关闭所有网络访问权限。完全省略此字段可允许所有出站流量，且不注入任何标头。

可能的值

object

沙盒的出站网络配置。指定后，会限制沙盒可以访问的外部网域。完全省略此字段可允许所有出站流量，且不注入任何标头。

许可名单 数组 (AllowlistEntry)  （可选）

允许的出站网域的列表。仅允许向列出的网域发送请求。使用 [{'domain': '*'}] 可允许所有网域，同时仍可在特定网域上注入标头。

一条网域许可名单规则，可选择注入标头。

字段

网域 字符串  （选填）

允许向其发送出站请求的网域。支持通配符（例如“*.googleapis.com”）。使用“*”可允许所有网域。

transform 数组（对象）或对象  （可选）

要注入到与相应网域匹配的所有出站请求中的标头。接受单个字典或字典列表。出站代理会自动注入这些内容。

string

关闭所有网络。

可能的值

  • disabled

    关闭所有网络。

sources 数组 (Source)  （可选）

要装载到环境中的来源。

要装载到环境中的来源。

字段

content string  （选填）

如果 `type` 为 `INLINE`，则为内嵌内容。

编码 字符串  （选填）

内嵌内容的可选编码（例如 `base64`）。

source string  （选填）

环境的来源。 对于 Cloud Storage，这是 Cloud Storage 路径。 对于 GitHub，这是 GitHub 路径。

目标 字符串  （选填）

来源应在环境中显示的位置。

type enum (string)  (optional)

没有提供说明。

可能的值：

  • gcs

    Cloud Storage 存储桶。

  • inline

    内嵌内容。

  • repository

    通用代码库。来源网址中的协议前缀用于标识提供方（例如，github://、gcs://）。

响应

如果成功，响应正文将包含结构如下的数据：

创建时间 字符串  （可选）

仅限输出。环境的创建时间，采用 ISO 8601 格式 (YYYY-MM-DDThh:mm:ssZ)。

file_count string  （选填）

仅限输出。环境中的文件数量（仅限输出）。

id string  （选填）

必需。仅限输出。环境的 ID。

last_accessed string  （可选）

仅限输出。环境上次被访问的时间，采用 ISO 8601 格式 (YYYY-MM-DDThh:mm:ssZ)。

network EnvironmentNetworkEgressAllowlist 或枚举 (string)  （可选）

环境的网络配置。

沙盒的出站网络配置。接受包含“允许名单”数组的对象以限制流量，或接受字符串“disabled”以关闭所有网络访问权限。完全省略此字段可允许所有出站流量，且不注入任何标头。

可能的值

object

沙盒的出站网络配置。指定后，会限制沙盒可以访问的外部网域。完全省略此字段可允许所有出站流量，且不注入任何标头。

许可名单 数组 (AllowlistEntry)  （可选）

允许的出站网域的列表。仅允许向列出的网域发送请求。使用 [{'domain': '*'}] 可允许所有网域，同时仍可在特定网域上注入标头。

一条网域许可名单规则，可选择注入标头。

字段

网域 字符串  （选填）

允许向其发送出站请求的网域。支持通配符（例如“*.googleapis.com”）。使用“*”可允许所有网域。

transform 数组（对象）或对象  （可选）

要注入到与相应网域匹配的所有出站请求中的标头。接受单个字典或字典列表。出站代理会自动注入这些内容。

string

关闭所有网络。

可能的值

  • disabled

    关闭所有网络。

size_bytes string  （选填）

仅限输出。环境文件的总大小（以字节为单位，仅输出）。

sources 数组 (Source)  （可选）

要装载到环境中的来源。

要装载到环境中的来源。

字段

content string  （选填）

如果 `type` 为 `INLINE`，则为内嵌内容。

编码 字符串  （选填）

内嵌内容的可选编码（例如 `base64`）。

source string  （选填）

环境的来源。 对于 Cloud Storage，这是 Cloud Storage 路径。 对于 GitHub，这是 GitHub 路径。

目标 字符串  （选填）

来源应在环境中显示的位置。

type enum (string)  (optional)

没有提供说明。

可能的值：

  • gcs

    Cloud Storage 存储桶。

  • inline

    内嵌内容。

  • repository

    通用代码库。来源网址中的协议前缀用于标识提供方（例如，github://、gcs://）。

status enum (string)  （选填）

仅限输出。环境容器的状态。

可能的值：

  • active

    仅限输出。环境容器的状态。

  • expired

    仅限输出。环境容器的状态。

更新 字符串  （选填）

仅限输出。环境上次更新的时间，采用 ISO 8601 格式 (YYYY-MM-DDThh:mm:ssZ)。

创建环境

示例响应

{
  "created": "2026-08-19T00:00:00Z",
  "id": "env_abc123",
  "last_accessed": "2026-08-19T00:00:00Z",
  "sources": [
    {
      "type": "inline",
      "content": "print('Hello, World!')",
      "target": "main.py"
    }
  ],
  "status": "active",
  "updated": "2026-08-19T00:00:00Z"
}

ListEnvironments

get https://generativelanguage.googleapis.com/v1beta/environments

列出环境。

路径 / 查询参数

page_size integer  （可选）

可选。要返回的环境数量上限。\n 如果未指定，则默认为 50。最大值为 1000。

page_token string  （可选）

可选。分页令牌。

响应

如果成功，响应正文将包含结构如下的数据：

environments array (Environment)  （选填）

属于所提供项目的环境。

next_page_token string  （可选）

分页令牌。

列出环境

示例响应

{
  "environments": [
    {
      "created": "2026-08-19T00:00:00Z",
      "id": "env_abc123",
      "last_accessed": "2026-08-19T00:00:00Z",
      "status": "active",
      "updated": "2026-08-19T00:00:00Z"
    }
  ]
}

GetEnvironmentFiles

get https://generativelanguage.googleapis.com/v1beta/environments/{environment}/files/{path}

从环境的快照中检索文件元数据或目录内容。如需直接下载文件内容，请传递 ?alt=media 或使用 files.download 辅助函数。

路径 / 查询参数

page_size integer  （可选）

可选。每页返回的条目数上限（用于目录列表）。

page_token string  （可选）

可选。目录列表的分页令牌。

recursive 布尔值  （可选）

可选。如果为 true 且路径为目录，则以递归方式列出所有文件。

响应

如果成功，响应正文将包含结构如下的数据：

files array (EnvironmentFile)  （可选）

如果所请求的路径是目录，则此属性包含相应目录的内容。 如果所请求的路径是文件，则此属性包含一个条目，其中包含文件的元数据。 如果指定了 alt=media，则此属性为空（内容通过“blob”提供）。

环境中的文件或目录的元数据。

字段

创建时间 字符串  （可选）

仅限输出。相应文件/目录的创建时间。

mime_type string  （可选）

仅限输出。文件的 MIME 类型（例如“text/python”“image/png”）。 对于目录，此值为空。 NOLINT

modified string  （选填）

仅限输出。相应文件/目录的修改时间。

name string  （可选）

仅限输出。文件或目录的名称（例如“main.py”或“src”）。

路径 字符串  （选填）

仅限输出。环境中的完整相对路径（例如“workspace/src/main.py”）。

size_bytes string  （选填）

仅限输出。文件/目录的大小（以字节为单位）。 NOLINT

type enum (string)  (optional)

仅限输出。条目的类型。

可能的值：

  • file

    常规文件。

  • directory

    目录。

next_page_token string  （可选）

目录列表的分页令牌。 NOLINT

列出环境中的文件

示例响应

{
  "files": [
    {
      "name": "src",
      "type": "directory",
      "created": "2026-08-19T00:00:00Z",
      "modified": "2026-08-19T00:00:00Z",
      "path": "src"
    },
    {
      "name": "main.py",
      "type": "file",
      "created": "2026-08-19T00:00:00Z",
      "mime_type": "text/x-python",
      "modified": "2026-08-19T00:00:00Z",
      "path": "main.py",
      "size_bytes": "22"
    }
  ]
}

获取文件元数据

示例响应

{
  "files": [
    {
      "name": "main.py",
      "type": "file",
      "created": "2026-08-19T00:00:00Z",
      "mime_type": "text/x-python",
      "modified": "2026-08-19T00:00:00Z",
      "path": "main.py",
      "size_bytes": "22"
    }
  ]
}

下载文件内容

示例响应

{
  "files": [
    {
      "name": "main.py",
      "type": "file",
      "mime_type": "text/x-python",
      "path": "main.py",
      "size_bytes": "22"
    }
  ]
}

GetEnvironment

get https://generativelanguage.googleapis.com/v1beta/environments/{id}

获取环境。

响应

如果成功，响应正文将包含结构如下的数据：

创建时间 字符串  （可选）

仅限输出。环境的创建时间，采用 ISO 8601 格式 (YYYY-MM-DDThh:mm:ssZ)。

file_count string  （选填）

仅限输出。环境中的文件数量（仅限输出）。

id string  （选填）

必需。仅限输出。环境的 ID。

last_accessed string  （可选）

仅限输出。环境上次被访问的时间，采用 ISO 8601 格式 (YYYY-MM-DDThh:mm:ssZ)。

network EnvironmentNetworkEgressAllowlist 或枚举 (string)  （可选）

环境的网络配置。

沙盒的出站网络配置。接受包含“允许名单”数组的对象以限制流量，或接受字符串“disabled”以关闭所有网络访问权限。完全省略此字段可允许所有出站流量，且不注入任何标头。

可能的值

object

沙盒的出站网络配置。指定后，会限制沙盒可以访问的外部网域。完全省略此字段可允许所有出站流量，且不注入任何标头。

许可名单 数组 (AllowlistEntry)  （可选）

允许的出站网域的列表。仅允许向列出的网域发送请求。使用 [{'domain': '*'}] 可允许所有网域，同时仍可在特定网域上注入标头。

一条网域许可名单规则，可选择注入标头。

字段

网域 字符串  （选填）

允许向其发送出站请求的网域。支持通配符（例如“*.googleapis.com”）。使用“*”可允许所有网域。

transform 数组（对象）或对象  （可选）

要注入到与相应网域匹配的所有出站请求中的标头。接受单个字典或字典列表。出站代理会自动注入这些内容。

string

关闭所有网络。

可能的值

  • disabled

    关闭所有网络。

size_bytes string  （选填）

仅限输出。环境文件的总大小（以字节为单位，仅输出）。

sources 数组 (Source)  （可选）

要装载到环境中的来源。

要装载到环境中的来源。

字段

content string  （选填）

如果 `type` 为 `INLINE`，则为内嵌内容。

编码 字符串  （选填）

内嵌内容的可选编码（例如 `base64`）。

source string  （选填）

环境的来源。 对于 Cloud Storage，这是 Cloud Storage 路径。 对于 GitHub，这是 GitHub 路径。

目标 字符串  （选填）

来源应在环境中显示的位置。

type enum (string)  (optional)

没有提供说明。

可能的值：

  • gcs

    Cloud Storage 存储桶。

  • inline

    内嵌内容。

  • repository

    通用代码库。来源网址中的协议前缀用于标识提供方（例如，github://、gcs://）。

status enum (string)  （选填）

仅限输出。环境容器的状态。

可能的值：

  • active

    仅限输出。环境容器的状态。

  • expired

    仅限输出。环境容器的状态。

更新 字符串  （选填）

仅限输出。环境上次更新的时间，采用 ISO 8601 格式 (YYYY-MM-DDThh:mm:ssZ)。

获取环境

示例响应

{
  "created": "2026-08-19T00:00:00Z",
  "id": "env_abc123",
  "last_accessed": "2026-08-19T00:00:00Z",
  "sources": [
    {
      "type": "inline",
      "content": "print('Hello, World!')",
      "target": "main.py"
    }
  ],
  "status": "active",
  "updated": "2026-08-19T00:00:00Z"
}

DeleteEnvironment

delete https://generativelanguage.googleapis.com/v1beta/environments/{id}

删除环境。

响应

如果成功，则响应为空。

删除环境

资源

环境

代理的执行环境。

字段

创建时间 字符串  （可选）

仅限输出。环境的创建时间，采用 ISO 8601 格式 (YYYY-MM-DDThh:mm:ssZ)。

file_count string  （选填）

仅限输出。环境中的文件数量（仅限输出）。

id string  （选填）

必需。仅限输出。环境的 ID。

last_accessed string  （可选）

仅限输出。环境上次被访问的时间，采用 ISO 8601 格式 (YYYY-MM-DDThh:mm:ssZ)。

网络 EnvironmentNetworkEgressAllowlist 或枚举 (字符串)  （可选）

环境的网络配置。

沙盒的出站网络配置。接受包含“允许名单”数组的对象以限制流量，或接受字符串“disabled”以关闭所有网络访问权限。完全省略此字段可允许所有出站流量，且不注入任何标头。

可能的值

object

沙盒的出站网络配置。指定后，会限制沙盒可以访问的外部网域。完全省略此字段可允许所有出站流量，且不注入任何标头。

许可名单 数组 (AllowlistEntry)  （可选）

允许的出站网域的列表。仅允许向列出的网域发送请求。使用 [{'domain': '*'}] 可允许所有网域，同时仍可在特定网域上注入标头。

一条网域许可名单规则，可选择注入标头。

字段

网域 字符串  （选填）

允许向其发送出站请求的网域。支持通配符（例如“*.googleapis.com”）。使用“*”可允许所有网域。

transform 数组（对象）或对象  （可选）

要注入到与相应网域匹配的所有出站请求中的标头。接受单个字典或字典列表。出站代理会自动注入这些内容。

string

关闭所有网络。

可能的值

  • disabled

    关闭所有网络。

size_bytes string  （选填）

仅限输出。环境文件的总大小（以字节为单位，仅输出）。

sources 数组 (Source)  （可选）

要装载到环境中的来源。

要装载到环境中的来源。

字段

content string  （选填）

如果 `type` 为 `INLINE`，则为内嵌内容。

编码 字符串  （选填）

内嵌内容的可选编码（例如 `base64`）。

source string  （选填）

环境的来源。 对于 Cloud Storage，这是 Cloud Storage 路径。 对于 GitHub，这是 GitHub 路径。

目标 字符串  （选填）

来源应在环境中显示的位置。

type enum (string)  (optional)

没有提供说明。

可能的值：

  • gcs

    Cloud Storage 存储桶。

  • inline

    内嵌内容。

  • repository

    通用代码库。来源网址中的协议前缀用于标识提供方（例如，github://、gcs://）。

status enum (string)  （选填）

仅限输出。环境容器的状态。

可能的值：

  • active

    仅限输出。环境容器的状态。

  • expired

    仅限输出。环境容器的状态。

更新 字符串  （选填）

仅限输出。环境上次更新的时间，采用 ISO 8601 格式 (YYYY-MM-DDThh:mm:ssZ)。