查询沙箱实例详情。

请求说明

请求方式：POST

请求地址：http://open.volcengineapi.com/?Action=DescribeSandbox&Version=2024-06-06

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

请求参数

参数	类型	是否必选	示例值	描述
Action	String	是	DescribeSandbox	接口名称。当前 API 的名称为 DescribeSandbox。
Version	String	是	2024-06-06	接口版本。当前 API 的版本为 2024-06-06。
SandboxId	String	是	vefaas-e8m6xarn-p2zamuv2fr-*****	通过沙箱实例 ID 或名称筛选沙箱实例。在沙箱应用页面的沙箱实例页签下获取沙箱实例 ID 或名称。登录沙箱应用的方法参见沙箱应用。说明同时指定多个查询条件时，优先匹配沙箱实例 ID 或名称来返回单个实例，或者返回实例不存在。
FunctionId	String	是	e8m6****	通过沙箱应用的 ID 筛选沙箱实例。在沙箱应用页面获取沙箱应用 ID。登录沙箱应用的方法参见沙箱应用。

请求示例

返回参数

参数	类型	示例值	描述
Id	String	vefaas-fnhyb3lm-ku58oo12ls-****	沙箱实例 ID 或名称。
FunctionId	String	fnhy****	沙箱实例所在沙箱应用的 ID。
Metadata	JSON Map	{"app":"test"}	沙箱实例标签（Label）元信息，用于标记、筛选实例。格式为<"key":"value">。
CreatedAt	String	2025-04-25 11:11:29.376 +0000 UTC	沙箱实例的创建时间。
ExpireAt	String	2025-04-25 11:31:29.376 +0000 UTC	沙箱实例的过期时间。
Status	String	Ready	沙箱实例的状态。取值： Starting：开始启动。 Ready：启动完成。 Paused：已暂停。 Failed：启动失败。 Terminating：终止中。
RevisionNumber	Integer	1	沙箱实例版本的编号。
AvailabilityZone	String	cn-beijing-b	沙箱实例所在可用区 ID。
InstanceType	String	elastic	沙箱实例类型。取值： elastic：弹性实例。 frozen：冻结实例。 activated：激活实例。 reserved：预留实例。
ErrorCode	String	function_health_check_failed	沙箱实例启动失败的错误码。取值： internal_load_request_error：系统内部错误。 function_initialize_failed：业务进程初始化错误。 function_health_check_failed：健康检查错误。 route_terminating：路由删除中。正常启动沙箱实例时，该字段为空。
ErrorMessage	String	function_health_check_failed	沙箱实例启动失败的报错信息。正常启动沙箱实例时，该字段为空。
Pending	Boolean	true	沙箱实例是否处于 Pending 等待调度状态，当 Status 尚未更新时，通过该字段判断是否在排队中。取值： true：处于等待调度状态。 false：默认值，不处于等待调度状态。
RequestTimeout	Integer	30	请求超时时间，单位为秒，取值范围为 1~900 的正整数，默认值为 30。
MaxConcurrency	Integer	100	单个沙箱实例最大并发。
MemoryMB	Integer	1024	沙箱实例内存的规格，单位为 MiB。
CpuMilli	Integer	500	沙箱实例 CPU 的规格，单位为 milli cpu。
ImageInfo	Object of InstanceImageInfo	-	沙箱实例镜像信息，包括镜像地址、启动命令、监听端口。
Envs	Array of EnvVar	-	沙箱实例环境变量信息。
InstanceTosMountConfig	Object of InstanceTosMountConfig	-	沙箱实例级别对象存储（TOS）存储挂载配置。
MetadataList	Array of SandboxMetadata	[{"MetaKey":"app","MetaValue":"test"}]	沙箱实例的元数据列表，每个元数据项由键值对组成，用于标记和筛选实例。
SessionId	String	sess-12345****	沙箱实例的会话 ID。
InstanceNasMountConfig	Object of InstanceNasMountConfig	1234567890ab****	沙箱实例级别文件存储（NAS）存储挂载配置。
AssignStatus	String	ready	Sandbox 分配状态（仅针对于开启了 Sandbox 池化能力场景）
PausedAt	String	2025-04-25 11:31:29.376 +0000 UTC	沙箱实例被执行暂停操作的时间，仅当沙箱实例状态（Status）处于已暂停（Paused）时返回该字段。
EBSVolumes	Array of EBSVolume	-	沙箱实例已挂载的 EBS 云盘配置列表，包含云盘 ID、容器内挂载路径、读写权限等相关配置信息。
RoleChainTrn	Array of String	["trn:iam::123456**:role/ChainRole1","trn:iam::098765**:role/ChainRole2"]	实例级别的角色链式授权 TRN 列表，用于配置跨账号场景下访问 TOS 存储的链式授权规则。
RoleTrn	String	trn:iam::210040****:role/VeFaaSDefaultRole	实例级别的角色 TRN 标识，用于配置本账号场景下访问 TOS 存储的授权规则。
AutoPauseConfig	Object of AutoPauseConfig	-	沙箱实例的到期自动暂停配置。
AutoSnapshotConfig	Object of AutoSnapshotConfig	-	沙箱实例的自动定时快照配置。
InstanceEfsMountConfig	Object of EfsMountConfig	-	沙箱实例级别弹性文件存储（EFS）的挂载配置，用于指定实例关联的 EFS 挂载点相关规则。
NetworkRules	Object of NetworkRules	-	沙箱实例的网络访问规则配置，用于控制实例的入站、出站网络访问权限与策略。
ImageVolumes	Array of ImageVolume	-	沙箱实例关联的镜像卷配置列表，用于描述实例挂载的额外镜像存储卷信息。
PausedSnapshot	Object of PausedSnapshotInfo	-	沙箱实例暂停时关联的快照信息，用于实例暂停后可基于该快照快速恢复运行状态。
AccessKey	String	ak-****	沙箱实例的访问密钥，用于身份校验以获取沙箱实例的访问权限。

