CreateChangeSet - 建立更改集 - Resource Orchestration Service

為資源棧建立更改集，您可以在執行更改之前查看對應更改內容。

介面說明

使用情境

使用更改集建立資源棧

如果您想管理大量的雲資源，並在資源棧建立成功之前預覽資源的建立效果，您可以選擇使用更改集建立資源棧。此時您需要將ChangeSetType參數設定為 CREATE 並完成相關參數配置。關於更改集的更多資訊，請參見更改集。

使用更改集更新資源棧

如果您想在更新資源之前預覽該操作對資源棧的影響，您可以選擇為現有資源棧建立更改集。此時您需要將 ChangeSetType 參數設定為 UPDATE 並完成相關參數配置。關於更改集的更多資訊，請參見更改集。

使用現有資源建立資源棧

如果您需要將現有的雲資源添加到一個新的資源棧中進行統一管理，您可以選擇使用更改集建立資源棧並完成資源匯入。此時您需要將 ChangeSetType 參數設定為 IMPORT 並完成相關參數配置。關於資源匯入的更多資訊，請參見概覽。

將現有資源匯入資源棧

如果您想要將現有資源匯入到一個已有資源棧中進行統一管理，您可以選擇使用更改集對已有資源棧進行更新。此時您需要將 ChangeSetType 參數設定為 IMPORT 並完成相關參數配置。關於資源匯入的更多資訊，請參見概覽。

使用限制

只有部分狀態下的資源棧支援通過更改集更新。更多資訊，請參見通過更改集更新資源棧。
一個資源棧最多同時存在 20 個更改集。
更改集只顯示資源棧變化，不顯示資源棧是否成功更新。
更改集不檢查是否將超出帳號限制、是否將更新不支援更新的資源、是否許可權不足而無法修改資源，所有這些都將導致資源棧更新失敗。如果更新失敗，ROS 將嘗試將您的資源復原到原始狀態。

本文以使用更改集更新資源棧為例，在杭州地區cn-hangzhou建立一個名為MyChangeSet的更改集，將 ID 為4a6c9851-3b0f-4f5f-b4ca-a14bf691****的資源棧的模板更新為{"ROSTemplateFormatVersion":"2015-09-01"}。

調試

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

調試

授權資訊

下表是API對應的授權資訊，可以在RAM權限原則語句的Action元素中使用，用來給RAM使用者或RAM角色授予調用此API的許可權。具體說明如下：

操作：是指具體的許可權點。
存取層級：是指每個操作的存取層級，取值為寫入（Write）、讀取（Read）或列出（List）。
資源類型：是指操作中支援授權的資源類型。具體說明如下：
- 對於必選的資源類型，用前面加 * 表示。
- 對於不支援資源級授權的操作，用全部資源表示。
條件關鍵字：是指雲產品自身定義的條件關鍵字。
關聯操作：是指成功執行操作所需要的其他許可權。操作者必須同時具備關聯操作的許可權，操作才能成功。

操作

存取層級

資源類型

條件關鍵字

關聯操作

ros:CreateChangeSet

create

*Stack

