Listing Stack Instances

Function

ListStackInstances

This API lists stack instances of a specified region or a specified member account (stack_domain_id), or all stack instances in a specified stack set.

You can use filter to find stack instances of a specified region or member account (stack_domain_id).
You can use sort_key and sort_dir as keywords to sort the returned results by creation time (create_time). The number of sort_keys must be the same as that of sort_dirs. Otherwise, error code 400 is returned. If sort_key and sort_dir are not assigned, results are sorted by creation time in descending order by default.
If no stack instance exists in the specified stack set, an empty list is returned.

URI

GET /v1/stack-sets/{stack_set_name}/stack-instances

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
stack_set_name	Yes	String	Stack set name. The name is unique within its domain (domain_id) and region. Only letters, digits, underscores (_), and hyphens (-) are allowed. The name is case-sensitive and must start with a letter.

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
stack_set_id	No	String	Unique ID of a stack set. It is a UUID generated by RFS when a stack set is created. Stack set names are unique only at one specific time, so you can create a stack set named HelloWorld and another stack set with the same name after deleting the first one. For parallel development in a team, users may want to ensure that the stack set they operate is the one created by themselves, not the one with the same name created by other teammates after deleting the previous one. Therefore, they can use this ID for strong matching. RFS ensures that the ID of each stack set is different and does not change with updates. If the stack_set_id value is different from the current stack set ID, 400 is returned.
filter	No	String	Filter condition. The AND operator is defined by commas (,). The OR operator is defined using a vertical bar (\|). The OR operator has a higher priority than the AND operator. Parentheses are not supported. The filter operator only supports the equal sign (=). The filter parameter name and value can contain only letters, digits, and underscores (_). Semicolons (;) are not allowed in filter criteria. If semicolons (;) are used, the filter criteria will be invalid. A filter parameter can be related to only one AND condition. Multiple OR conditions in an AND condition can be related to only one filter criterion.
sort_key	No	Array of strings	Sorting field. Only create_time is supported.
sort_dir	No	Array of strings	Specify an ascending or descending order. asc: ascending order desc: descending order
call_identity	No	String	This parameter is only supported when the stack set permission model is SERVICE_MANAGED. Specify whether you are acting as an account administrator in the organization's management account or as a delegated administrator in a member account. By default, SELF is specified. Use SELF for stack sets with self-managed permissions. No matter what call identity is specified, the stack set involved in request is always belonging to management account.* SELF - Invoked as the management account. DELEGATED_ADMIN - Invoked as a delegated administrator account. User account must be registered as a delegated administrator in the management account.

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
Client-Request-Id	Yes	String	Unique request ID. It is specified by a user and is used to locate a request. UUID is recommended.

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
stack_instances	Array of StackInstance objects	Stack instance list.

**Table 5** StackInstance
Parameter	Type	Description
stack_set_id	String	Unique ID of a stack set. It is a UUID generated by RFS when a stack is created. Stack set names are unique only at one specific time, so you can create a stack set named HelloWorld and another stack set with the same name after deleting the first one. For parallel development in a team, users may want to ensure that the stack set they operate is the one created by themselves, not the one with the same name created by other teammates after deleting the previous one. Therefore, they can use this ID for strong matching. RFS ensures that the ID of each stack set is different and does not change with updates. If the stack_set_id value is different from the current stack set ID, 400 is returned.
stack_set_name	String	Name of a stack set. The name is unique within its domain (domain_id) and region. Only letters, digits, underscores (_), and hyphens (-) are allowed. The name is case-sensitive and must start with a letter.
status	String	Stack instance status can be: WAIT_IN_PROGRESS: The stack instance is waiting for operation. CANCEL_COMPLETE - The stack instance operation is canceled. OPERATION_IN_PROGRESS: The stack instance operation is in progress. OPERATION_FAILED: The stack instance operation failed. INOPERABLE - The stack instance cannot be operated. OPERATION_COMPLETE: The stack instance operation is complete.
status_message	String	When the stack instance is in an INOPERABLE or OPERATION_FAILED state, brief error information is displayed for debugging.
stack_id	String	Unique stack ID. It is a UUID generated by RFS when a stack is created. Stack names are unique at one specific time, so you can create a stack named HelloWorld and another stack with the same name after deleting the first one. For parallel development in a team, users may want to ensure that the stack they operate is the one created by themselves, not the one with the same name created by other teammates after deleting the previous one. Therefore, they can use this ID for strong matching. RFS ensures that the ID of each stack is different and does not change with updates. If the stack_id value is different from the current stack ID, 400 is returned.
stack_name	String	Stack name. The name is unique within its domain (domain_id), region, and project (project_id). Only letters, digits, underscores (_), and hyphens (-) are allowed. The name is case-sensitive and must start with a letter.
stack_domain_id	String	Tenant ID of the stack associated with the stack instance.
latest_stack_set_operation_id	String	Stack set operation ID for the latest deployment of the stack instance. It is a UUID generated by RFS when a stack set operation is created.
region	String	Region of the stack associated with the stack instance.
create_time	String	Time when a stack instance is created. It uses a UTC (YYYY-MM-DDTHH:mm:ss.SSSZ) format, for example, 1970-01-01T00:00:00.000Z.
update_time	String	Time when a stack instance is updated. It uses a UTC (YYYY-MM-DDTHH:mm:ss.SSSZ) format, for example, 1970-01-01T00:00:00.000Z.