InstanceImageInfo

参数	类型	示例值	描述
Id	String	xGWv9i****	已预热的镜像 ID。可通过 ListSandboxImages 接口查询当前已预热镜像列表。
Port	Integer	8080	实例镜像端口。
Image	String	cr-vefaas-**.cr.volces.com/vefaas-**/official-nodejs:v1.0.0	沙箱实例所使用的已预热镜像的地址，支持通过该地址或已预热镜像 ID 创建实例。
Command	String	bash /root/sandbox/scripts/run.sh	实例的自定义启动命令。
SourceImageUrl	String	cr-vefaas-**.cr.volces.com/vefaas-**/nodejs-sandbox:v1.2.0	沙箱实例所使用的容器镜像的源地址，为镜像仓库中对应镜像的完整可访问路径，用于标识镜像的来源位置。

EnvVar

参数	类型	示例值	描述
Key	String	business_type	沙箱实例环境变量的键。
Value	String	free	沙箱实例环境变量的值。

InstanceTosMountConfig

参数	类型	示例值	描述
Mode	String	override	TOS 挂载配置的继承策略，决定实例配置如何与函数配置合并。 inherit：默认值，完全沿用函数上配置的 TOS 挂载，实例不单独设置。 merge：将函数的 TOS 挂载配置与实例的 TOS 挂载配置合并生效。 override：完全使用实例的 TOS 挂载配置，忽略函数上的配置。
Enable	Boolean	true	沙箱实例是否启用实例级别的对象存储（TOS）挂载，取值： true：已开启。 false：默认值，未开启。
AuthMode	String	AKSK	实例级别全局 TOS 认证模式，适用于未单独配置认证的挂载点（TosMountPoints）。取值： IAM_ROLE：使用函数绑定的 IAM 角色（Role）进行认证。使用前需确保函数已配置 Role 角色，IAM 角色的配置方法参见 IAM 授权最佳实践。 AKSK：使用 AK/SK 认证。
Credentials	Object of Credentials	-	实例级别全局 AK/SK 凭证，用于沙箱实例的 TOS 访问认证。当 AuthMode 为 AKSK 时需要配置。
TosMountPoints	Array of TosMountPoint	-	实例的 TOS 挂载点列表。注意携带 SnapshotId 从快照创建实例时，指定此字段为覆盖语义，将完整替换快照中的 TOS 挂载点配置。

