# 添加自定义镜像版本 - AddV2TenantImageVersion #### 功能介绍 为已注册的镜像添加新的版本信息。此接口为同步接口，与[注册自定义镜像](https://support.huaweicloud.com/api-aidatalake/RegisterV2TenantImage.html)接口配合完成镜像版本管理。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-aidatalake/aidatalake_02_0003.html)。 #### URI POST /v2/images/{image_id}/versions 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | image_id | 是 | String | **参数解释** ：镜像ID。可通过[查询自定义镜像列表](https://support.huaweicloud.com/api-aidatalake/ListV2TenantImages.html)获取镜像ID。 **约束限制**：不涉及。 **取值范围**：长度为32\~36的英文字符、数字和中划线的组合。 **默认取值**：不涉及。 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | **参数解释** ：用户Token，通过调用[获取IAM用户Token](https://support.huaweicloud.com/api-iam/iam_30_0001.html)接口获取。 **约束限制**：不涉及。 **取值范围**：只能由英文字母、数字及特殊字符组成，长度不超过65534个字符。Token格式由IAM服务定义，具体字符集参见IAM服务相关文档。 **默认取值**：不涉及。 | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | image_url | 是 | String | **参数解释**：自定义镜像的URL地址，由镜像仓库地址、镜像命名空间、镜像名称和镜像版本组成。 **约束限制**：不涉及。 **取值范围**：由大小写英文字母、数字、小数点(.)、斜杠(/)、冒号(:)、下划线(_)和连字符(-)组成的容器镜像地址。长度为1\~2000个字符。 **默认取值**：不涉及。 | | category | 是 | String | **参数解释**：自定义镜像的分类。 **约束限制**：不涉及。 **取值范围**： - RAY_BASIC：基于Ray构建的自定义镜像。 - SPARK_JOB：基于SparkJob构建的自定义镜像。 - SPARK_SQL：基于SparkSql构建的自定义镜像。 - FLINK_JOB：基于FlinkJob构建的自定义镜像。 - AURA_JOB：基于AuraJobV2构建的自定义镜像。 **默认取值**：不涉及。 | | architectures | 否 | Array of strings | **参数解释**：镜像支持的架构列表，取值包括：x86_64（x86架构）、aarch64（ARM架构），未传入该参数时默认为x86_64。 **约束限制**：不涉及。 | | type | 是 | String | **参数解释**：版本类型。 **约束限制**：不涉及。 **取值范围**： - STABLE：稳定版本。 - RECOMMEND：推荐版本。 - BETA：测试版本。 **默认取值**：不涉及。 | | container_softwares | 否 | Array of [ContainerSoftware] objects | **参数解释**：自定义镜像包含的软件列表，每个元素为一个ContainerSoftware对象，包含软件名称和版本信息。 **约束限制**：软件列表最小个数为0，最大个数为100。 | | description | 否 | String | **参数解释**：自定义镜像的描述。 **约束限制**：不涉及。 **取值范围**：不允许输入感叹号、小于号、大于号、等号、与号、双引号、单引号、艾特符、井号、百分号、分号、左括号、右括号、竖线、星号、反斜杠。长度为0\~2000个字符。 **默认取值**：不涉及。 | | base_image_id | 否 | String | **参数解释** ：基础镜像ID，可通过[查询自定义镜像列表](https://support.huaweicloud.com/api-aidatalake/ListV2TenantImages.html)获取镜像ID。 **约束限制**：Spark类型镜像必填。 **取值范围**：支持英文字母、数字及中划线，长度0\~64个字符。 **默认取值**：不涉及。 | | base_image_version_id | 否 | String | **参数解释** ：基础镜像版本ID，可通过[查询自定义镜像版本列表](https://support.huaweicloud.com/api-aidatalake/ListV2TenantImageVersions.html)获取镜像版本ID。 **约束限制**：当镜像分类为Spark类型时此字段必填，其余情况可选。 **取值范围**：支持英文字母、数字及中划线，长度0\~64个字符。 **默认取值**：不涉及。 | 表4ContainerSoftware | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | name | 是 | String | **参数解释**：软件名称。 **约束限制**：不涉及。 **取值范围**：支持英文字母、数字、小数点、下划线和连字符，2\~32个字符。 **默认取值**：不涉及。 | | version | 是 | String | **参数解释**：软件版本。 **约束限制**：不涉及。 **取值范围**：支持英文字母、数字、小数点、下划线和连字符，2\~32个字符。 **默认取值**：不涉及。 | #### 响应参数 **状态码：200** 表5响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | version_id | String | **参数解释**：镜像版本ID。 **取值范围**：长度为32\~36的英文字符、数字和中划线的组合。 | | image_version | String | **参数解释**：镜像版本。 **取值范围**：支持英文字母、数字、小数点、斜杠、冒号、下划线和连字符，长度2\~32个字符。 | | category | String | **参数解释**：镜像分类。 **取值范围**： - RAY_BASIC：基于Ray构建的自定义镜像。 - SPARK_JOB：基于SparkJob构建的自定义镜像。 - SPARK_SQL：基于SparkSql构建的自定义镜像。 - FLINK_JOB：基于FlinkJob构建的自定义镜像。 - AURA_JOB：基于AuraJobV2构建的自定义镜像。 | | image_registry | String | **参数解释**：镜像域名。 **取值范围**：支持英文字母、数字、小数点及连字符，长度0\~255个字符。 | | image_namespace | String | **参数解释**：镜像命名空间。 **取值范围**：由英文字母、数字、中划线和下划线组成，长度0\~64个字符。 | | image_name | String | **参数解释**：镜像名。 **取值范围**：由中文字符、英文字母、数字、中划线和下划线组成，长度0\~128个字符。 | | architectures | Array of strings | **参数解释**：镜像支持的架构列表，取值包括：x86_64（x86架构）、aarch64（ARM架构）。 | | container_softwares | Array of [ContainerSoftware] objects | **参数解释**：镜像软件列表，每个元素为一个ContainerSoftware对象，包含软件名称和版本信息。 | | status | String | **参数解释**：镜像版本状态。 **取值范围**： - AVAILABLE：可用。 - UNAVAILABLE：不可用。 - UNKNOWN：未知。 | | type | String | **参数解释**：镜像版本类型。 **取值范围**： - STABLE：稳定版本。 - RECOMMEND：推荐版本。 - BETA：测试版本。 | | visibility | String | **参数解释**：镜像版本可见性。 **取值范围**： - PRIVATE：私有，仅工作空间内可见。 - PUBLIC：公共，所有工作空间可见。 | | create_time | String | **参数解释**：自定义镜像版本创建时间，使用UTC时间，ISO 8601格式，yyyy-MM-dd'T'HH:mm:ss.SSSXXX，例如：2025-01-10T03:37:12.000+00:00。 **取值范围**：不涉及。 | | update_time | String | **参数解释**：自定义镜像版本更新时间，使用UTC时间，ISO 8601格式，yyyy-MM-dd'T'HH:mm:ss.SSSXXX，例如：2025-01-10T03:37:12.000+00:00。 **取值范围**：不涉及。 | | description | String | **参数解释**：镜像版本描述。 **取值范围**：支持中文字符、英文字母、数字及常用符号（不允许输入感叹号、小于号、大于号、等号、与号、双引号、单引号），长度0\~2000个字符。 | | base_image_id | String | **参数解释**：关联的预置基础镜像ID。 **取值范围**：支持英文字母、数字及中划线，长度0\~64个字符。 | | base_image_version_id | String | **参数解释**：关联的预置基础镜像版本ID。 **取值范围**：支持英文字母、数字及中划线，长度0\~64个字符。 | | image_snapshot | [V2ImageSnapshotInfo] object | **参数解释**：匹配到的镜像快照信息，无快照时为null。 | 表6ContainerSoftware | 参数 | 参数类型 | 描述 | |:---|:---|:---| | name | String | **参数解释**：软件名称。 **取值范围**：支持英文字母、数字、小数点、下划线和连字符，2\~32个字符。 | | version | String | **参数解释**：软件版本。 **取值范围**：支持英文字母、数字、小数点、下划线和连字符，2\~32个字符。 | 表7V2ImageSnapshotInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | **参数解释**：镜像快照记录ID。 **取值范围**：长度为32\~36的英文字符、数字和中划线的组合。 | | image_id | String | **参数解释**：镜像ID。 **取值范围**：长度为32\~36的英文字符、数字和中划线的组合。 | | image_version_id | String | **参数解释**：镜像版本ID。 **取值范围**：长度为32\~36的英文字符、数字和中划线的组合。 | | name | String | **参数解释**：镜像快照名称（用户指定）。 **取值范围**：以小写字母开头，小写字母、数字、中划线（-）组成，小写字母或数字结尾的1到190字符的字符串。 | | image_address | String | **参数解释**：镜像完整地址（含registry/namespace/name:version）。 **取值范围**：支持英文字母、数字、小数点、冒号、斜杠及连字符，长度为0\~1024个字符。 | | image_name | String | **参数解释**：镜像名称。 **取值范围**：支持英文字母、数字、小数点、斜杠、冒号、下划线和连字符，长度为0\~128个字符。 | | image_version | String | **参数解释**：镜像版本。 **取值范围**：支持英文字母、数字、小数点、冒号、下划线和连字符，长度为0\~1024个字符。 | | status | String | **参数解释**：镜像快照状态。 **取值范围**： - Creating：创建中。 - Available：可用。 - Unavailable：不可用。 | | image_snapshot_size | Integer | **参数解释**：快照大小，单位GiB。 **取值范围**：20\~400。 | | creation_mode | String | **参数解释**：创建方式。 **取值范围**： - Created：直接创建。 - Associated：关联CCI已有快照。 | | reserved_days | Integer | **参数解释**：镜像快照保留天数。超过保留天数自动失效，0表示永久保留。 **取值范围**：0\~65536。 | | expire_time | String | **参数解释**：镜像快照超期时间，null表示永久有效。使用UTC时间，ISO 8601格式，yyyy-MM-dd'T'HH:mm:ss.SSSXXX，例如：2025-01-10T03:37:12.000+00:00。 **取值范围**：不涉及。 | | failed_message | String | **参数解释**：镜像快照失效的提示信息。 **取值范围**：支持中文字符、英文字母、数字及常用符号，长度为0\~65535个字符。 | | create_time | String | **参数解释**：创建时间，使用UTC时间，ISO 8601格式，yyyy-MM-dd'T'HH:mm:ss.SSSXXX，例如：2025-01-10T03:37:12.000+00:00。 **取值范围**：不涉及。 | | update_time | String | **参数解释**：更新时间，使用UTC时间，ISO 8601格式，yyyy-MM-dd'T'HH:mm:ss.SSSXXX，例如：2025-01-10T03:37:12.000+00:00。 **取值范围**：不涉及。 | **状态码：400** 表8响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码。 **取值范围**：长度为8\~36个字符。 | | error_msg | String | **参数解释**：错误描述。 **取值范围**：长度为2\~512个字符。 | | solution_msg | String | **参数解释**：解决方案。 **取值范围**：长度为0\~4096个字符。 | **状态码：401** 表9响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码。 **取值范围**：长度为8\~36个字符。 | | error_msg | String | **参数解释**：错误描述。 **取值范围**：长度为2\~512个字符。 | | solution_msg | String | **参数解释**：解决方案。 **取值范围**：长度为0\~4096个字符。 | **状态码：403** 表10响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码。 **取值范围**：长度为8\~36个字符。 | | error_msg | String | **参数解释**：错误描述。 **取值范围**：长度为2\~512个字符。 | | solution_msg | String | **参数解释**：解决方案。 **取值范围**：长度为0\~4096个字符。 | **状态码：404** 表11响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码。 **取值范围**：长度为8\~36个字符。 | | error_msg | String | **参数解释**：错误描述。 **取值范围**：长度为2\~512个字符。 | | solution_msg | String | **参数解释**：解决方案。 **取值范围**：长度为0\~4096个字符。 | **状态码：500** 表12响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码。 **取值范围**：长度为8\~36个字符。 | | error_msg | String | **参数解释**：错误描述。 **取值范围**：长度为2\~512个字符。 | | solution_msg | String | **参数解释**：解决方案。 **取值范围**：长度为0\~4096个字符。 | #### 请求示例 为已有镜像添加新版本。 ``` POST /v2/images/{image_id}/versions { "image_url" : "swr.cn-north-4.myhuaweicloud.com/test-image/spark_job:v1", "category" : "SPARK_JOB", "type" : "STABLE", "architectures" : [ "x86_64" ], "container_softwares" : [ { "name" : "jdk", "version" : "21" } ], "description" : "test image", "base_image_id" : "2b5633ba2b904511ad514346f4d23d4b", "base_image_version_id" : "3c6744cb3c015622be65457a5e34de5c" } ``` #### 响应示例 **状态码：200** ``` { "version_id" : "c2533937-101d-4a5b-9c8d-03c2ee815f1d", "image_version" : "v1", "category" : "SPARK_JOB", "image_registry" : "swr.cn-north-4.myhuaweicloud.com", "image_namespace" : "test-image", "image_name" : "spark_job", "architectures" : [ "x86_64" ], "container_softwares" : [ { "name" : "jdk", "version" : "21" } ], "status" : "AVAILABLE", "type" : "STABLE", "visibility" : "PRIVATE", "create_time" : "2025-01-10T03:37:12.000+00:00", "update_time" : "2025-01-10T03:37:12.000+00:00", "description" : "test image" } ``` **状态码：400** ``` { "error_code" : "AIDataLake.00010151", "error_msg" : "Parameter value is invalid.", "solution_msg" : "Please input valid parameter value." } ``` **状态码：401** ``` { "error_code" : "APIGW.0301", "error_msg" : "Incorrect IAM authentication information: decrypt token fail.", "solution_msg" : "Check whether the IAM authentication information is correct." } ``` **状态码：403** ``` { "error_code" : "AIDataLake.00010150", "error_msg" : "The operation is not allowed.", "solution_msg" : "Check whether the operation is allowed in the current status." } ``` **状态码：404** ``` { "error_code" : "AIDataLake.00010009", "error_msg" : "No resources found.", "solution_msg" : "Ensure the requested resource exists and the parameters are correct." } ``` **状态码：500** ``` { "error_code" : "AIDataLake.00011001", "error_msg" : "Internal error.", "solution_msg" : "Contact technical support or try again later." } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 请求成功。 | | 400 | 请求参数错误。 | | 401 | 未授权。 | | 403 | 禁止访问。 | | 404 | 资源未找到。 | | 500 | 内部服务器错误。 |