為資源棧創(chuàng)建更改集,您可以在執(zhí)行更改之前查看對(duì)應(yīng)更改內(nèi)容。
接口說(shuō)明
使用場(chǎng)景
使用更改集創(chuàng)建資源棧
如果您想管理大量的云資源,并在資源棧創(chuàng)建成功之前預(yù)覽資源的創(chuàng)建效果,您可以選擇使用更改集創(chuàng)建資源棧。此時(shí)您需要將ChangeSetType
參數(shù)設(shè)置為 CREATE 并完成相關(guān)參數(shù)配置。關(guān)于更改集的更多信息,請(qǐng)參見(jiàn)更改集。
使用更改集更新資源棧
如果您想在更新資源之前預(yù)覽該操作對(duì)資源棧的影響,您可以選擇為現(xiàn)有資源棧創(chuàng)建更改集。此時(shí)您需要將 ChangeSetType 參數(shù)設(shè)置為 UPDATE 并完成相關(guān)參數(shù)配置。 關(guān)于更改集的更多信息,請(qǐng)參見(jiàn)更改集。
使用現(xiàn)有資源創(chuàng)建資源棧
如果您需要將現(xiàn)有的云資源添加到一個(gè)新的資源棧中進(jìn)行統(tǒng)一管理,您可以選擇使用更改集創(chuàng)建資源棧并完成資源導(dǎo)入。此時(shí)您需要將 ChangeSetType 參數(shù)設(shè)置為 IMPORT 并完成相關(guān)參數(shù)配置。關(guān)于資源導(dǎo)入的更多信息,請(qǐng)參見(jiàn)概覽。
將現(xiàn)有資源導(dǎo)入資源棧
如果您想要將現(xiàn)有資源導(dǎo)入到一個(gè)已有資源棧中進(jìn)行統(tǒng)一管理,您可以選擇使用更改集對(duì)已有資源棧進(jìn)行更新。此時(shí)您需要將 ChangeSetType 參數(shù)設(shè)置為 IMPORT 并完成相關(guān)參數(shù)配置。關(guān)于資源導(dǎo)入的更多信息,請(qǐng)參見(jiàn)概覽。
使用限制
- 只有部分狀態(tài)下的資源棧支持通過(guò)更改集更新。更多信息,請(qǐng)參見(jiàn)通過(guò)更改集更新資源棧。
- 一個(gè)資源棧最多同時(shí)存在 20 個(gè)更改集。
- 更改集只顯示資源棧變化,不顯示資源棧是否成功更新。
- 更改集不檢查是否將超出賬號(hào)限制、是否將更新不支持更新的資源、是否權(quán)限不足而無(wú)法修改資源,所有這些都將導(dǎo)致資源棧更新失敗。如果更新失敗,ROS 將嘗試將您的資源回滾到原始狀態(tài)。
本文以使用更改集更新資源棧為例,在杭州地域cn-hangzhou
創(chuàng)建一個(gè)名為MyChangeSet
的更改集,將 ID 為4a6c9851-3b0f-4f5f-b4ca-a14bf691****
的資源棧的模板更新為{"ROSTemplateFormatVersion":"2015-09-01"}
。
調(diào)試
您可以在OpenAPI Explorer中直接運(yùn)行該接口,免去您計(jì)算簽名的困擾。運(yùn)行成功后,OpenAPI Explorer可以自動(dòng)生成SDK代碼示例。
授權(quán)信息
下表是API對(duì)應(yīng)的授權(quán)信息,可以在RAM權(quán)限策略語(yǔ)句的Action
元素中使用,用來(lái)給RAM用戶或RAM角色授予調(diào)用此API的權(quán)限。具體說(shuō)明如下:
- 操作:是指具體的權(quán)限點(diǎn)。
- 訪問(wèn)級(jí)別:是指每個(gè)操作的訪問(wèn)級(jí)別,取值為寫(xiě)入(Write)、讀取(Read)或列出(List)。
- 資源類型:是指操作中支持授權(quán)的資源類型。具體說(shuō)明如下:
- 對(duì)于必選的資源類型,用背景高亮的方式表示。
- 對(duì)于不支持資源級(jí)授權(quán)的操作,用
全部資源
表示。
- 條件關(guān)鍵字:是指云產(chǎn)品自身定義的條件關(guān)鍵字。
- 關(guān)聯(lián)操作:是指成功執(zhí)行操作所需要的其他權(quán)限。操作者必須同時(shí)具備關(guān)聯(lián)操作的權(quán)限,操作才能成功。
操作 | 訪問(wèn)級(jí)別 | 資源類型 | 條件關(guān)鍵字 | 關(guān)聯(lián)操作 |
---|---|---|---|---|
ros:CreateChangeSet | create |
|
| 無(wú) |
請(qǐng)求參數(shù)
名稱 | 類型 | 必填 | 描述 | 示例值 |
---|---|---|---|---|
StackId | string | 否 | 創(chuàng)建更改集的資源棧的 ID。ROS 通過(guò)將此資源棧的信息與您提交的信息(例如:修改后的模板或不同的參數(shù)輸入值)進(jìn)行比較來(lái)生成更改集。 說(shuō)明
該參數(shù)僅在更改集類型為 UPDATE 或 IMPORT 時(shí)生效。
| 4a6c9851-3b0f-4f5f-b4ca-a14bf691**** |
StackPolicyURL | string | 否 | 包含資源棧策略的文件的位置。URL 必須指向位于 Web 服務(wù)器(HTTP 或 HTTPS)或阿里云 OSS 存儲(chǔ)空間(例如:oss://ros/stack-policy/demo、oss://ros/stack-policy/demo?RegionId=cn-hangzhou)的策略,策略文件長(zhǎng)為 16384 個(gè)字節(jié)。 URL 的最大長(zhǎng)度為 1350 個(gè)字節(jié)。 說(shuō)明
OSS 地域如未指定,默認(rèn)與接口參數(shù) RegionId 相同。
當(dāng)更改集類型為 CREATE 時(shí),您僅能指定 StackPolicyBody 或 StackPolicyURL 參數(shù)之一。 當(dāng)更改集類型為 UPDATE 時(shí),您僅能指定以下參數(shù)之一:
| oss://ros/stack-policy/demo |
StackPolicyBody | string | 否 | 資源棧策略的結(jié)構(gòu),長(zhǎng)度為 1~16,384 個(gè)字節(jié)。 當(dāng)更改集類型為 CREATE 時(shí),您僅能指定 StackPolicyBody 或 StackPolicyURL 其中一個(gè)參數(shù)。 當(dāng)更改集類型為 UPDATE 時(shí),您僅能指定以下參數(shù)之一:
| {"Statement":[{"Effect":"Allow","Action":"Update:*","Principal":"*","Resource":"*"}]} |
StackName | string | 否 | 創(chuàng)建更改集的資源棧的名稱。 說(shuō)明
該參數(shù)僅在更改集類型為 CREATE 或 IMPORT 時(shí)生效。
| MyStack |
UsePreviousParameters | boolean | 否 | 對(duì)于未傳遞的參數(shù),是否使用上次傳遞的值。取值:
說(shuō)明
該參數(shù)僅在更改集類型為 UPDATE 或 IMPORT 時(shí)生效。
| true |
ChangeSetType | string | 否 | 更改集的類型。取值:
當(dāng)您選擇更改集類型為 CREATE 時(shí),ROS 會(huì)為您創(chuàng)建新的資源棧。此時(shí)資源棧將處于 說(shuō)明
| UPDATE |
Description | string | 否 | 更改集的描述。最大長(zhǎng)度為 1024 個(gè)字節(jié)。 | It is a demo. |
RegionId | string | 是 | 更改集所屬的地域 ID。 您可以調(diào)用 DescribeRegions 查看最新的阿里云地域列表。 | cn-hangzhou |
ClientToken | string | 否 | 保證請(qǐng)求的冪等性。該參數(shù)值由客戶端生成,并且必須全局唯一。 | 123e4567-e89b-12d3-a456-42665544**** |
TemplateURL | string | 否 | 包含模板主體的文件的位置。URL 必須指向位于 Web 服務(wù)器(HTTP 或 HTTPS)或阿里云 OSS 存儲(chǔ)空間(例如:oss://ros/template/demo、oss://ros/template/demo?RegionId=cn-hangzhou)中的模板,模板最大值為 524,288 個(gè)字節(jié)。 說(shuō)明
如果 OSS 地域未指定,默認(rèn)與接口參數(shù) RegionId 相同。
您僅能指定 TemplateBody、TemplateURL 或 TemplateId 其中一個(gè)參數(shù)。 URL 最大長(zhǎng)度為 1024 個(gè)字節(jié)。 | oss://ros/template/demo |
StackPolicyDuringUpdateURL | string | 否 | 更新資源棧策略的文件的位置。URL 必須指向位于 Web 服務(wù)器(HTTP 或 HTTPS)或阿里云 OSS 存儲(chǔ)空間(例如:oss://ros/stack-policy/demo、oss://ros/stack-policy/demo?RegionId=cn-hangzhou)中的策略,策略文件最長(zhǎng)為 16,384 個(gè)字節(jié)。 說(shuō)明
OSS 地域如未指定,默認(rèn)與接口參數(shù) RegionId 相同。
URL 最大長(zhǎng)度為 1350 個(gè)字節(jié)。
| oss://ros/stack-policy/demo |
TemplateBody | string | 否 | 模板主體的結(jié)構(gòu)。長(zhǎng)度為 1~524,288 個(gè)字節(jié)。如果長(zhǎng)度較大,則建議通過(guò) HTTP POST+Body Param 的方式,將參數(shù)放在請(qǐng)求體中進(jìn)行傳遞,避免因 URL 過(guò)長(zhǎng)而導(dǎo)致請(qǐng)求失敗。 說(shuō)明
您必須且僅能指定 TemplateBody、TemplateURL 或 TemplateId 其中一個(gè)參數(shù)。
| {"ROSTemplateFormatVersion":"2015-09-01"} |
TimeoutInMinutes | long | 否 | 資源棧狀態(tài)變?yōu)?CREATE_FAILED 或 UPDATE_FAILED 之前可以經(jīng)過(guò)的時(shí)間量。
| 12 |
DisableRollback | boolean | 否 | 當(dāng)創(chuàng)建資源棧失敗時(shí),是否禁用回滾策略。
說(shuō)明
該參數(shù)僅在更改集類型為 CREATE 或 IMPORT 時(shí)生效。
| false |
ChangeSetName | string | 是 | 更改集的名稱。 說(shuō)明
更改集名稱在與指定資源棧關(guān)聯(lián)的所有更改集中必須是唯一的。
| MyChangeSet |
StackPolicyDuringUpdateBody | string | 否 | 臨時(shí)覆蓋資源棧策略的結(jié)構(gòu)。長(zhǎng)度為 1~16,384 個(gè)字節(jié)。
| {"Statement":[{"Effect":"Allow","Action":"Update:*","Principal":"*","Resource":"*"}]} |
RamRoleName | string | 否 | RAM 角色名稱。ROS 會(huì)扮演該角色創(chuàng)建資源棧,使用角色的憑證代表用戶進(jìn)行接口調(diào)用。 RAM 角色的更多信息,請(qǐng)參見(jiàn)資源棧角色。 | test-role |
ReplacementOption | string | 否 | 如果資源的屬性發(fā)生了變化,且變化的屬性不支持修改更新(資源物理 ID 不變),是否使用替換更新(刪除資源,重新創(chuàng)建,資源物理 ID 會(huì)發(fā)生變化)。取值:
說(shuō)明
修改更新的優(yōu)先級(jí)高于替換更新。該參數(shù)僅在更改集類型為 UPDATE 時(shí)生效。
| Disabled |
TemplateId | string | 否 | 模板 ID。支持共享模板和私有模板。 您可以通過(guò)調(diào)用ListTemplates - 查詢模板列表接口查看模板 ID。 說(shuō)明
您僅能指定 TemplateBody、TemplateURL 或 TemplateId 其中一個(gè)參數(shù)。
| 5ecd1e10-b0e9-4389-a565-e4c15efc**** |
TemplateVersion | string | 否 | 模板版本。 說(shuō)明
該參數(shù)僅在指定 TemplateId 時(shí)生效。
| v1 |
Parameters | array<object> | 否 | 模板中已定義的參數(shù)。 | |
object | 否 | |||
ParameterKey | string | 是 | 模板中已定義的參數(shù)的名稱。如果未指定特定參數(shù)的名稱和取值,則 ROS 將使用模板中指定的默認(rèn)值。N 的最大值為 200。 說(shuō)明
Parameters 為可選參數(shù)。若指定了 Parameters,則 Parameters.N.ParameterKey 為必選參數(shù)。
| Amount |
ParameterValue | string | 是 | 模板中已定義的參數(shù)的取值。N 的最大值為 200。 說(shuō)明
Parameters 為可選參數(shù)。若指定了 Parameters,則 Parameters.N.ParameterValue 為必選參數(shù)。
| 12 |
NotificationURLs | array | 否 | 接收資源棧事件的回調(diào)地址列表。 | |
string | 否 | 接收資源棧事件的回調(diào)地址。取值:
說(shuō)明
當(dāng)前支持華東 1(杭州)、華東 2(上海)、華北 2(北京)、中國(guó)(香港)、華北 3(張家口)五個(gè)地域。
N 最大值為 5。資源棧的狀態(tài)發(fā)生變化時(shí),會(huì)進(jìn)行通知。當(dāng)資源棧啟用回滾時(shí),CREATE_FAILED(創(chuàng)建失敗)和 UPDATE_FAILED(更新失敗)不會(huì)通知,而 CREATE_ROLLBACK(創(chuàng)建失敗回滾)和 ROLLBACK(更新失敗回滾)會(huì)進(jìn)行通知。IN_PROGRESS 狀態(tài)不會(huì)通知。
| http://example.com/ros-notify | |
ResourcesToImport | array<object> | 否 | 待導(dǎo)入資源列表。 | |
object | 否 | |||
ResourceIdentifier | string | 否 | 字符串到字符串的鍵值映射。取值是 JSON 格式的字符串,用來(lái)標(biāo)識(shí)要導(dǎo)入的資源。 資源的標(biāo)識(shí)符屬性可以通過(guò) GetTemplateSummary 接口獲取。 說(shuō)明
該參數(shù)僅在更改集類型為 IMPORT 時(shí)生效。ResourcesToImport 為可選參數(shù)。若指定了 ResourcesToImport,則 ResourcesToImport.N.ResourceIdentifier 為必選參數(shù)。
| {"VpcId": "vpc-2zevx9ios******"} |
LogicalResourceId | string | 否 | 資源邏輯 ID,即模板中資源的名稱。 說(shuō)明
該參數(shù)僅在更改集類型為 IMPORT 時(shí)生效。ResourcesToImport 為可選參數(shù)。若指定了 ResourcesToImport,則 ResourcesToImport.N.LogicalResourceId 為必選參數(shù)。
| Vpc |
ResourceType | string | 否 | 資源的類型,需要與模板中定義的類型一致。 說(shuō)明
該參數(shù)僅在更改集類型為 IMPORT 時(shí)生效。ResourcesToImport 為可選參數(shù)。若指定了 ResourcesToImport,則 ResourcesToImport.N.ResourceType 為必選參數(shù)。
| ALIYUN::ECS::VPC |
TemplateScratchId | string | 否 | 資源場(chǎng)景 ID,即資源納管場(chǎng)景 ID。 當(dāng) ChangeSetType 取值為 IMPORT 時(shí),該參數(shù)才有效,該參數(shù)僅支持創(chuàng)建新的資源棧導(dǎo)入。 如果您想通過(guò)資源納管場(chǎng)景導(dǎo)入資源時(shí),請(qǐng)只設(shè)置該參數(shù),而不是模板相關(guān)參數(shù)。 您可以通過(guò)調(diào)用ListTemplateScratches - 查詢資源場(chǎng)景列表查看資源納管場(chǎng)景 ID。 | 4a6c9851-3b0f-4f5f-b4ca-a14bf691**** |
Parallelism | long | 否 | 資源最大并發(fā)數(shù)。默認(rèn)為空,用戶可以輸入大于等于零的整數(shù)。設(shè)置資源最大并發(fā)數(shù)后,將與資源棧進(jìn)行關(guān)聯(lián),影響資源棧的后續(xù)操作。 該參數(shù)僅在更改集類型為 CREATE 或 UPDATE 時(shí)生效,取值:
| 1 |
關(guān)于公共請(qǐng)求參數(shù)的詳情,請(qǐng)參見(jiàn)公共參數(shù)。
返回參數(shù)
示例
正常返回示例
JSON
格式
{
"ChangeSetId": "e85abe0c-6528-43fb-ae93-fdf8de22****",
"RequestId": "B288A0BE-D927-4888-B0F7-B35EF84B6E6F",
"StackId": "4a6c9851-3b0f-4f5f-b4ca-a14bf691****"
}
錯(cuò)誤碼
訪問(wèn)錯(cuò)誤中心查看更多錯(cuò)誤碼。
變更歷史
變更時(shí)間 | 變更內(nèi)容概要 | 操作 |
---|---|---|
2024-01-11 | API 內(nèi)部配置變更,不影響調(diào)用 | 查看變更詳情 |
2023-08-15 | API 內(nèi)部配置變更,不影響調(diào)用 | 查看變更詳情 |
HttpCode | 錯(cuò)誤碼 | 錯(cuò)誤信息 | 描述 |
---|---|---|---|
400 | CircularDependency | Circular Dependency Found: {reason}. | 模板包含循環(huán)引用。reason 為具體原因。 |
400 | InvalidSchema | {reason}. | 模板格式不正確。reason 為具體原因。 |
400 | InvalidTemplateAttribute | The Referenced Attribute ({resource} {name}) is incorrect. | 模板包含不正確的資源屬性(輸出)引用。resource 為資源名,name 為屬性名。 |
400 | InvalidTemplatePropertyType | The specified value type of ({resource} {section}) is incorrect. | 模板資源定義中的字段類型不正確。resource 為資源名,section 為字段名。 |
400 | InvalidTemplateReference | The specified reference "{name}" (in {referencer}) is incorrect. | 模板包含不正確的引用。name 為引用名,referencer 為引用者。 |
400 | InvalidTemplateSection | The template section is invalid: {section}. | 模板包含無(wú)效的字段。section 為字段名。 |
400 | InvalidTemplateVersion | The template version is invalid: {reason}. | 模板版本不正確。reason 為具體原因。 |
400 | StackPolicyValidationFailed | Action denied by stack policy: {reason}. | 未通過(guò)資源棧策略校驗(yàn)。reason 為具體原因。 |
400 | StackValidationFailed | {reason}. | 資源棧校驗(yàn)失敗。reason 為具體原因。 |
400 | UnknownUserParameter | The Parameter ({name}) was not defined in template. | 傳遞的參數(shù)在模板中未定義。name 為參數(shù)名。 |
400 | UserParameterMissing | The Parameter {name} was not provided. | 參數(shù)在模板中已定義,但未傳遞值。name 為參數(shù)名。 |
404 | StackNotFound | The Stack ({name}) could not be found. | 資源棧不存在。name 為資源棧名稱或 ID。 |
409 | ActionInProgress | Stack {name} already has an action ({action}) in progress. | 資源棧在變更中。name 為資源棧名稱或 ID,action 為具體的變更操作。 |
409 | ChangeSetExists | The ChangeSet ({name}) of Stack ({stack}) already exists. | 同名更改集已存在。name 為更改集名,stack 為關(guān)聯(lián)的資源棧名稱或 ID。 |
409 | StackExists | The Stack ({name}) already exists. | 同名資源棧已存在。name 為資源棧名稱。 |
404 | TemplateNotFound | The Tempalte ({ ID }) could not be found. | 模板不存在。ID 為模板 ID。 |
404 | TemplateNotFound | The Template { ID } with version { version } could not be found. | 模板或指定版本不存在。ID 為模板 ID,version 為模板版本。 |