PreviewStack - - 阿里雲

Previews the information about a stack that you want to create based on a specified template. You can use this operation to verify the resources in the template.

This topic provides an example on how to create a stack named MyStack in the China (Hangzhou) region and preview the information about the stack. In this example, the template body of the stack is {"ROSTemplateFormatVersion":"2015-09-01"}.

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	PreviewStack	The operation that you want to perform. Set the value to PreviewStack.
DisableRollback	Boolean	No	false	Specifies whether to disable rollback for the resources when the stack fails to be created. Default value: false. Valid values: true false
TimeoutInMinutes	Long	No	60	The timeout period that is allowed to create the stack. Unit: minutes. Default value: 60.
TemplateBody	String	No	{"ROSTemplateFormatVersion":"2015-09-01"}	The structure of the template body. The template body must be 1 to 524,288 bytes in length. If the length of the template body exceeds the upper limit, we recommend that you add parameters to the HTTP POST request body to prevent request failures caused by excessively long URLs. Note You must specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, and TemplateScratchId.
StackPolicyURL	String	No	oss://ros-stack-policy/demo	The URL of the file that contains the stack policy. The URL must point to a policy that is located on an HTTP or HTTPS web server or in an Object Storage Service (OSS) bucket, such as oss://ros/stack-policy/demo or oss://ros/stack-policy/demo?RegionId=cn-hangzhou. The policy file can be up to 16,384 bytes in length. If you do not specify the region ID of the OSS bucket, the value of the RegionId parameter is used. Note You can specify only one of the StackPolicyBody and StackPolicyURL parameters. The URL can be up to 1,350 bytes in length.
RegionId	String	Yes	cn-hangzhou	The region ID of the stack. You can call the DescribeRegions operation to query the most recent region list.
StackPolicyBody	String	No	{"Statement": [{"Action": "Update:", "Resource": "", "Effect": "Allow", "Principal": "*"}]}	The structure that contains the stack policy body. The stack policy body must be 1 to 16,384 bytes in length. Note You can specify only one of the StackPolicyBody and StackPolicyURL parameters.
StackName	String	No	MyStack	The name of the stack. You can use this parameter to preview the stack that you want to create. The name can be up to 255 characters in length, and can contain digits, letters, hyphens (-), and underscores (_). The name must start with a digit or letter. Note You must specify only one of the StackName and StackId parameters.
ClientToken	String	No	123e4567-e89b-12d3-a456-42665544****	The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but you must make sure that the token is unique among different requests. The token can be up to 64 characters in length, and can contain letters, digits, hyphens (-), and underscores (_). For more information, see Ensure idempotence.
TemplateURL	String	No	oss://ros-template/demo	The URL of the file that contains the template body. The URL must point to a template that is located on an HTTP or HTTPS web server or in an OSS bucket, such as oss://ros/stack-policy/demo or oss://ros/stack-policy/demo?RegionId=cn-hangzhou. The template body can be up to 524,288 bytes in length. If you do not specify the region ID of the OSS bucket, the value of the RegionId parameter is used. Note You must specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, and TemplateScratchId.
TemplateId	String	No	5ecd1e10-b0e9-4389-a565-e4c15efc****	The ID of the template. This parameter applies to shared templates and private templates. Note You must specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, and TemplateScratchId.
TemplateVersion	String	No	v1	The version of the template. This parameter takes effect only when the TemplateId parameter is specified.
Parameters.N.ParameterKey	String	Yes	ALIYUN::AccountId	The name of parameter N. If you do not specify the name and value of a parameter, Resource Orchestration Service (ROS) uses the default name and value that are specified in the template. Maximum value of N: 200. Note If you specify Parameters, you must specify Parameters.N.ParameterKey.
Parameters.N.ParameterValue	String	Yes	151266687691****	The value of parameter N. Maximum value of N: 200. Note If you specify Parameters, you must specify Parameters.N.ParameterValue.
Parallelism	Long	No	1	The maximum number of concurrent operations that can be performed on resources. This parameter takes effect only for Terraform stacks. By default, this parameter is empty. You can set this parameter to an integer that is greater than or equal to 0. Note If you set this parameter to an integer that is greater than 0, the integer is used. If you set this parameter to 0 or leave it empty, the default value of Terraform is used. In most cases, the default value of Terraform is 10.
TemplateScratchId	String	No	ts-aa9c62feab844a6b****	The ID of the scenario. For more information about how to query the IDs of scenarios, see ListTemplateScratches. Note You must specify only one of the following parameters: TemplateBody, TemplateURL, TemplateId, and TemplateScratchId.
TemplateScratchRegionId	String	No	cn-hangzhou	The region ID of the scenario. The default value is the same as the value of the RegionId parameter. You can call the DescribeRegions operation to query the most recent region list.
StackId	String	No	4a6c9851-3b0f-4f5f-b4ca-a14bf691****	The ID of the stack. You can use this parameter to preview a stack that you want to update. Note You must specify only one of the StackName and StackId parameters. In the scenario in which you preview a stack that you want to create or update, you cannot preview the resources in its nested stacks.
EnablePreConfig	Boolean	No	false	Specifies whether to query the parameters that want to use in compliance precheck. Default value: false. Valid values: true false

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

