CreateChangeSet - 创建更改集

为资源栈创建更改集,您可以在执行更改之前查看对应更改内容。

接口说明

使用场景

使用更改集创建资源栈

如果您想管理大量的云资源,并在资源栈创建成功之前预览资源的创建效果,您可以选择使用更改集创建资源栈。此时您需要将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****

错误码

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

变更历史

更多信息,参考变更详情