APIKeyInfo
API密钥简略信息
被如下接口引用：DescribeAPIKeyList。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| Name | String | 否 | API密钥名称 示例值：LocalDev |
| KeyId | String | 否 | API密钥ID 示例值：ark-3edcft6y |
| Status | String | 否 | 密钥状态。可以为API_KEY_STATUS_ACTIVE，或API_KEY_STATUS_INACTIVE 示例值：API_KEY_STATUS_ACTIVE |
| MaskedKey | String | 否 | 隐藏部分字符的API密钥，方便用户辨认 示例值：ark_g9****ztdA |
| CreatedAt | String | 否 | API密钥创建时间 示例值：2025-09-12T09:00:03.094Z |
CLSConfig
沙箱工具日志推送CLS相关配置
被如下接口引用：CreateSandboxTool, DescribeSandboxToolList。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| TopicId | String | 否 | 沙箱工具日志推送所使用的CLS日志主题ID 示例值：123e4567-e89b-12d3-a456-426614174000 |
CfsStorageSource
文件存储配置
被如下接口引用：CreateSandboxTool, DescribeSandboxToolList。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| FileSystemId | String | 否 | CFS资源ID 示例值：cfs-123456 |
| Path | String | 否 | CFS挂载路径 示例值：/ |
CosStorageSource
沙箱实例对象存储挂载配置
被如下接口引用：CreateSandboxTool, DescribeSandboxToolList。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| Endpoint | String | 否 | 对象存储访问域名 示例值：test-123456789.cos.ap-guangzhou.myqcloud.com |
| BucketName | String | 否 | 对象存储桶名称 示例值：test-123456789 |
| BucketPath | String | 否 | 对象存储桶路径，必须为以/起始的绝对路径 示例值：/ |
CustomConfiguration
沙箱自定义配置
被如下接口引用：CreateSandboxTool, StartSandboxInstance, UpdateSandboxTool。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| Image | String | 否 | 镜像地址 示例值：test.tencentcloudcr.com/example/nginx:latest |
| ImageRegistryType | String | 否 | 镜像仓库类型： 示例值：enterprise |
| Command | Array of String | 否 | 启动命令 示例值：["/bin/bash", "-c"] |
| Args | Array of String | 否 | 启动参数 示例值：["-h", "0.0.0.0", "-p", "8000"] |
| Env | Array of EnvVar | 否 | 环境变量 |
| Ports | Array of PortConfiguration | 否 | 端口配置 |
| Resources | ResourceConfiguration | 否 | 资源配置 |
| Probe | ProbeConfiguration | 否 | 探针配置 |
| DNSConfig | DNSConfig | 否 | 沙箱 DNS 配置 |
CustomConfigurationDetail
沙箱自定义配置详细信息
被如下接口引用：DescribeSandboxInstanceList, DescribeSandboxToolList, StartSandboxInstance。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| Image | String | 否 | 镜像地址 示例值：test.tencentcloudcr.com/example/nginx:latest |
| ImageRegistryType | String | 否 | 镜像仓库类型： 示例值：TCR |
| ImageDigest | String | 否 | 镜像 Digest 示例值：sha256:abc123def456... |
| Command | Array of String | 否 | 启动命令 示例值：["/bin/bash", "-c"] |
| Args | Array of String | 否 | 启动参数 示例值：["-h", "0.0.0.0", "-p", "8000"] |
| Env | Array of EnvVar | 否 | 环境变量 |
| Ports | Array of PortConfiguration | 否 | 端口配置 |
| Resources | ResourceConfiguration | 否 | 资源配置 |
| Probe | ProbeConfiguration | 否 | 探针配置 |
| DNSConfig | DNSConfig | 否 | 沙箱 DNS 配置 |
DNSConfig
沙箱自定义 dns 配置
被如下接口引用：CreateSandboxTool, DescribeSandboxInstanceList, DescribeSandboxToolList, StartSandboxInstance, UpdateSandboxTool。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| Servers | Array of String | 是 | DNS 服务器地址 参数格式：需要有效 IP 地址 默认值：10.0.0.1 示例值：["9.9.9.9"] |
| Searches | Array of String | 否 | 搜索域(对应 resolv.conf 的 search 指令) 示例值：["example.internal"] |
| Options | Array of String | 否 | 配置项(对应 resolv.conf 选项) 示例值：["ndots:5"] |
EnvVar
环境变量
被如下接口引用：CreateSandboxTool, DescribeSandboxInstanceList, DescribeSandboxToolList, StartSandboxInstance, UpdateSandboxTool。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| Name | String | 否 | 环境变量名 示例值：TEST_ENV |
| Value | String | 否 | 环境变量值 示例值：ABD |
Filter
过滤列表规则
被如下接口引用：DescribeSandboxInstanceList, DescribeSandboxToolList。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| Name | String | 否 | 属性名称, 若存在多个Filter时，Filter间的关系为逻辑与（AND）关系。 示例值：FILTER_KEY_NAME |
| Values | Array of String | 否 | 属性值, 若同一个Filter存在多个Values，同一Filter下Values间的关系为逻辑或（OR）关系。 示例值：["LocalDev"] |
HttpGetAction
HTTP GET 探测动作配置
被如下接口引用：CreateSandboxTool, StartSandboxInstance, UpdateSandboxTool。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| Path | String | 否 | 路径 示例值：/health |
| Port | Integer | 否 | 端口 示例值：8000 |
| Scheme | String | 否 | 协议 示例值：HTTP |
ImageStorageSource
镜像卷挂载源配置
被如下接口引用：CreateSandboxTool, DescribeSandboxToolList。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| Reference | String | 否 | 镜像地址 示例值：ccr.ccs.tencentyun.com/example/nginx:latest |
| ImageRegistryType | String | 否 | 镜像仓库类型：enterprise、personal。示例值：enterprise |
| SubPath | String | 否 | 镜像内部的路径 示例值：/mnt/sub |
| Digest | String | 否 | 镜像 Digest，请求时无需传入 示例值：sha256:abcdefg123... |
LogConfiguration
沙箱工具日志采集相关配置
被如下接口引用：CreateSandboxTool, DescribeSandboxToolList。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| CLSConfig | CLSConfig | 否 | 日志推送CLS的配置。 |
MetadataVar
metadata 项
被如下接口引用：DescribeSandboxInstanceList, StartSandboxInstance, UpdateSandboxInstance。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| Name | String | 否 | 沙箱元数据名 示例值：b |
| Value | String | 否 | 沙箱元数据值 示例值：b |
MountOption
沙箱实例存储挂载配置可选项，用于覆盖沙箱工具的存储配置的部分选项，并提供子路径挂载配置。
被如下接口引用：DescribeSandboxInstanceList, StartSandboxInstance。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| Name | String | 否 | 指定沙箱工具中的存储配置名称 示例值：Storage1 |
| MountPath | String | 否 | 沙箱实例本地挂载路径（可选），默认继承工具中的存储配置 示例值：/home/user |
| SubPath | String | 否 | 沙箱实例存储挂载子路径（可选） 示例值：workspace1 |
| ReadOnly | Boolean | 否 | 沙箱实例存储挂载读写权限（可选），默认继承工具存储配置 示例值：false |
NetworkConfiguration
沙箱网络配置
被如下接口引用：CreateSandboxTool, DescribeSandboxToolList, UpdateSandboxTool。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| NetworkMode | String | 是 | 网络模式（当前支持 PUBLIC, VPC, SANDBOX） 示例值：PUBLIC |
| VpcConfig | VPCConfig | 否 | VPC网络相关配置 |
PortConfiguration
端口配置
被如下接口引用：CreateSandboxTool, DescribeSandboxInstanceList, DescribeSandboxToolList, StartSandboxInstance, UpdateSandboxTool。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| Name | String | 否 | 端口名 示例值：http |
| Port | Integer | 否 | 端口 示例值：8000 |
| Protocol | String | 否 | 协议 示例值：TCP |
ProbeConfiguration
健康检查探针配置
被如下接口引用：CreateSandboxTool, DescribeSandboxInstanceList, DescribeSandboxToolList, StartSandboxInstance, UpdateSandboxTool。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| HttpGet | HttpGetAction | 否 | HTTP GET 探测配置 |
| ReadyTimeoutMs | Integer | 否 | 健康检查就绪超时 示例值：30000 |
| ProbeTimeoutMs | Integer | 否 | 健康检查单次探测超时 示例值：1000 |
| ProbePeriodMs | Integer | 否 | 健康检查间隔 示例值：1000 |
| SuccessThreshold | Integer | 否 | 健康检查成功阈值 示例值：1 |
| FailureThreshold | Integer | 否 | 健康检查失败阈值 示例值：3 |
ResourceConfiguration
资源配置
被如下接口引用：CreateSandboxTool, DescribeSandboxInstanceList, DescribeSandboxToolList, StartSandboxInstance, UpdateSandboxTool。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| CPU | String | 否 | cpu 资源量 示例值：500m |
| Memory | String | 否 | 内存资源量 示例值：1Gi |
SandboxInstance
沙箱实例结构体
被如下接口引用：DescribeSandboxInstanceList, StartSandboxInstance。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| InstanceId | String | 是 | 沙箱实例唯一标识符 示例值：48dd1132cfb96ccee5fd0aa58da2562d2fe3a929 |
| ToolId | String | 是 | 所属沙箱工具 ID 示例值：sdt-def456ghi789 |
| ToolName | String | 是 | 所属沙箱工具名称 示例值：code-interpreter-v1 |
| Status | String | 是 | 实例状态：STARTING（启动中）、RUNNING（运行中）、STOPPING（停止中）、STOPPED（已停止）、STOP_FAILED（停止失败）、FAILED（失败状态） 示例值：RUNNING |
| TimeoutSeconds | Integer | 否 | 超时时间（秒），null 表示无超时设置 示例值：600 |
| ExpiresAt | String | 否 | 过期时间（ISO 8601 格式），null 表示无过期时间 示例值：2024-01-01T10:30:00Z |
| StopReason | String | 否 | 停止原因：manual（手动）、timeout（超时）、error（错误）、system（系统），仅在状态为 STOPPED、STOP_FAILED 或 FAILED 时有值。当 provider 停止失败时，状态为 STOP_FAILED，原因为 error 示例值：timeout |
| CreateTime | String | 否 | 创建时间（ISO 8601 格式） 示例值：2024-01-01T10:00:00Z |
| UpdateTime | String | 否 | 更新时间（ISO 8601 格式） 示例值：2024-01-01T10:10:00Z |
| MountOptions | Array of MountOption | 否 | 存储挂载选项 |
| CustomConfiguration | CustomConfigurationDetail | 否 | 沙箱实例自定义配置 |
| NetworkMode | String | 否 | 网络模式 枚举值：
可以覆盖工具级别的网络配置。但如果一个工具本身就不支持 VPC 网络，那么即便在实例设置里选了 VPC 模式，也是无效的 示例值：VPC |
| Metadata | Array of MetadataVar | 否 | 沙箱实例元数据 |
SandboxTool
沙箱工具结构体
被如下接口引用：DescribeSandboxToolList。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| ToolId | String | 是 | 沙箱工具唯一标识符 示例值：sdt-ee4ywozw |
| ToolName | String | 否 | 沙箱工具名称，长度 1-50 字符，支持中英文、数字、下划线。同一 AppId 下沙箱工具名称必须唯一 示例值：browser-sandbox |
| ToolType | String | 否 | 沙箱工具类型，取值：browser（浏览器工具）、code-interpreter（代码解释器工具）、computer（计算机控制工具）、mobile（移动设备工具） 示例值：browser |
| Status | String | 否 | 沙箱工具状态，取值：CREATING（创建中）、ACTIVE（可用）、DELETING（删除中）、FAILED（失败） 示例值：ACTIVE |
| Description | String | 否 | 沙箱工具描述信息，最大长度 200 字符 示例值：浏览器沙箱环境 |
| DefaultTimeoutSeconds | Integer | 否 | 默认超时时间，支持格式：5m、300s、1h 等，不指定则使用系统默认值（5 分钟）。最大 24 小时 示例值：600 |
| NetworkConfiguration | NetworkConfiguration | 否 | 网络配置 |
| Tags | Array of Tag | 否 | 标签规格，包含资源标签绑定关系。用于为沙箱工具绑定标签，支持多种资源类型的标签绑定 |
| CreateTime | String | 否 | 沙箱工具创建时间，格式：ISO8601 示例值：2024-01-15T10:30:00Z |
| UpdateTime | String | 否 | 沙箱工具更新时间，格式：ISO8601 示例值：2024-01-15T10:30:00Z |
| RoleArn | String | 否 | 沙箱工具绑定角色ARN 示例值：qcs::cam::uin/100000001:roleName/test_role |
| StorageMounts | Array of StorageMount | 否 | 沙箱工具中实例存储挂载配置 |
| CustomConfiguration | CustomConfigurationDetail | 否 | 沙箱工具自定义配置 |
| LogConfiguration | LogConfiguration | 否 | 沙箱工具日志推送相关配置 |
| StatusReason | String | 否 | 用于说明沙箱工具处于该状态的原因 示例值：InternalError |
StorageMount
沙箱工具中实例存储挂载配置
被如下接口引用：CreateSandboxTool, DescribeSandboxToolList。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| Name | String | 否 | 存储挂载配置名称 示例值：Storage1 |
| StorageSource | StorageSource | 否 | 存储配置 |
| MountPath | String | 否 | 沙箱实例本地挂载路径 示例值：/home/user |
| ReadOnly | Boolean | 否 | 存储挂载读写权限配置，默认为false 示例值：false |
StorageSource
挂载存储配置
被如下接口引用：CreateSandboxTool, DescribeSandboxToolList。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| Cos | CosStorageSource | 否 | 对象存储桶配置 |
| Image | ImageStorageSource | 否 | 镜像卷配置 |
| Cfs | CfsStorageSource | 否 | 文件存储配置 |
Tag
标签
被如下接口引用：CreateSandboxTool, DescribeSandboxToolList, UpdateSandboxTool。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| Key | String | 否 | 标签键 示例值：business |
| Value | String | 否 | 标签值 示例值：biz1 |
VPCConfig
沙箱工具VPC相关配置
被如下接口引用：CreateSandboxTool, DescribeSandboxToolList, UpdateSandboxTool。
| 名称 | 类型 | 必选 | 描述 |
|---|---|---|---|
| SubnetIds | Array of String | 否 | VPC子网ID列表 示例值：["subnet-012abcde", "subnet-012edcba"] |
| SecurityGroupIds | Array of String | 否 | 安全组ID列表 示例值：["sg-abcde012", "sg-210edcba"] |