Response parameters


Parameter	Type	Example	Description
RequestId	String	B288A0BE-D927-4888-B0F7-B35EF84B6E6F	The ID of the request.
Stack	Object		The information about the stack that is previewed.
TemplateDescription	String	One ECS instance.	The description of the template.
Parameters	Array of Parameter		The parameters of the stack.
ParameterKey	String	ALIYUN::AccountId	The name of the parameter.
ParameterValue	String	151266687691****	The value of the parameter.
Description	String	One ECS instance.	The description of the stack.
DisableRollback	Boolean	false	Indicates whether rollback is disabled for the resources when the stack fails to be created.
StackName	String	MyStack	The name of the stack.
TimeoutInMinutes	Integer	60	The timeout period that is allowed to create the stack. Unit: minutes.
StackPolicyBody	Map		The structure that contains the stack policy body.
Resources	Array of Resource		The resources in the stack.
LogicalResourceId	String	WebServer	The logical ID of the resource.
AcsResourceType	String	ACS::ECS::Instance	The type of the resource that belongs to an Alibaba Cloud service.
ResourceType	String	ALIYUN::ECS::Instance	The type of the resource.
Description	String	ECS instance.	The description of the resource.
Stack	Map		The information about the nested stack. The data structure of the value is the same as the data structure of the entire response.
RequiredBy	Array of String	["Resource1", "Resource2"]	The resources on which the stack depends.
Properties	Map		The properties of the resource.
Action	String	Add	The action that is performed on resources. Valid values: Add Modify Remove None
Replacement	String	False	Indicates whether a replacement update is performed on the template. Valid values: True: A replacement update is performed on the template. False: A change is made on the template. Conditional: A replacement update may be performed on the template. You can check whether a replacement update is performed when the template is in use. Note This parameter is returned only if the Action parameter is set to Modify.
PhysicalResourceId	String	i-a1b2c3***	The physical ID of the resource. This parameter is returned only if the Action parameter is set to Modify or Remove.
RegionId	String	cn-hangzhou	The region ID of the stack.
Log	Object		The log that is generated when the stack is run.
TerraformLogs	Array of TerraformLog		The log that is generated when a Terraform stack is run. This parameter is returned only if the stack is a Terraform stack. Note You can use this parameter to preview the logs of a Terraform stack.
Command	String	apply	The name of the Terraform command. Valid values: apply plan destroy version For more information about Terraform commands, see Basic CLI Features.
Stream	String	stdout	The output stream. Valid values: stdout: standard output stream stderr: standard error stream
Content	String	Apply complete! Resources: 42 added, 0 changed, 0 destroyed.	The content of the output stream that is returned after the command is run.

Examples

Sample requests

http(s)://ros.aliyuncs.com/?Action=PreviewStack
&TemplateBody={"ROSTemplateFormatVersion":"2015-09-01"}
&StackName=MyStack
&RegionId=cn-hangzhou
&<Common request parameters>

Sample success responses

XML format

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