acs:ros:{#regionId}:{#accountId}:stack/{#StackId}

Template

acs:ros:{#regionId}:{#accountId}:template/{#TemplateId}

無

請求參數

名稱	類型	必填	描述	樣本值
StackId	string	否	建立更改集的資源棧的 ID。ROS 通過將此資源棧的資訊與您提交的資訊（例如：修改後的模板或不同的參數輸入值）進行比較來產生更改集。您可以通過調用ListStacks - 查詢資源棧列表介面擷取資源棧 ID。說明該參數僅在更改集類型為 UPDATE 或 IMPORT 時生效。	4a6c9851-3b0f-4f5f-b4ca-a14bf691****
StackPolicyURL	string	否	包含資源棧策略的檔案的位置。URL 必須指向位於 Web 服務器（HTTP 或 HTTPS）或阿里雲 OSS 儲存空間（例如：oss://ros/stack-policy/demo、oss://ros/stack-policy/demo?RegionId=cn-hangzhou）的策略，策略檔案長為 16384 個位元組。 URL 的最大長度為 1350 個位元組。說明 OSS 地區如未指定，預設與介面參數 RegionId 相同。當更改集類型為 CREATE 時，您僅能指定 StackPolicyBody 或 StackPolicyURL 參數之一。當更改集類型為 UPDATE 時，您僅能指定以下參數之一： StackPolicyBody StackPolicyURL StackPolicyDuringUpdateBody StackPolicyDuringUpdateURL	oss://ros/stack-policy/demo
StackPolicyBody	string	否	資源棧策略的結構，長度為 1~16,384 個位元組。當更改集類型為 CREATE 時，您僅能指定 StackPolicyBody 或 StackPolicyURL 其中一個參數。當更改集類型為 UPDATE 時，您僅能指定以下參數之一： StackPolicyBody StackPolicyURL StackPolicyDuringUpdateBody StackPolicyDuringUpdateURL	{"Statement":[{"Effect":"Allow","Action":"Update:","Principal":"","Resource":"*"}]}
StackName	string	否	建立更改集的資源棧的名稱。長度不超過 255 個字元。必須以數字或英文字母開頭，可包含數字、英文字母、短劃線（-）和底線（_）。說明該參數僅在更改集類型為 CREATE 或 IMPORT 時生效。	MyStack
UsePreviousParameters	boolean	否	對於未傳遞的參數，是否使用上次傳遞的值。取值： true false（預設值）說明該參數僅在更改集類型為 UPDATE 或 IMPORT 時生效。	true
ChangeSetType	string	否	更改集的類型。取值： CREATE：為新資源棧建立更改集。 UPDATE（預設值）：為現有資源棧建立更改集。 IMPORT：為新資源棧或現有資源棧建立更改集匯入非 ROS 託管資源。當您選擇更改集類型為 CREATE 時，ROS 會為您建立新的資源棧。此時資源棧將處於`REVIEW_IN_PROGRESS`狀態，直到您執行更改集。說明禁止使用 UPDATE 類型為新資源棧建立更改集，或使用 CREATE 類型為現有資源棧建立更改集。 IMPORT 類型的更改集不支援設定資源棧策略，請在建立或更新資源棧時設定相關參數。	UPDATE
Description	string	否	更改集的描述。最大長度為 1024 個位元組。	It is a demo.
RegionId	string	是	更改集所屬的地區 ID。您可以調用 DescribeRegions 查看最新的阿里雲地區列表。	cn-hangzhou
ClientToken	string	否	保證請求的等冪性。該參數值由用戶端產生，並且必須全域唯一。長度不超過 64 個字元。可包含英文字母、數字、短劃線（-）和底線（_）。更多詳情，請參見如何保證等冪性。	123e4567-e89b-12d3-a456-42665544****
TemplateURL	string	否	包含模板主體的檔案的位置。URL 必須指向位於 Web 服務器（HTTP 或 HTTPS）或阿里雲 OSS 儲存空間（例如：oss://ros/template/demo、oss://ros/template/demo?RegionId=cn-hangzhou）中的模板，模板最大值為 524,288 個位元組。說明如果 OSS 地區未指定，預設與介面參數 RegionId 相同。您僅能指定 TemplateBody、TemplateURL 或 TemplateId 其中一個參數。 URL 最大長度為 1024 個位元組。	oss://ros/template/demo
StackPolicyDuringUpdateURL	string	否	更新資源棧策略的檔案的位置。URL 必須指向位於 Web 服務器（HTTP 或 HTTPS）或阿里雲 OSS 儲存空間（例如：oss://ros/stack-policy/demo、oss://ros/stack-policy/demo?RegionId=cn-hangzhou）中的策略，策略檔案最長為 16,384 個位元組。說明 OSS 地區如未指定，預設與介面參數 RegionId 相同。 URL 最大長度為 1350 個位元組。如果要更新受保護的資源，請在更新期間指定臨時覆蓋資源棧策略。如果未指定資源棧策略，則將使用與資源棧關聯的當前策略。該參數僅在更改集類型為 UPDATE 時生效。您僅能指定以下參數之一： StackPolicyBody StackPolicyURL StackPolicyDuringUpdateBody StackPolicyDuringUpdateURL	oss://ros/stack-policy/demo
TemplateBody	string	否	模板主體的結構。長度為 1~524,288 個位元組。如果長度較大，則建議通過 HTTP POST+Body Param 的方式，將參數放在請求體中進行傳遞，避免因 URL 過長而導致請求失敗。說明您必須且僅能指定 TemplateBody、TemplateURL 或 TemplateId 其中一個參數。	{"ROSTemplateFormatVersion":"2015-09-01"}
TimeoutInMinutes	integer	否	資源棧狀態變為 CREATE_FAILED 或 UPDATE_FAILED 之前可以經過的時間量。當更改集類型為 CREATE 時，該參數為必選參數；當更改集類型為 UPDATE 時，該參數為選擇性參數。單位：分鐘。取值範圍：10~1440。預設值：60。	12
DisableRollback	boolean	否	當建立資源棧失敗時，是否禁用復原策略。取值： true：禁用復原，即在建立資源棧失敗時不進行復原。 false（預設值）：不禁用復原，即在建立資源棧失敗時進行復原。說明該參數僅在更改集類型為 CREATE 或 IMPORT 時生效。	false
ChangeSetName	string	是	更改集的名稱。長度不超過 255 個字元。必須以數字或英文字母開頭，可包含數字、英文字母、短劃線（-）和底線（_）。說明更改集名稱在與指定資源棧關聯的所有更改集中必須是唯一的。	MyChangeSet
StackPolicyDuringUpdateBody	string	否	臨時覆蓋資源棧策略的結構。長度為 1~16,384 個位元組。如果要更新受保護資源，請在此更新期間指定臨時覆蓋資源棧策略，如未指定，則將使用與資源棧關聯的當前策略。該參數僅在更改集類型為 UPDATE 時生效，您僅能指定以下參數之一： StackPolicyBody StackPolicyURL StackPolicyDuringUpdateBody StackPolicyDuringUpdateURL	{"Statement":[{"Effect":"Allow","Action":"Update:","Principal":"","Resource":"*"}]}
RamRoleName	string	否	RAM 角色名稱。ROS 會扮演該角色建立資源棧，使用角色的憑證代表使用者進行介面調用。 ROS 始終將此角色用於資源棧上將進行的操作。只要使用者有權在資源棧上進行操作，即使使用者無權使用角色，ROS 也會使用此角色，確保角色授予最少的許可權。如果使用者未指定該值，ROS 將使用以前與資源棧關聯的角色。如果沒有可用角色，ROS 將使用從您的使用者憑證中產生的臨時憑證。 RAM 角色名稱最大長度為 64 個位元組。 RAM 角色的更多資訊，請參見資源棧角色。	test-role
ReplacementOption	string	否	如果資源的屬性發生了變化，且變化的屬性不支援修改更新（資源物理 ID 不變），是否使用替換更新（刪除資源，重新建立，資源物理 ID 會發生變化）。取值： Enabled：允許替換更新。 Disabled（預設）：不允許替換更新。說明修改更新的優先順序高於替換更新。該參數僅在更改集類型為 UPDATE 時生效。	Disabled
TemplateId	string	否	模板 ID。支援共用模板和私人模板。您可以通過調用ListTemplates - 查詢範本列表介面查看模板 ID。說明您僅能指定 TemplateBody、TemplateURL 或 TemplateId 其中一個參數。	5ecd1e10-b0e9-4389-a565-e4c15efc****
TemplateVersion	string	否	模板版本。說明該參數僅在指定 TemplateId 時生效。	v1
Parameters	array<object>	否	模板中已定義的參數。
	object	否
ParameterKey	string	是	模板中已定義的參數的名稱。如果未指定特定參數的名稱和取值，則 ROS 將使用模板中指定的預設值。N 的最大值為 200。說明 Parameters 為選擇性參數。若指定了 Parameters，則 Parameters.N.ParameterKey 為必選參數。	Amount
ParameterValue	string	是	模板中已定義的參數的取值。N 的最大值為 200。說明 Parameters 為選擇性參數。若指定了 Parameters，則 Parameters.N.ParameterValue 為必選參數。	12
NotificationURLs	array	否	接收資源棧事件的回調地址清單。	http://my-site.com/ros-notify
	string	否	接收資源棧事件的回調地址。取值： HTTP POST URL 每個 URL 最大長度為 1024 個位元組。 eventbridge 資源棧狀態變更會通知到事件匯流排（EventBridge）服務。您可以登入事件匯流排控制台，在左側導覽列單擊事件匯流排，查看事件資訊。說明當前支援華東 1（杭州）、華東 2（上海）、華北 2（北京）、中國（香港）、華北 3（張家口）五個地區。 N 最大值為 5。資源棧的狀態發生變化時，會進行通知。當資源棧啟用復原時，CREATE_FAILED（建立失敗）和 UPDATE_FAILED（更新失敗）不會通知，而 CREATE_ROLLBACK（建立失敗復原）和 ROLLBACK（更新失敗復原）會進行通知。IN_PROGRESS 狀態不會通知。無論資源棧是否定義了 Outputs 都會進行通知。通知內容樣本如下： `{ "Outputs": [ { "Description": "No description given", "OutputKey": "InstanceId", "OutputValue": "i-xxx" } ], "StackId": "80bd6b6c-e888-4573-ae3b-93d29113****", "StackName": "test-notification-url", "Status": "CREATE_COMPLETE" }`	http://example.com/ros-notify
ResourcesToImport	array<object>	否	待匯入資源清單。
	object	否
ResourceIdentifier	string	否	字串到字串的索引值映射。取值是 JSON 格式的字串，用來標識要匯入的資源。鍵是資源的標識符屬性（例如：ALIYUN::ECS::VPC 資源的 VpcId），值是屬性的取值（例如：`vpc-2zevx9ios****`）。資源的標識符屬性可以通過 GetTemplateSummary 介面擷取。說明該參數僅在更改集類型為 IMPORT 時生效。ResourcesToImport 為選擇性參數。若指定了 ResourcesToImport，則 ResourcesToImport.N.ResourceIdentifier 為必選參數。	{"VpcId": "vpc-2zevx9ios******"}
LogicalResourceId	string	否	資源邏輯 ID，即模板中資源的名稱。說明該參數僅在更改集類型為 IMPORT 時生效。ResourcesToImport 為選擇性參數。若指定了 ResourcesToImport，則 ResourcesToImport.N.LogicalResourceId 為必選參數。	Vpc
ResourceType	string	否	資源的類型，需要與模板中定義的類型一致。說明該參數僅在更改集類型為 IMPORT 時生效。ResourcesToImport 為選擇性參數。若指定了 ResourcesToImport，則 ResourcesToImport.N.ResourceType 為必選參數。	ALIYUN::ECS::VPC
TemplateScratchId	string	否	資源情境 ID，即資源納管情境 ID。當 ChangeSetType 取值為 IMPORT 時，該參數才有效，該參數僅支援建立新的資源棧匯入。如果您想通過資源納管情境匯入資源時，請只設定該參數，而不是模板相關參數。您可以通過調用ListTemplateScratches - 查詢資源情境列表查看資源納管情境 ID。	4a6c9851-3b0f-4f5f-b4ca-a14bf691****
Parallelism	integer	否	資源最大並發數。預設為空白，使用者可以輸入大於等於零的整數。設定資源最大並發數後，將與資源棧進行關聯，影響資源棧的後續操作。該參數僅在更改集類型為 CREATE 或 UPDATE 時生效，取值：當更改集類型為 CREATE 時設定為大於零的整數：使用整數值。設定為零或者不設定：對於 ROS 類型資源棧不限制，Terraform 類型資源棧使用 Terraform 預設值（通常為 10）。當更改集類型為 UPDATE 時設定為大於零的整數：使用整數值。設定為零：對於 ROS 類型資源棧不限制，Terraform 類型資源棧使用 Terraform 預設值（通常為 10）。不設定：使用上次操作時設定的值。如果上次操作時未設定該參數，對於 ROS 類型資源棧不限制，Terraform 類型資源棧使用 Terraform 預設值（通常為 10）。	1
Tags	array<object>	否	更改集的標籤。
	object	否	更改集的標籤。
Key	string	否	資源棧的標籤鍵。 N 的取值範圍為 1~20。說明 Tags 為選擇性參數。如果需要指定 Tags，則 Tags.N.Key 必須指定。此標籤會傳遞到資源棧中每個支援標籤的資源中。更多資訊，請參見標籤傳遞。	usage
Value	string	否	資源棧的標籤值。 N 的取值範圍為 1~20。說明此標籤會傳遞到資源棧中每個支援標籤的資源中。更多資訊，請參見標籤傳遞。	test
ResourceGroupId	string	否	資源群組 ID。如果不指定該參數，更改集對應的資源棧將加入預設資源群組。關於資源群組的更多資訊，請參見什麼是資源群組。	rg-acfmxazb4ph6aiy****
TaintResources	array	否	標記為髒資源的列表。
	string	否	ROS 資源棧中，需要配置為：資源名稱，例如：my_vpc。 Terraform 資源棧中，需要配置為：資源類型+資源名稱，例如：alicloud_vpc.my_vpc	my_vpc

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

返回參數

名稱	類型	描述	樣本值
	object
ChangeSetId	string	更改集 ID。	e85abe0c-6528-43fb-ae93-fdf8de22****
RequestId	string	請求 ID。	B288A0BE-D927-4888-B0F7-B35EF84B6E6F
StackId	string	資源棧 ID。	4a6c9851-3b0f-4f5f-b4ca-a14bf691****

錯誤碼

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

變更歷史

更多資訊，參考變更詳情。