Status code: 400

**Table 6** Response body parameters
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.
encoded_authorization_message	String	The message contains information about unauthorized requests.
details	Array of Detail objects	Detailed error messages returned by service when permission is denied.

**Table 7** Detail
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.

Status code: 401

**Table 8** Response body parameters
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.
encoded_authorization_message	String	The message contains information about unauthorized requests.
details	Array of Detail objects	Detailed error messages returned by service when permission is denied.

**Table 9** Detail
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.

Status code: 403

**Table 10** Response body parameters
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.
encoded_authorization_message	String	The message contains information about unauthorized requests.
details	Array of Detail objects	Detailed error messages returned by service when permission is denied.

**Table 11** Detail
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.

Status code: 404

**Table 12** Response body parameters
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.
encoded_authorization_message	String	The message contains information about unauthorized requests.
details	Array of Detail objects	Detailed error messages returned by service when permission is denied.

**Table 13** Detail
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.

Status code: 429

**Table 14** Response body parameters
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.
encoded_authorization_message	String	The message contains information about unauthorized requests.
details	Array of Detail objects	Detailed error messages returned by service when permission is denied.

**Table 15** Detail
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.

Status code: 500

**Table 16** Response body parameters
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.
encoded_authorization_message	String	The message contains information about unauthorized requests.
details	Array of Detail objects	Detailed error messages returned by service when permission is denied.

**Table 17** Detail
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.

Example Requests

Use filter to obtain the stack instances of a specified stack set in member accounts domainA and domainB.

GET https://{endpoint}/v1/stack-sets/my_hello_world_stack_set/stack-instances?filter=stack_domain_id==stackDomainIdA|stack_domain_id==stackDomainIdB

Use sort_key and sort_dir to specify the list of stack instances to be returned. The returned instances are sorted in ascending order by creation time.
```
GET https://{endpoint}/v1/stack-sets/my_hello_world_stack_set/stack-instances?sort_key=create_time&sort_dir=asc
```

Example Responses

Status code: 200

Stack instances listed.

{
  "stack_instances" : [ {
    "stack_set_id" : "f689e9fd-97e7-4185-bd8a-7d5f708d45d7",
    "stack_set_name" : "my_hello_world_stack_set",
    "latest_stack_set_operation_id" : "3fef5d3e-27b6-44e8-9769-1d7262bd9430",
    "status" : "OPERATION_COMPLETE",
    "stack_id" : "ea6a4f0e-ee8a-494e-b12a-8be4a1e65af2",
    "stack_name" : "my_hello_world_stack",
    "stack_domain_id" : "6cbcca2a2f114a63841bdbc7a19b7b09",
    "region" : "cn-north-7",
    "create_time" : "2023-05-17T15:39:25.210Z",
    "update_time" : "2023-05-18T16:39:25.210Z"
  }, {
    "stack_set_id" : "f689e9fd-97e7-4185-bd8a-7d5f708d45d7",
    "stack_set_name" : "my_hello_world_stack_set",
    "latest_stack_set_operation_id" : "fb5e781e-a27d-46e2-9954-242753857a9f",
    "status" : "OPERATION_FAILED",
    "status_message" : "Deploy stack failed",
    "stack_id" : "4abf1770-2760-4339-9c18-427fa115db6a",
    "stack_name" : "my_hello_world_stack",
    "stack_domain_id" : "6cbcca2a2f114a63841bdbc7a19b7b12",
    "region" : "cn-north-7",
    "create_time" : "2023-05-15T15:39:25.210Z",
    "update_time" : "2023-05-16T16:39:25.210Z"
  } ]
}

Status Codes

Status Code	Description
200	Stack instances listed.
400	Invalid request.
401	Authentication failed.
403	The user does not have the permission to call this API.
404	The stack set does not exist.
429	Too frequent requests.
500	Internal server error.