调用PutSecretValue为凭据存入新版本的凭据值-密钥管理服务-阿里云-密钥管理服务(KMS)-阿里云帮助中心

接口说明

RAM 用户或 RAM 角色调用该 OpenAPI 需要被授予的权限策略详情，请参见访问控制。
仅通用凭据支持本接口，每个通用凭据最多保存 10 个凭据版本，超出时 KMS 会滚动删除最早的凭据版本。
默认情况下，新存入的凭据值被标记为 ACSCurrent，而 ACSCurrent 标记的前一个版本被标记为 ACSPrevious。您可以通过指定 VersionStage 参数来覆盖该默认行为。
此接口用于存入新版本的凭据值，而不能用于修改已有版本的凭据值。存入新版本时需指定版本号，KMS 按照如下规则进行操作：
- 版本号在凭据内不存在：创建新版本并存入凭据值。
- 版本号在凭据内存在：如果入参中的凭据值和凭据内该版本号对应的凭据值相同，则请求会被忽略，并且返回成功（请求是幂等的），不相同时则请求会被拒绝，且返回失败。

本文将提供一个示例，为凭据名称是secret001的凭据存入一个新版本的凭据值，新凭据版本号VersionId为v3、凭据值SecretData为importantdata。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

kms:PutSecretValue

update

*Secret

acs:kms:{#regionId}:{#accountId}:secret/{#SecretName}

无

kms:GenerateDataKey

请求参数

名称	类型	必填	描述	示例值
VersionId	string	是	凭据的版本号，在该凭据内唯一。	v3
SecretName	string	是	凭据名称或凭据资源名称（ARN）。说明访问其他阿里云账号下的凭据时，必须输入凭据 ARN。凭据 ARN 的格式为`acs:kms:${region}:${account}:secret/${secret-name}`。	secret001
SecretData	string	是	凭据值。加密后存入指定的新版本中。	importantdata
SecretDataType	string	否	凭据值类型。取值： text（默认值） binary	text
VersionStages	string	否	凭据版本在存入时需要被同时标记的版本状态。如果您不指定此参数，KMS 默认为新版本标记 ACSCurrent。	["ACSCurrent","ACSNext"]

关于公共请求参数的详情，请参见公共参数。

返回参数

名称	类型	描述	示例值
	object
RequestId	string	本次调用请求的 ID，是由阿里云为该请求生成的唯一标识符，可用于排查和定位问题。	f94ec9d3-2d10-4922-9a5c-5dcd5ebcb5e8
SecretName	string	凭据名称。	secret001
VersionId	string	凭据的版本号。	v3
VersionStages	object
VersionStage	array	凭据的版本状态。
	string	凭据的版本状态。	{ "VersionStage": [ "ACSCurrent", "ACSNext" ] }

示例

正常返回示例

JSON格式

{
  "RequestId": "f94ec9d3-2d10-4922-9a5c-5dcd5ebcb5e8",
  "SecretName": "secret001",
  "VersionId": "v3",
  "VersionStages": {
    "VersionStage": [
      "{ \"VersionStage\": [ \"ACSCurrent\", \"ACSNext\" ] }"
    ]
  }
}

错误码

HTTP status code	错误码	错误信息
400	InvalidParameter	some of the specified parameters "\" is not valid
400	Rejected.LimitExceeded	exceed secret limits error
500	InternalFailure	Internal Failure
403	Forbidden.NoPermission	This operation is forbidden by permission system
404	Forbidden.ResourceNotFound	Resource not found
409	Rejected.ResourceExist	The request was rejected becasue key already exsit

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。