SandboxMetadata

参数	类型	示例值	描述
MetaKey	String	business_line	沙箱实例元数据项的键，用于标识元数据的分类维度，配合对应的值实现实例的标记与筛选。
MetaValue	String	payment_service	沙箱实例元数据项对应的值，与元数据键配合组成键值对，用于标记实例的业务属性、归属分类等信息，支持基于该值对实例进行筛选与分组。

InstanceNasMountConfig

参数	类型	示例值	描述
Enable	Boolean	true	沙箱实例是否启用了实例级别的 NAS 挂载，取值： true：已开启。 false：默认值，未开启。
NasMountPoints	Array of NasMountPoint	-	当沙箱实例启用实例级别的文件存储（NAS）挂载时，该字段指定实例挂载的 NAS 远端目录及对应的本地目录的列表。

EBSVolume

参数	类型	示例值	描述
ReadOnly	Boolean	true	标识对应 EBS 云盘是否为只读模式，取值如下： true：云盘为只读状态，沙箱实例仅可读取云盘内数据，无法执行写入、修改、删除操作。 false：默认值，云盘为可读写状态，沙箱实例可正常对云盘内数据执行各类操作。
VolumeID	String	vol-2d53x7kf9abc1****	对应挂载至沙箱实例的弹性块存储（EBS）卷的 ID，用于定位和关联指定的 EBS 存储资源。
MountPath	String	/mnt/ebs/****	弹性块存储卷在沙箱实例内的本地挂载目录，实例进程可通过该路径访问对应存储卷的文件系统。

AutoPauseConfig

参数	类型	示例值	描述
Enable	Boolean	true	沙箱实例是否启用自动暂停配置，取值如下： true：已开启自动暂停功能，沙箱实例在无请求的空闲状态下将自动进入暂停状态以节省资源。 false：默认值，未开启自动暂停功能。
SnapshotType	String	disk	沙箱实例自动暂停时生成的快照类型。取值如下： disk：磁盘快照，仅保存实例的磁盘状态。 full：包含内存信息的不停机快照，同时保存实例的磁盘与运行时内存状态。

AutoSnapshotConfig

参数	类型	示例值	描述
Enable	Boolean	true	沙箱实例是否启用实例级别的自动快照配置，取值如下： true：已开启自动快照功能，系统将按照配置规则自动对实例数据进行快照备份； false：默认值，未开启自动快照功能，不会自动执行快照备份操作。
Metadata	JSON Map	{"app":"test"}	沙箱实例快照元信息，格式为<"key":"value">。
TimeZone	String	Asia/Shanghai	自动快照 Cron 表达式（CronExpression）所使用的时区，默认值：Asia/Shanghai。
MaxRetained	Integer	3	同一沙箱实例下允许保留的自动快照最大数量。当快照数量超出该阈值时，系统会自动清理最早的历史快照。取值为 0时，通过快照保留天数（RetentionDays）控制快照生命周期。
SnapshotType	String	disk	自动快照类型。取值如下： disk：磁盘快照，仅保存实例的磁盘状态。 full：包含内存信息的不停机快照，同时保存实例的磁盘与运行时内存状态。
RetentionDays	Integer	7	自动快照配置中指定的快照保留时长，单位为天，超过该时长的历史快照将被自动清理释放存储空间。
CronExpression	String	@every 24h	配置沙箱实例自动快照的定时触发规则，支持两种形式：标准 5 位 Cron 表达式，格式为 minute hour day-of-month month day-of-week，基于指定时区按固定时间点触发； @every 相对间隔形式，格式为 @every <时长>，以实例创建、恢复或上次快照执行完成的时间为基准点按固定间隔触发，不受时区影响。相邻两次自动快照的执行间隔不得小于 12 小时。

EfsMountConfig

参数	类型	示例值	描述
MountPoints	Array of EfsMountPoint	-	当沙箱实例启用弹性文件存储（EFS）挂载时的配置信息。

NetworkRules

参数	类型	示例值	描述
HttpProxy	Object of HttpProxy	-	沙箱实例网络规则中的 HTTP 代理配置。
MaxEgressCps	Long	100	所有出向流量每秒允许新建的最大连接数。0 表示不限速，合法范围为 [0, 4294967295]。
EgressIPRules	Object of IPRules	-	IPv4 CIDR、IP 和端口访问规则。
AllowEgressAccess	Boolean	false	当出站网络访问请求未命中任何已配置的允许/拒绝规则时，系统执行的默认处理动作，取值如下： true：默认值，允许该出站访问请求。 false：拒绝该出站访问请求。
EgressDomainRules	Object of DomainRules	-	HTTP/HTTPS 域名访问规则。

ImageVolume

参数	类型	示例值	描述
ReadOnly	Boolean	true	挂载模式，默认只读。
ImageName	String	cr-vefaas-****.cr.volces.com/vefaas-test/extra-volume-image:v2.1.0	用户提供的容器镜像地址，系统会自动将其解析为 FaaS 侧对应的 Nydus 镜像，作为沙箱实例挂载的额外镜像存储卷的来源。
MountPath	String		容器内挂载路径。

PausedSnapshotInfo

参数	类型	示例值	描述
SnapshotId	String	snap-20250425-ku58oo12ls-789ab****	沙箱实例暂停时生成的快照 ID，可用于后续基于该快照恢复对应的沙箱实例状态。
SnapshotType	String	full	快照类型。取值如下： disk：磁盘快照，仅保存实例的磁盘状态。 full：包含内存信息的不停机快照，同时保存实例的磁盘与运行时内存状态。
FullSnapshotExpiresAt	String	2025-04-26 11:11:29.376 +0000 UTC	沙箱实例暂停时生成的全量快照的过期时间。

Credentials

参数	类型	示例值	描述
AccessKeyId	String	AKLTM3V4Y2RZM2RBMDBMMjVj****	用于验证沙箱实例访问对象存储（TOS）身份的密钥 ID，是访问 TOS 资源的身份凭证组成部分。
SecretAccessKey	String	FweiffJEFJEWFJWERYTKRVFJlewjfwelFslfjsdfl****	用于访问 TOS 存储桶的密钥凭证中的秘密访问密钥。
SessionToken	String	STS-20250425111129-ku58oo12ls-****	沙箱实例挂载 TOS 存储时使用的临时会话令牌。

TosMountPoint

参数	类型	示例值	描述
AuthMode	String	AKSK	实例级别全局 TOS 认证模式，适用于未单独配置认证的挂载点（TosMountPoints）。取值： IAM_ROLE：使用函数绑定的 IAM 角色（Role）进行认证。使用前需确保函数已配置 Role 角色，IAM 角色的配置方法参见 IAM 授权最佳实践。 AKSK：使用 AK/SK 认证。
Endpoint	String	http://tos-****.ivolces.com	指定沙箱实例挂载的 TOS 存储桶对应的访问域名，关联对应地域的 TOS 服务节点，用于建立与目标 TOS 存储桶的网络访问链路。
ReadOnly	Boolean	false	指定 TOS 挂载点在沙箱实例本地目录的访问权限，取值如下： true：本地目录为只读权限，实例仅可读取对应 TOS 存储桶内的文件数据，无法执行写入、修改、删除操作。 false：本地目录为读写权限，实例可正常对对应 TOS 存储桶内的文件执行各类操作。
BucketName	String	vefaas-business-storage-****	指定沙箱实例挂载的对象存储（TOS）存储桶的名称，用于关联待挂载的目标 TOS 存储资源。
BucketPath	String	/business-****/upload	指定沙箱实例挂载的目标 TOS 存储桶内的远端目录路径，实例将该路径下的存储桶内容映射至本地挂载目录中进行访问。
Credentials	Object of Credentials	-	实例级别全局 AK/SK 凭证，用于沙箱实例的 TOS 访问认证。当 AuthMode 为 AKSK 时需要配置。
LocalMountPath	String	/mnt/tos/business_****	沙箱实例内的本地目录路径，系统会将指定的 TOS 存储桶远端目录映射至该路径，实例进程可通过该路径访问对应 TOS 存储资源的内容。
EncryptionConfig	Object of BucketEncryptionConfig	-	TOS 挂载点的服务端加密配置。

