All Products
Search
Document Center

Key Management Service:PutSecretValue

更新時間:May 16, 2024

Stores the secret value of a new version into a generic secret.

Note Only generic secrets support the operation. Each generic secret can have up to 10 versions. If a generic secret has more than 10 versions, Key Management Service (KMS) automatically deletes the earliest version in a rolling manner.

By default, the newly stored secret value is labeled as ACSCurrent, and the label for the previous version of the secret value is changed from ACSCurrent to ACSPrevious. If you specify VersionStage, the newly stored secret value is labeled as the stage label that you specify.

This operation is used to store the secret values of new versions. It cannot be used to modify the secret value of an existing version. When you store a new version, you must specify the version number. KMS follows these rules:

  • If the specified version number does not exist in the secret, KMS creates the version and stores the secret value.
  • If the specified version number already exists in the secret and the secret value of the version is the same as the secret value that you specify, KMS ignores the request and returns a success message. The request is idempotent. If the specified version number already exists in the secret but the secret value of the version is different from the secret value that you specify, KMS rejects the request and returns a failure message.

In the following example, the secret value of a new version is stored into the secret001 secret. VersionId is set to v3, and SecretData is set to importantdata

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter

Type

Required

Example

Description

Action String Yes PutSecretValue

The operation that you want to perform. Set the value to PutSecretValue.

VersionId String Yes v3

The version number of the secret, which is unique within the secret.

SecretName String Yes secret001

The Alibaba Cloud Resource Name (ARN) of the secret or secret resource.

Note When you access a secret within another Alibaba Cloud account, you must enter the ARN of the secret. The ARN is in the acs:kms:${region}:${account}:secret/${secret-name} format.
SecretData String Yes importantdata

The secret value. The secret value is encrypted and then stored in the new version.

SecretDataType String No text

The type of the secret value. Valid values:

  • text (default)
  • binary
VersionStages String No ["ACSCurrent","ACSNext"]

The stage label that is used to mark the new version. If you do not specify the parameter, KMS marks the new version with ACSCurrent.

For more information about common request parameters, see Common parameters.

Response parameters

Parameter

Type

Example

Description

SecretName String secret001

The secret name.

VersionId String v3

The version number of the secret.

RequestId String f94ec9d3-2d10-4922-9a5c-5dcd5ebcb5e8

The ID of the request, which is used to locate and troubleshoot issues.

VersionStages Array of String { "VersionStage": [ "ACSCurrent", "ACSNext" ] }

The stage label of the secret.

Examples

Sample requests

http(s)://[Endpoint]/?Action=PutSecretValue
&VersionId=v3
&SecretName=secret001
&SecretData=importantdata
&SecretDataType=text
&VersionStages=["ACSCurrent","ACSNext"]
&Common request parameters

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

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

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

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

Error codes

For a list of error codes, see Service error codes.