Listing Stack Sets

Function

ListStackSets

This API lists all stack sets of the current account (domain) at the current region.

You can use filter to find stack sets with a specified permission model (permission_model).
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.
Currently, all stack sets are returned. Pagination is not supported.
If there is no stack set, an empty list will be returned.

URI

GET /v1/stack-sets

**Table 1** Query Parameters
Parameter	Mandatory	Type	Description
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 2** 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 3** Response body parameters
Parameter	Type	Description
stack_sets	Array of StackSet objects	Stack sets.

**Table 4** StackSet
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.
stack_set_description	String	Description of a stack set. It can be used by customers to identify their own stack sets.
permission_model	String	Permission model. It defines the creation mode of the agency required for RFS to operate stack sets, default is SELF_MANAGED. You can use the CreateStackSet API to specify this parameter. This parameter does not support updating yet. If you want to update the permission model, you can delete and then create a stack set with the same name. * SERVICE_MANAGED: Based on the Organization service, RFS will automatically create all IAM agency required when deploying organization member accounts. You can use this model to create stack sets only after setting "Resource Formation Stack Set service" as a trusted service in your organization. Only an organization administrator or a delegated administrator can create stack sets using SERVICE_MANAGED permissions. * SELF_MANAGED: For deployment, you need to manually create agencies in advance, including the agency created by the management account for RFS and the agency created by the member account for the management account. The stack set creation will not fail if the agency does not exist or is incorrect. An error is reported only when the stack set or stack instance is deployed.
status	String	The stack set status can be: IDLE: The stack set is idle. OPERATION_IN_PROGRESS: The stack set operation is in progress. DEACTIVATED: The stack set is disabled.
create_time	String	Time when a stack set 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 set 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 5** 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 6** Detail
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.

Status code: 401

**Table 7** 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 8** Detail
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.

Status code: 403

**Table 9** 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 10** Detail
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.

Status code: 429

**Table 11** 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 12** Detail
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.

Status code: 500

**Table 13** 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 14** Detail
Parameter	Type	Description
error_code	String	Response code.
error_msg	String	Response message.

Example Requests

You can obtain all stack sets of the current account (domain) at the current region. The returned stack sets are sorted in descending order by creation time.
```
GET https://{endpoint}/v1/stack-sets
```
You can use filter to obtain the stack sets with the specified permission model SELF_MANAGED. The returned stack sets are sorted in descending order by creation time.
```
GET https://{endpoint}/v1/stack-sets?filter=permission_model==SELF_MANAGED
```
You can use sort_key and sort_dir to specify the list of stack sets to be returned. The returned stack sets are sorted in ascending order by creation time.
```
GET https://{endpoint}/v1/stack-sets?sort_key=create_time&sort_dir=asc
```

Example Responses

Status code: 200

List stack sets succeeded.

{
  "stack_sets" : [ {
    "stack_set_id" : "f689e9fd-97e7-4185-bd8a-7d5f708d45d7",
    "stack_set_name" : "my_first_stack_set",
    "stack_set_description" : "my first stack set",
    "permission_model" : "SELF_MANAGED",
    "status" : "IDLE",
    "create_time" : "2023-05-15T15:39:25.751Z",
    "update_time" : "2023-05-15T16:39:25.751Z"
  }, {
    "stack_set_id" : "b3e7e15f-f96b-4190-94f4-bb8120f8c4dc",
    "stack_set_name" : "my_second_stack_set",
    "stack_set_description" : "my second stack set",
    "permission_model" : "SELF_MANAGED",
    "status" : "OPERATION_IN_PROGRESS",
    "create_time" : "2023-05-15T14:39:25.210Z",
    "update_time" : "2023-05-15T15:39:25.233Z"
  } ]
}

Status Codes

Status Code	Description
200	List stack sets succeeded.
400	Invalid request.
401	Authentication failed.
403	The user does not have the permission to call this API.
429	Too frequent requests.
500	Internal server error.