更新时间:2026-05-20 GMT+08:00
分享

创建凭据版本 - CreateSecretVersion

功能介绍

在指定的凭据中,创建一个新的凭据版本,用于加密保管新的凭据值。默认情况下,新创建的凭据版本被标记为SYSCURRENT状态,而SYSCURRENT标记的前一个凭据版本被标记为SYSPREVIOUS状态。您可以通过指定VersionStage参数来覆盖默认行为

接口约束

  • 凭据管理服务console控制台仅使用secret_string字段。如果您想要添加二进制类型凭据到secret_binary字段中保存,必须使用SDK或API的方式

  • 凭据管理服务的每个凭据中最多可支持20个版本

  • 只能对处于ENABLED状态的凭据添加新的版本

  • 每次存入新的凭据值时,凭据版本号按照为v1,v2,v3...的模式自动增加

调用方法

请参见如何调用API

授权信息

账号具备所有API的调用权限,如果使用账号下的IAM用户调用当前API,该IAM用户需具备调用API所需的权限。

  • 如果使用角色与策略授权,具体权限要求请参见权限和授权项
  • 如果使用身份策略授权,需具备如下身份策略权限。

    授权项

    访问级别

    资源类型(*为必须)

    条件键

    别名

    依赖的授权项

    csms:secret:createVersion

    Write

    secretName *

    • csms:Type

    • g:EnterpriseProjectId

    • g:ResourceTag/<tag-key>

    csms:secretVersion:create

    kms:cmk:createDataKey

URI

POST /v1/{project_id}/secrets/{secret_name}/versions

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

参数解释:

项目ID。可参考获取项目ID获取。

约束限制:

不涉及

取值范围:

以IAM服务接口返回值为准,字符长度32-32

默认取值:

不涉及

secret_name

String

参数解释:

凭据名称

约束限制:

不涉及

取值范围:

需要满足正则表达式:^[a-zA-Z0-9_-]{1,64}$

默认取值:

不涉及

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

String

参数解释:

用户Token。 通过调用IAM服务查询用户Token接口获取(响应消息头中X-Subject-Token的值)。使用AK、SK等认证方式,此处非必选

约束限制:

不涉及

取值范围:

IAM服务查询用户Token接口为准

默认取值:

不涉及

表3 请求Body参数

参数

是否必选

参数类型

描述

secret_binary

String

参数解释:

二进制类型凭据在base64编码后的明文,凭据管理服务将其加密后,存入凭据的初始版本中

约束限制:

secret_binary和secret_string必须且只能设置一个,最大64K

取值范围:

不涉及

默认取值:

不涉及

secret_string

String

参数解释:

文本类型凭据的明文,凭据管理服务将其加密后,存入凭据的初始版本中

约束限制:

secret_binary和secret_string必须且只能设置一个,最大64K

取值范围:

不涉及

默认取值:

不涉及

version_stages

Array of strings

参数解释:

凭据版本在存入时需要被同时标记的版本状态。如果您不指定此参数,凭据管家默认为新版本标记SYSCURRENT

约束限制:

数组大小:最小1,最大12

取值范围:

不涉及

默认取值:

不涉及

expire_time

Long

参数解释:

凭据版本过期时间,时间戳,即从1970年1月1日至该时间的总秒数。默认为空,凭据订阅“版本过期”事件类型时,有效期判断所依据的值

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

响应参数

状态码:200

表4 响应Body参数

参数

参数类型

描述

version_metadata

VersionMetadata object

参数解释:

凭据版本元数据信息

取值范围:

不涉及

表5 VersionMetadata

参数

参数类型

描述

id

String

参数解释:

凭据的版本号标识符,凭据对象下唯一

取值范围:

不涉及

create_time

Long

参数解释:

凭据版本创建时间,时间戳,即从1970年1月1日至该时间的总秒数

取值范围:

不涉及

expire_time

Long

参数解释:

凭据版本过期时间,时间戳,即从1970年1月1日至该时间的总秒数。默认为空,凭据订阅“版本过期”事件类型时,有效期判断所依据的值

取值范围:

不涉及

kms_key_id

String

参数解释:

加密版本凭据值的KMS主密钥ID

取值范围:

不涉及

secret_name

String

参数解释:

凭据名称

取值范围:

不涉及

version_stages

Array of strings

参数解释:

凭据版本被标记的状态列表。每个版本标签对于凭据对象下版本是唯一存在的,如果创建版本时,指定的是同一凭据对象下的一个已经标记在其他版本上的状态,该标签将自动从其他版本上删除,并附加到此版本上

如果未指定version_stage的值,则凭据管理服务会自动移动临时标签SYSCURRENT到此新版本

取值范围:

不涉及

请求示例

创建凭据版本,凭据值为secret_string

{
  "secret_string" : "secret_string"
}

响应示例

状态码:200

请求已成功

{
  "version_metadata" : {
    "id" : "v1",
    "kms_key_id" : "b168fe00ff56492495a7d22974df2d0b",
    "create_time" : 1581507580000,
    "secret_name" : "secret-name-demo",
    "version_stages" : [ "SYSCURRENT" ]
  }
}

状态码

状态码

描述

200

请求已成功

错误码

请参见错误码

相关文档