NasMountPoint

参数	类型	示例值	描述
RemotePath	String	/business/up****	沙箱实例挂载的文件存储（NAS）服务端的远端目录路径，系统会将该路径下的 NAS 存储内容映射至实例本地挂载目录，供实例进程访问。
LocalMountPath	String	/mnt/nas/business_up****	沙箱实例内的本地目录路径，系统会将指定的文件存储（NAS）服务端远端目录映射至该路径，实例进程可通过该路径访问对应 NAS 存储资源的内容。

EfsMountPoint

参数	类型	示例值	描述
Backend	Object of EfsBackendConfig	-	弹性文件存储（EFS）挂载的后端配置，包含目标挂载目标与所属可用区信息。
ReadOnly	Boolean	true	指定弹性文件存储（EFS）挂载点在沙箱实例本地目录的访问权限，取值如下： true：本地目录为只读权限，实例仅可读取对应 EFS 存储内的文件数据，无法执行写入、修改、删除操作。 false：本地目录为读写权限，实例可正常对对应 EFS 存储内的文件执行各类操作。
LocalMountPath	String	/mnt/efs/business_****	沙箱实例内的本地目录路径，系统会将指定的弹性文件存储（EFS）服务端远端目录映射至该路径，实例进程可通过该路径访问对应 EFS 存储资源的内容。
EncryptionConfig	Object of EfsEncryptionConfig	-	弹性文件存储（EFS）挂载点的服务端加密配置，用于指定挂载 EFS 存储时的加密相关参数，保障存储数据的安全性。

