文档中心

函数服务

沙箱镜像

PrecacheSandboxImages

PrecacheSandboxImages

批量预热用户自定义镜像。

请求说明

请求方式：POST

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

调试

API Explorer

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

请求参数

参数	类型	是否必选	示例值	描述
Action	String	是	PrecacheSandboxImages	接口名称。当前 API 的名称为 PrecacheSandboxImages。
Version	String	是	2024-06-06	接口版本。当前 API 的版本为 2024-06-06。
ImageUrls	Array of String	是	["registry.****.com/demo/app:v1.0.0"]	需要预热的 Sandbox 自定义镜像地址列表。火山引擎镜像仓库：在镜像仓库（CR）中上传镜像后，在镜像仓库控制台的 OCI 制品仓库页面具体镜像详情中获取镜像地址。第三方镜像仓库：待预热镜像的完整地址，格式为 <registry-domain>/<namespace>/<repository-name>:<tag>。 <registry-domain>：镜像仓库域名。填写镜像仓库提供的访问域名，不包含 http:// 或 https://。 <namespace>：命名空间。用于对镜像仓库中的镜像进行分组和权限隔离。 <repository-name>：OCI 制品仓库的名称，也就是镜像地址中的镜像名称。 <tag>：镜像版本标签，例如 v1.0.0、20261020 或 latest。
RegistryType	String	否	Custom	镜像仓库的类型。支持的取值如下所示。 CR：火山引擎镜像仓库。使用镜像仓库 CR 托管的镜像。镜像上传后可直接执行预热，无需额外配置仓库访问凭证和网络访问方式。 Custom：自定义镜像仓库。使用第三方或自建镜像仓库中的镜像，例如 Harbor、Nexus 和兼容 Registry V2 标准的仓库。执行预热时，需要配置仓库访问凭证和网络访问方式。
RegistryAuthConfig	Object of SandboxImagePrecacheAuthConfig	否	-	镜像仓库的认证配置。用于设置云沙箱从自定义镜像仓库拉取镜像时采用的传输协议和 HTTPS 证书校验策略。默认使用 HTTPS 协议并校验证书，请在仓库配置不满足默认要求时修改。仅当 RegistryType 为 Custom 时需要填写。
NetworkConfig	Object of SandboxImagePrecacheNetworkConfig	否	-	镜像仓库的网络配置。用于指定公网访问或私有 VPC 访问。选择私有 VPC 时还需要配置 VPC、子网和安全组。仅当 RegistryType 为 Custom 时需要填写。
ClientToken	String	否	c5e54fd8-6c83-4e01-a0c4-7b16af2d****	用于保证请求幂等性的凭证。在同一账号下，若请求携带相同的该凭证且请求参数完全一致，接口将返回相同的 TicketId，避免重复执行相同操作。

SandboxImagePrecacheAuthConfig

参数	类型	是否必选	示例值	描述
AuthType	String	是	BasicAuth	自定义镜像仓库的认证类型，用于指定访问该仓库时的认证方式，取值如下。 BasicAuth：以用户名和密码组合校验身份，填写访问仓库的用户名与密码。 BearerToken：以令牌校验身份，填写访问仓库的 Token，适用于 Harbor 等仓库的机器人账户。 Anonymous：镜像仓库对目标镜像公开、无需认证，可直接拉取。
Token	String	否	eyJhbG****adQssw5c	认证使用的令牌，当认证类型（AuthType）为 BearerToken 时生效。
Password	String	否	pass****123	认证使用的密码，当认证类型（AuthType）为 BasicAuth 时生效。
Username	String	否	robot****	认证使用的用户名，当认证类型（AuthType）为 BasicAuth 时生效。
UsePlainHTTP	Boolean	否	false	是否强制使用 HTTP 协议拉取源镜像。 true：使用 HTTP 协议拉取源镜像。镜像仓库未配置 HTTPS 证书、仅支持 HTTP 协议访问时使用。 false：默认值，不使用 HTTP 协议拉取源镜像。
SkipCertVerification	Boolean	否	false	当拉取自定义镜像仓库镜像使用 HTTPS 协议时，是否跳过对仓库 HTTPS 证书的合法性校验。 true：跳过证书校验，镜像仓库使用自签证书或证书链不完整、无法完成正常校验等场景时选择。 false：默认值，正常校验证书合法性。

SandboxImagePrecacheNetworkConfig

参数	类型	是否必选	示例值	描述
VpcId	String	否	vpc-****	自定义镜像仓库所在的私有网络 ID，网络访问类型（AccessType）为 PrivateVpc 时生效。
SubnetId	String	否	subnet-***	自定义镜像仓库所在的子网 ID，网络访问类型（AccessType）为 PrivateVpc 时生效。
AccessType	String	是	PrivateVpc	云沙箱拉取自定义镜像仓库镜像时的网络访问类型，仅当 RegistryType 为 Custom 时生效。支持的取值如下所示。 Public：通过公网访问自定义镜像仓库； PrivateVpc：通过私有 VPC 网络访问自定义镜像仓库。
SecurityGroupIds	Array of String	否	["sg-**","sg-**"]	用于指定云沙箱通过私有 VPC 访问自定义镜像仓库时，关联的安全组列表，当网络访问类型（AccessType）为 PrivateVpc 时生效。

请求示例

返回参数

参数	类型	示例值	描述
TicketId	String	948410ee80954******	预热工单 ID。接口成功返回仅表示已提交预热任务。请调用查询预热工单详情接口（GetSandboxImagePrecacheTicket），并传入 TicketId，当工单状态为成功（success）时，表示镜像预热完成。

返回示例

错误码

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

最近更新时间：2026.11.02 16:16:46

这个页面对您有帮助吗？

有用

有用

无用

无用