<PreviewStackResponse>
    <RequestId>B288A0BE-D927-4888-B0F7-B35EF84B6E6F</RequestId>
    <Stack>
        <TemplateDescription>One ECS instance.</TemplateDescription>
        <Parameters>
            <ParameterKey>ALIYUN::AccountId</ParameterKey>
            <ParameterValue>151266687691****</ParameterValue>
        </Parameters>
        <Description>One ECS instance.</Description>
        <DisableRollback>false</DisableRollback>
        <StackName>MyStack</StackName>
        <TimeoutInMinutes>60</TimeoutInMinutes>
        <Resources>
            <LogicalResourceId>WebServer</LogicalResourceId>
            <AcsResourceType>ACS::ECS::Instance</AcsResourceType>
            <ResourceType>ALIYUN::ECS::Instance</ResourceType>
            <Description>ECS instance.</Description>
            <RequiredBy>["Resource1", "Resource2"]</RequiredBy>
            <Action>Add</Action>
            <Replacement>False</Replacement>
        </Resources>
        <RegionId>cn-hangzhou</RegionId>
        <Log>
            <TerraformLogs>
                <Command>apply</Command>
                <Stream>stdout</Stream>
                <Content>Apply complete! Resources: 42 added, 0 changed, 0 destroyed.</Content>
            </TerraformLogs>
        </Log>
    </Stack>
</PreviewStackResponse>

JSON format

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

{
  "RequestId" : "B288A0BE-D927-4888-B0F7-B35EF84B6E6F",
  "Stack" : {
    "TemplateDescription" : "One ECS instance.",
    "Parameters" : {
      "ParameterKey" : "ALIYUN::AccountId",
      "ParameterValue" : "151266687691****"
    },
    "Description" : "One ECS instance.",
    "DisableRollback" : false,
    "StackName" : "MyStack",
    "TimeoutInMinutes" : 60,
    "Resources" : {
      "LogicalResourceId" : "WebServer",
      "AcsResourceType" : "ACS::ECS::Instance",
      "ResourceType" : "ALIYUN::ECS::Instance",
      "Description" : "ECS instance.",
      "RequiredBy" : "[\"Resource1\", \"Resource2\"]",
      "Action" : "Add",
      "Replacement" : "False"
    },
    "RegionId" : "cn-hangzhou",
    "Log" : {
      "TerraformLogs" : {
        "Command" : "apply",
        "Stream" : "stdout",
        "Content" : "Apply complete! Resources: 42 added, 0 changed, 0 destroyed."
      }
    }
  }
}

Error codes

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

For more information about errors common to all operations, see Common error codes.


HTTP status code	Error code	Error message	Description
400	CircularDependency	Circular Dependency Found: {reason}.	The error message returned because the template contains a circular dependency. reason indicates the cause of the error.
400	InvalidSchema	{reason}.	The error message returned because the template format is invalid. reason indicates the cause of the error.
400	InvalidTemplateAttribute	The Referenced Attribute ({resource} {name}) is incorrect.	The error message returned because the resource property that is referenced in the Outputs section of the template is invalid. resource indicates the resource name. name indicates the property name.
400	InvalidTemplatePropertyType	The specified value type of ({resource} {section}) is incorrect.	The error message returned because the type of the resource property that is defined in a section of the template is invalid. resource indicates the resource name. section indicates the section name.
400	InvalidTemplateReference	The specified reference "{name}" (in {referencer}) is incorrect.	The error message returned because the template contains an invalid reference. name indicates the reference name. referencer indicates the referencer name.
400	InvalidTemplateSection	The template section is invalid: {section}.	The error message returned because the template contains an invalid section. section indicates the section name.
400	InvalidTemplateVersion	The template version is invalid: {reason}.	The error message returned because the template version is invalid. reason indicates the cause of the error.
400	StackValidationFailed	{reason}.	The error message returned because the stack failed to be validated. reason indicates the cause of the error.
400	UnknownUserParameter	The Parameter ({name}) was not defined in template.	The error message returned because the specified parameter is not defined in the template. name indicates the parameter name.
400	UserParameterMissing	The Parameter {name} was not provided.	The error message returned because no value is specified for the parameter that is defined in the template. name indicates the parameter name.
409	StackExists	The Stack ({name}) already exists.	The error message returned because a stack that has the same name already exists. name indicates the stack name.
404	TemplateNotFound	The Template ({ ID }) could not be found.	The error message returned because the template does not exist. ID indicates the template ID.
404	TemplateNotFound	The Template { ID } with version { version } could not be found.	The error message returned because the template or template version does not exist. ID indicates the template ID. version indicates the template version.