HttpProxy

参数	类型	示例值	描述
Mode	String	TCP-80-443	HTTP CONNECT 代理的转发模式，取值如下： TCP-80-443：默认值，仅将 80、443 端口的 TCP 请求转发至代理。 TCP：将所有 TCP 请求转发至代理。
Address	String	http://proxy.service.internal:****	沙箱实例 HTTP CONNECT 代理的访问地址，必须使用 http:// 或 https://协议格式的 URL 进行配置，用于指定实例出站请求转发的目标代理服务地址。
Headers	JSON Map	{"Proxy-Authorization":"Bearer"}	沙箱实例向 HTTP CONNECT 代理发送出站请求时，附加携带的自定义请求头，通常可用于传递代理服务所需的认证凭证等敏感信息。

IPRules

参数	类型	示例值	描述
Deny	Array of IPRule	[{"Cidrs":["10.10.0.0/16"],"Ports":[]}]	沙箱实例出站网络访问中，针对 IPv4 地址段、IP 及端口的拒绝（Deny）规则列表，与允许（Allow）规则合计最多 16 条。
Allow	Array of IPRule	[{"Cidrs":["10.0.0.0/8","192.0.2.10"],"Ports":[{"Protocol":"TCP","Port":443,"EndPort":443}]}]	沙箱实例出站网络访问中，针对 IPv4 地址段、IP 及端口的允许（Allow）访问规则列表，与拒绝（Deny）规则合计最多 16 条。
Policy	String	AllowOverrides	当出站 IP 访问的允许（Allow）规则与拒绝（Deny）规则同时命中时，系统执行的优先级判定策略，取值如下： AllowOverrides：默认值，优先匹配允许规则。 DenyOverrides：优先匹配拒绝规则。

DomainRules

参数	类型	示例值	描述
Deny	Array of String	["blocked.example.com","*.malicious.example.org"]	沙箱实例出站网络访问中，被拒绝的 HTTP/HTTPS 域名规则列表，支持精确域名与 *.example.com通配符格式，与允许（Allow）规则合计最多 16 条。
Allow	Array of String	["api.example.com","*.service.example.com"]	沙箱实例出站网络访问中，被允许的 HTTP/HTTPS 域名规则列表，与拒绝（Deny）规则合计最多 16 条。
Policy	String	AllowOverrides	当出站域名访问的允许（Allow）规则与拒绝（Deny）规则同时命中时，系统执行的优先级判定策略，取值如下： AllowOverrides：默认值，优先匹配允许规则。 DenyOverrides：优先匹配拒绝规则。

