全部產品
Search
文件中心

:CreateSecret

更新時間:Jan 22, 2025

建立憑據並存入憑據的初始版本。

您需要指定憑據名稱、初始版本的憑據值和版本號碼。初始版本的狀態被標記為ACSCurrent。

KMS使用您指定的金鑰組憑據值進行加密保護,密鑰和憑據需要屬於同一個KMS執行個體,且密鑰必須為對稱金鑰。

說明 KMS對每個版本的憑據值進行加密,憑據名稱、版本號碼、版本的狀態標記等中繼資料不會被加密。

您對憑據值進行加密前,需要具備密鑰的kms:GenerateDataKey許可權。

本文將提供一個樣本,建立一個名稱為mydbconninfo、初始版本號碼VersionIdv1、憑據值SecretData{"Accounts":[{"AccountName":"user1","AccountPassword":"****"}]}的RDS憑據。

調試

您可以在OpenAPI Explorer中直接運行該介面,免去您計算簽名的困擾。運行成功後,OpenAPI Explorer可以自動產生SDK程式碼範例。

請求參數

名稱

類型

是否必選

樣本值

描述

Action String CreateSecret

要執行的操作。取值:CreateSecret

SecretName String mydbconninfo

憑據名稱。 憑據名稱在當前地區下唯一。

長度不超過192個字元,可包含英文字母、數字、底線(_)、正斜線(/)、加號(+)、等號(=)、半形句號(.)、短劃線(-)和字元(@)。不同類型的憑據名稱要求如下:

  • 當SecretType取值為Generic(通用憑據)、Rds(RDS憑據)、Redis(Redis/Tair憑據)時,不能以acs/開頭。
  • 當SecretType取值為RAMCredentials(RAM憑據)時,使用固定值$Auto。此時KMS自動產生憑據名稱,以acs/ram/user/開頭,包含RAM使用者顯示名稱。
  • 當SecretType取值為ECS(ECS憑據)時,必須以acs/ecs/開頭。
VersionId String v1

初始版本的版本號碼,版本號碼在該憑據內唯一。

長度不超過64個字元。

EncryptionKeyId String key-gzz63ff0db5hg3qje****

用於加密憑據值的密鑰ID。

說明 密鑰和憑據需要屬於同一個KMS執行個體,且密鑰必須為對稱金鑰。
SecretData String {"Accounts":[{"AccountName":"user1","AccountPassword":"****"}]}

憑據值。長度不超過30720位元組(30KB)。KMS使用指定的金鑰組其加密後,存入初始版本中。

  • 當SecretType取值為Generic(通用憑據)時,您可以自訂憑據值。
  • 當SecretType取值為Rds(RDS憑據)時,憑據值格式為:{"Accounts":[{"AccountName":"","AccountPassword":""}]}。其中,AccountName為RDS執行個體的帳號名稱,AccountPassword為RDS執行個體的帳號口令。
  • 當SecretType取值為Redis(Redis憑據)時,參數傳值為 $Auto
  • 當SecretType取值為RAMCredentials(RAM憑據)時,憑據值格式為:{"AccessKeys":[{"AccessKeyId":"","AccessKeySecret":""}]}。其中,AccessKeyId是存取金鑰ID,AccessKeySecret是存取金鑰內容。您需要指定RAM使用者的所有AccessKey。
  • 當SecretType取值為PolarDB 時,參數傳值為 $Auto
  • 當SecretType取值為ECS(ECS憑據)時,憑據值格式為:
    • 當ExtendedConfig參數中SecretSubType取值為Password時:{"UserName":"","Password": ""}。其中,UserName為登入ECS執行個體的使用者名稱,Password為登入ECS執行個體的密碼。
    • 當ExtendedConfig參數中SecretSubType取值為SSHKey時:{"UserName":"","PublicKey": "", "PrivateKey": ""}。其中,PublicKey為登入ECS執行個體的SSH格式公開金鑰,PrivateKey為登入ECS執行個體的私密金鑰。
SecretDataType String text

憑據實值型別。取值:

  • text(預設值):文本類型
  • binary:二進位類型
說明 當SecretType取值為Rds、Redis、PolarDB、RAMCredentials或ECS時,SecretDataType取值只能為text。
Description String mydbinfo

憑據的描述資訊。

