模板预热

步骤一：初始化 SDK 客户端

安装 Go SDK（Software Development Kit，软件开发工具包）及依赖。

go get github.com/alibabacloud-go/sandbox-20260820/client
go get github.com/alibabacloud-go/darabonba-openapi/v2/utils
go get github.com/alibabacloud-go/tea/dara

设置访问凭证：

export ALIBABA_CLOUD_ACCESS_KEY_ID="<YOUR-ACCESS-KEY-ID>"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="<YOUR-ACCESS-KEY-SECRET>"
# 使用 STS 临时凭证时，还需设置：
# export ALIBABA_CLOUD_SECURITY_TOKEN="<YOUR-SECURITY-TOKEN>"

以下示例均基于 OpenAPI 版本 2026-08-20。客户端初始化方法在后续各步骤中复用，不再重复列出 import 语句。

package main

import (
    "fmt"
    "os"
    "time"

    openapiutil "github.com/alibabacloud-go/darabonba-openapi/v2/utils"
    sandbox "github.com/alibabacloud-go/sandbox-20260820/client"
    "github.com/alibabacloud-go/tea/dara"
)

func newClient(region string) (*sandbox.Client, error) {
    return sandbox.NewClient(&openapiutil.Config{
        AccessKeyId:     dara.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")),
        AccessKeySecret: dara.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")),
        SecurityToken:   dara.String(os.Getenv("ALIBABA_CLOUD_SECURITY_TOKEN")),
        Endpoint:        dara.String("sandbox." + region + ".aliyuncs.com"),
        Protocol:        dara.String("https"),
    })
}

长期 AccessKey 无需设置 ALIBABA_CLOUD_SECURITY_TOKEN；使用 STS 临时凭证时必须设置。

步骤二：创建预热任务并轮询至就绪

调用 CreateTemplateCache 提交预热任务，再轮询 DescribeTemplateCache 直到 status 变为 ready。请求成功表示任务已被平台受理，预热在后台异步完成，受理成功不代表预热完成。示例每 15 秒轮询一次，最长等待 20 分钟，超时后继续查询任务状态，不要重复创建。模板尚未完成构建时，CreateTemplateCache 返回 409 TemplateNotReady，且不会创建预热任务。

func createAndWait(client *sandbox.Client, teamID, templateID string) error {
    resp, err := client.CreateTemplateCache(&sandbox.CreateTemplateCacheRequest{
        Body: &sandbox.CreateTemplateCacheInput{
            TeamID:     dara.String(teamID),
            TemplateID: dara.String(templateID),
        },
    })
    if err != nil {
        return fmt.Errorf("CreateTemplateCache: %w", err)
    }

    cache := resp.Body.TemplateCache
    fmt.Printf("accepted: status=%s requestId=%s\n",
        dara.StringValue(cache.Status), dara.StringValue(resp.Body.RequestId))

    deadline := time.Now().Add(20 * time.Minute)
    for time.Now().Before(deadline) {
        got, err := client.DescribeTemplateCache(
            dara.String(templateID),
            &sandbox.DescribeTemplateCacheRequest{TeamID: dara.String(teamID)},
        )
        if err != nil {
            return fmt.Errorf("DescribeTemplateCache: %w", err)
        }

        cache = got.Body.TemplateCache
        status := dara.StringValue(cache.Status)
        fmt.Printf("status=%s progress=%d reason=%q sizeMB=%d requestId=%s\n",
            status,
            dara.Int32Value(cache.Progress),
            dara.StringValue(cache.StatusReason),
            dara.Int32Value(cache.ImageSizeMB),
            dara.StringValue(got.Body.RequestId),
        )

        switch status {
        case "ready":
            return nil
        case "failed", "evicted":
            return fmt.Errorf("template cache is %s: %s", status, dara.StringValue(cache.StatusReason))
        }
        time.Sleep(15 * time.Second)
    }
    return fmt.Errorf("timed out waiting for template cache")
}

预热是否完成只以 status 为 ready 为准。progress 仅用于展示任务进度，取值只有 0（未就绪）和 100（已就绪）两种，不会按百分比逐步推进，不作为就绪判定条件。

步骤三：使用预热就绪的模板创建沙箱

status 为 ready 后，即可使用该模板创建沙箱。需等待状态就绪后再创建，才能获得预热加速；预热未完成时创建沙箱通常只是无法提速，若镜像加速数据仍在准备中，可能返回 400 accelerated image not ready，请就绪后重试。具体操作，请参见创建沙箱。

查询预热状态

调用 DescribeTemplateCache，传入模板 ID 和 Team ID，根据返回的 status 判断任务状态：

• creating：任务已受理，可能正在排队、等待容量、等待并发或执行预热。继续查询，不重复创建。

• ready：预热完成，可使用该模板创建沙箱。

• failed：预热失败。查看 statusReason 排查，先删除再重新创建。

• evicted：预热数据已被平台回收，不能再提供预热加速。先删除，等待返回 404 后重新创建，并一并删除同地域内同一镜像（imageDigest）的其他 evicted 任务，否则新任务可能立即回到 evicted。

分页查询预热任务

调用 ListTemplateCache 分页查询当前 Team 的预热任务，可通过 templateID 和 status 过滤，maxResults 默认为 20，取值范围为 1 到 100，超出取值范围时按边界值处理，不返回错误。以 nextToken 是否为空判断分页结束，不能根据当前页条数判断。

删除预热任务

不再需要预热时，调用 DeleteTemplateCache 删除预热任务。

func deleteCache(client *sandbox.Client, teamID, templateID string) error {
    resp, err := client.DeleteTemplateCache(
        dara.String(templateID),
        &sandbox.DeleteTemplateCacheRequest{TeamID: dara.String(teamID)},
    )
    if err != nil {
        return fmt.Errorf("DeleteTemplateCache: %w", err)
    }
    fmt.Printf("delete accepted: requestId=%s\n", dara.StringValue(resp.Body.RequestId))
    return nil
}

DeleteTemplateCache 返回成功后，继续调用 DescribeTemplateCache，直到返回 404 TemplateCacheNotFound，方可认为预热任务的逻辑删除完成。返回成功仅表示删除请求已被接受，底层镜像数据在没有存活实例继续引用对应镜像后由平台异步安全清理；重复删除返回 404。

对状态为 failed 或 evicted 的任务重新预热时，同样需先删除，再调用 CreateTemplateCache。