BucketEncryptionConfig

参数	类型	示例值	描述
SSECKey	String	aGVsbG****	SSE-C 加密方式使用的加密密钥，为 256 位、经 base64 编码的字符串，用于对 TOS 存储桶中的数据执行加密或解密操作。访问已通过 SSE-C 加密的存量数据时，必须使用写入数据时对应的同一密钥。
SSECMD5	String	aGVsbG****	SSE-C 加密方式下，加密密钥对应的 base64 编码 128 位 MD5 摘要，用于服务端校验加密密钥的完整性与正确性，确保加密密钥未被篡改。
EnableSSE	Boolean	true	指定 TOS 挂载点是否启用服务端加密功能，取值如下： true：已启用服务端加密，系统将对该挂载点关联的 TOS 存储桶内数据执行服务端加密存储。 false：未启用服务端加密。
KMSMasterKeyID	String	trn:kms:***:210040:key/abc123d**	当 TOS 挂载点的服务端加密方式为 SSE-KMS时，需指定该字段，用于关联 KMS 服务中对应的用户管理主密钥，实现 TOS 存储桶数据的服务端加密保护。
EncryptionMethod	String	SSE-TOS	指定 TOS 挂载点的服务端加密方式，取值如下： SSE-KMS：使用 KMS 托管密钥的服务端加密方式。 SSE-TOS：使用 TOS 托管密钥的服务端加密方式。
EncryptionAlgorithm	String	AES256	指定 TOS 挂载点服务端加密所使用的加密算法，当前仅支持 AES256 算法。

EfsBackendConfig

参数	类型	示例值	描述
ZoneId	String	cn-beijing-a	弹性文件存储（EFS）接入点所属的可用区标识，必须为函数 VPC 子网已覆盖的可用区。
MountTarget	String	/efs/ap-example.*****.efs.ivolces.com:/	EFS 接入点的挂载地址，格式为 /efs/<mount-target-domain>:<export-path>。占位符说明如下： <mount-target-domain>：接入点域名，填写 EFS 接入点对应的域名。 <export-path>：导出路径，填写需要挂载的 EFS 目录。挂载根目录时填写 /。

EfsEncryptionConfig

参数	类型	示例值	描述
SSECKey	String	aGVsbG9Xb3JsZF****	SSE-C 加密方式使用的密钥，为 32 字节的可打印 ASCII 字符串。访问已通过 SSE-C 加密的存量弹性文件存储（EFS）数据时，必须使用写入数据时对应的同一密钥。
SSECMD5	String	d41d8cd****	SSE-C 加密密钥对应的 MD5 值，为 32 位小写十六进制字符串，由调用方计算后传入，用于服务端校验加密密钥的完整性与正确性，确保加密密钥未被篡改。
SSECAlgorithm	String	AES_256_XTS	SSE-C 加密方式所使用的加密算法，当前固定取值为 AES_256_XTS。

IPRule

参数	类型	示例值	描述
Cidrs	Array of String	["10.0.0.0/8","192.0.2.10"]	IPv4 地址列表，支持填写 CIDR 地址段或单个 IPv4 地址。每条规则最多可配置 16 个地址。
Ports	Array of EgressPortRange	-	访问规则对应的目标端口范围配置，支持指定协议、单个端口或端口区间。空数组或不填写表示匹配所有端口。

EgressPortRange

参数	类型	示例值	描述
Port	Integer	440	目标端口或端口范围的起始端口，取值范围为 1～65535。不传时，表示匹配指定协议的所有端口。
EndPort	Integer	443	端口范围的结束端口，取值范围为 1～65535，且必须大于或等于 Port。
Protocol	String	TCP	网络传输协议，大小写敏感，取值如下： TCP：默认值，传输控制协议。 UDP：用户数据报协议。

返回示例

错误码

当前接口暂无独立错误码，若接口调用返回异常，可参考公共错误码进行故障排查。

函数服务