Tags String [{\"TagKey\":\"key1\",\"TagValue\":\"val1\"},{\"TagKey\":\"key2\",\"TagValue\":\"val2\"}]

憑據的標籤。每個標籤由一個索引值對(Key:Value)組成,包含標籤鍵(Key)、標籤值(Value)。

標籤建和標籤值的格式:最多支援128個字元,可以包含英文大小寫字母、數字、正斜線(/)、反斜線(\)、底線(_)、短劃線(-)、半形句號(.)、加號(+)、等號(=)、半形冒號(:)、字元at(@)。

  • 標籤鍵不能以aliyun或acs:開頭。
  • 每個憑據最多可以設定20個標籤索引值對。
SecretType String Rds

憑據類型。取值:

  • Generic(預設值):通用憑據。
  • Rds:RDS憑據。
  • Redis:Redis憑據。
  • RAMCredentials:RAM憑據。
  • ECS:ECS憑據。
  • PolarDB:PolarDB憑據。
ExtendedConfig Map {"SecretSubType":"SingleUser", "DBInstanceId":"rm-bp1b3dd3a506e****" ,"CustomData":{"Key1": "v1", "fds":"fdsf"}}

憑據的拓展配置,用於指定特定憑據類型的屬性。長度不超過1024個字元。

  • 當SecretType取值為Generic(通用憑據)時,忽略該參數。
  • 當SecretType取值為Rds(RDS憑據)時,需要指定ExtendedConfig的如下參數:
    • SecretSubType(必填):憑據子類型。取值:
      • SingleUser:指定憑據管家以單帳號模式RDS憑據。憑據輪轉時,指定帳號的口令會被重設為新的隨機口令。
      • DoubleUsers:指定憑據管家以雙帳號模式RDS憑據,ACSCurrent和ACSPrevious分別引用其中一個帳號。憑據輪轉時,ACSPrevious引用帳號的口令會被重設為新的隨機口令,隨後憑據管家交換ACSCurrent和ACSPrevious對RDS帳號的引用。
    • DBInstanceId(必填):指定RDS帳號所在的RDS執行個體ID。
    • CustomData(可選):自訂資料。取值為JSON格式的索引值對,最多不超過10個索引值對,多個索引值對用半形逗號(,)間隔。取值樣本:{"Key1": "v1", "fds":"fdsf"}。預設值為空白{}
  • 當SecretType取值為Redis(Redis憑據)時,需要指定ExtendedConfig的如下參數:
    • SecretSubType(必填):憑據子類型。取值:
      • DoubleUsers:指定憑據管家以雙帳號模式Redis憑據,ACSCurrent和ACSPrevious分別引用其中一個帳號。憑據輪轉時,ACSPrevious引用帳號的口令會被重設為新的隨機口令,隨後憑據管家交換ACSCurrent和ACSPrevious對Redis帳號的引用。
    • AccountName(必填):資料庫使用者名稱。
    • CloneAccountName(必填):資料庫使用者名稱,為AccountName加上尾碼_clone
    • AccountPrivilege(必填):訪問資料庫的許可權。
    • InstanceId(必填):Redis執行個體ID。
    • RegionId(必填):Redis執行個體所在地區ID。
    • CustomData(可選):自訂資料。取值為JSON格式的索引值對,最多不超過10個索引值對,多個索引值對用半形逗號(,)間隔。取值樣本:{"Key1": "v1", "fds":"fdsf"}。預設值為空白{}
  • 當SecretType取值為RAMCredentials(RAM憑據)時,需要指定ExtendedConfig的如下參數:
    • SecretSubType(必填):憑據子類型。取值: RamUserAccessKey。
    • UserName(必填):RAM使用者名稱稱。
    • CustomData(可選):自訂資料。取值為JSON格式的索引值對,最多不超過10個索引值對,多個索引值對用半形逗號(,)間隔。預設值為空白{}
  • 當SecretType取值為ECS(ECS憑據)時,需要指定ExtendedConfig的如下參數:
    • SecretSubType(必填):憑據子類型。取值:
      • Password:ECS口令。
      • SSHKey:ECS SSH公私密金鑰。
    • RegionId(必填):ECS執行個體所在地區ID。
    • InstanceId(必填):ECS執行個體ID。
    • CustomData(可選):自訂資料。取值為JSON格式的索引值對,最多不超過10個索引值對,多個索引值對用半形逗號(,)間隔。預設值為空白{}
  • 當SecretType取值為 PolarDB 時,需要指定ExtendedConfig的如下參數:
    • SecretSubType(必填):DoubleUsers(固定值)
    • RegionId(必填): 地區
    • DBClusterId(必填):PolarDB執行個體ID
    • DBType(必填): MySQL、PostgreSQL
    • AccountName(必填): 帳號名字
    • CloneAccountName:AccountName_clone
    • AccountType:帳號類型僅支援 Normal
    • AccountPrivilege: 僅 MySQL 可以填
    • DBName:僅MySQL可以填
    • CustomData(可選):自訂資料。取值為JSON格式的索引值對,最多不超過10個索引值對,多個索引值對用半形逗號(,)間隔。取值樣本:{"Key1": "v1", "fds":"fdsf"}。預設值為空白{}。
說明 當SecretType取值為Rds、Redis、PolarDB、RAMCredentials或ECS時,必須設定該參數。
EnableAutomaticRotation Boolean true

是否開啟自動輪轉,取值:

  • true:開啟自動輪轉。
  • false(預設值):不開啟自動輪轉。
說明 當SecretType取值為Rds(RDS憑據)、PolarDB(PolarDB憑據)、Redis(Redis憑據)、RAMCredentials(RAM憑據)或ECS(ECS憑據)時,該參數有效。當SecretType取值為Generic(通用憑據)時,不支援自動輪轉,您可通過PutSecretValue操作手工輪轉。
RotationInterval String 30d

自動輪轉的周期。取值範圍:6小時~8,760小時(365天)。

格式為integer[unit],其中integer表示時間長度,unit表示時間單位。

unit取值:d(天)、h(小時)、m(分鐘)、s(秒)。例如:7d或者604,800s均表示7天的周期。

說明 僅當EnableAutomaticRotation取值為true時,必須設定該參數,否則無需設定。
DKMSInstanceId String kst-bjj62d8f5e0sgtx8h****

KMS執行個體的執行個體ID。

Policy String {"Version":"1","Statement": [{"Sid":"kms default secret policy","Effect":"Allow","Principal":{"RAM": ["acs:ram::119285303511****:*"]},"Action":["kms:*"],"Resource": ["*"] }] }

憑據策略的具體內容,JSON格式。最大長度為32768個位元組。

關於憑據策略的詳細介紹,請參見憑據策略概述。不輸入該參數時,使用預設憑據策略。

憑據策略內容包含:

  • Version:憑據策略的版本,目前版本僅支援設定為1。
  • Statement:憑據策略的語句,每個憑據策略包含一個或多個語句。

憑據策略格式為:

{
    "Version": "1",
    "Statement": [
        {
            "Sid": "Enable RAM User Permissions",
            "Effect": "Allow",
            "Principal": {
              "RAM": ["acs:ram::12345678****:*"]
            },
            "Action": [
                "kms:*"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

Statement詳細介紹:

  • Sid:可選,表示自訂的語句標識符。內容長度小於等於128字元,支援的字元為:大寫英文字母(A-Z)、小寫英文字母(a-z)、數字(0-9),特殊字元( _/+=.@-)。
  • Effect:必選,表示是允許還是拒絕該策略語句中的許可權。取值為:Allow或Deny。
  • Principal:必選,表示權限原則的授權主體,支援設定為當前阿里雲帳號(即憑據所屬的阿里雲帳號),當前阿里雲帳號下的RAM使用者、RAM角色,其他阿里雲帳號下的RAM使用者、RAM角色。
  • Action:必選,表示要允許或拒絕的API操作,內容必須以"kms:"開頭。操作許可權列表的範圍,請參見憑據策略概述。如果您設定了列表外的操作,設定後也不會生效。
  • Resource:必選,取值只能是*,表示本KMS憑據。
  • Condition:可選,表示授權生效的限制條件。通過使用條件可以評估API請求的上下文,以確定策略語句是否適用。格式為"Condition": {"condition operator": {"condition key": "condition value"}}。詳細介紹,請參見憑據策略概述
說明 授權給其他阿里雲帳號下的RAM使用者、RAM角色後,您仍需在存取控制RAM側,使用該RAM使用者、RAM角色的阿里雲帳號為其授權使用該憑據,RAM使用者、RAM角色才能使用該憑據。集體操作,請參見Key Management Service自訂權限原則參考為RAM使用者授權為RAM角色授權

關於公用請求參數的詳情,請參見公用參數

返回資料

名稱

類型

樣本值

描述

RequestId String 3bf02f7a-015b-4f93-be0f-cc043fda2dd3

本次調用請求的ID,是由阿里雲為該請求產生的唯一識別碼,可用於排查和定位問題。

AutomaticRotation String Enabled

是否開啟自動輪轉。取值:

  • Enabled:開啟自動輪轉。
  • Disabled:不開啟自動輪轉。
  • Invalid:輪轉狀態異常,憑據管家無法為您自動輪轉。
說明 SecretType取值為Rds、Redis、PolarDB、RAMCredentials或ECS時,返回該參數。
SecretName String mydbconninfo

憑據名稱。

VersionId String v1

憑據版本號碼。

NextRotationDate String 2023-07-06T18:22:03Z

下一次輪轉的時間。

說明 當自動輪轉開啟時,返回該參數。
SecretType String Rds

憑據類型。取值:

  • Generic:通用憑據。
  • Rds:RDS憑據。
  • Redis:Redis憑據。
  • RAMCredentials:RAM憑據。
  • ECS:ECS憑據。
  • PolarDB:PolarDB憑據。
RotationInterval String 604800s

憑據自動輪轉的周期。

格式為integer[unit],其中integer表示時間長度,unit表示時間單位。 unit取值:s(秒)。例如:7天的輪轉周期為604800s。

說明 當自動輪轉開啟時,返回該參數。
Arn String acs:kms:cn-hangzhou:154035569884****:secret/mydbconninfo

阿里雲資源名稱。

ExtendedConfig String {\"SecretSubType\":\"SingleUser\", \"DBInstanceId\":\"rm-uf667446pc955****\", \"CustomData\":"Key1": "v1", "fds":"fdsf"} }

憑據的拓展配置。

說明 當SecretType取值為Rds、Redis、PolarDB、RAMCredentials或ECS時,返回該參數。
DKMSInstanceId String kst-bjj62d8f5e0sgtx8h****

KMS執行個體的執行個體ID。

樣本

請求樣本

http(s)://[Endpoint]/?Action=CreateSecret
&SecretName=mydbconninfo
&VersionId=v1
&EncryptionKeyId=key-gzz63ff0db5hg3qje****
&SecretData={"Accounts":[{"AccountName":"user1","AccountPassword":"****"}]}
&SecretDataType=text
&Description=mydbinfo
&Tags=[{\"TagKey\":\"key1\",\"TagValue\":\"val1\"},{\"TagKey\":\"key2\",\"TagValue\":\"val2\"}]
&SecretType=Rds
&EnableAutomaticRotation=true
&RotationInterval=30d
&DKMSInstanceId=kst-bjj62d8f5e0sgtx8h****
&Policy={"Version":"1","Statement": [{"Sid":"kms default secret policy","Effect":"Allow","Principal":{"RAM": ["acs:ram::119285303511****:*"]},"Action":["kms:*"],"Resource": ["*"] }] }
&公用請求參數

正常返回樣本

XML格式

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

<CreateSecretResponse>
    <RequestId>3bf02f7a-015b-4f93-be0f-cc043fda2dd3</RequestId>
    <AutomaticRotation>Enabled</AutomaticRotation>
    <SecretName>mydbconninfo</SecretName>
    <VersionId>v1</VersionId>
    <NextRotationDate>2023-07-06T18:22:03Z</NextRotationDate>
    <SecretType>Rds</SecretType>
    <RotationInterval>604800s</RotationInterval>
    <Arn>acs:kms:cn-hangzhou:154035569884****:secret/mydbconninfo</Arn>
    <ExtendedConfig>{\"SecretSubType\":\"SingleUser\", \"DBInstanceId\":\"rm-uf667446pc955****\",  \"CustomData\":"Key1": "v1", "fds":"fdsf"} }</ExtendedConfig>
    <DKMSInstanceId>kst-bjj62d8f5e0sgtx8h****</DKMSInstanceId>
</CreateSecretResponse>

JSON格式

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

{
  "RequestId" : "3bf02f7a-015b-4f93-be0f-cc043fda2dd3",
  "AutomaticRotation" : "Enabled",
  "SecretName" : "mydbconninfo",
  "VersionId" : "v1",
  "NextRotationDate" : "2023-07-06T18:22:03Z",
  "SecretType" : "Rds",
  "RotationInterval" : "604800s",
  "Arn" : "acs:kms:cn-hangzhou:154035569884****:secret/mydbconninfo",
  "ExtendedConfig" : "{\\\"SecretSubType\\\":\\\"SingleUser\\\", \\\"DBInstanceId\\\":\\\"rm-uf667446pc955****\\\",  \\\"CustomData\\\":\"Key1\": \"v1\", \"fds\":\"fdsf\"} }",
  "DKMSInstanceId" : "kst-bjj62d8f5e0sgtx8h****"
}

錯誤碼

HttpCode

錯誤碼

錯誤資訊

描述

400 UnsupportedOperation This action is not supported. 不支援的操作
400 Rejected.LimitExceeded The request was rejected because user create resource limit was exceeded 建立的資源達到上限,請求被拒絕。
400 InvalidParameter The specified parameter is not valid. 參數非法。
400 Rejected.ShareQuotaExceedLimit Instance Share Quota Exceed Limit. 執行個體份額配額超過限制。
403 Forbidden.DKMSInstanceNotFound The specified DKMS Instance is not found. 您指定的專屬kms執行個體未找到。
404 Forbidden.ResourceNotFound The resource is not found. 資源不存在。
409 Rejected.ResourceExist The resource already exists. 資源已存在。
409 Rejected.ResourceInDeleteWindow The secret is planned to be deleted. 此憑據在計劃刪除中
500 InternalFailure Internal Failure 內部錯誤

訪問錯誤中心查看更多錯誤碼。