文档首页/ 资源编排服务 RFS/ API参考/ API/ 资源栈集/ 获取资源栈集操作的元数据
更新时间：2024-11-22 GMT+08:00
查看PDF
分享

获取资源栈集操作的元数据

功能介绍

获取资源栈集操作元数据（ShowStackSetOperationMetadata）

此API用于获取指定资源栈集操作的元数据，包括资源栈集操作ID、资源栈集ID、资源栈集名称、资源栈集操作状态、创建时间、更新时间、部署目标等信息。

具体信息见ShowStackSetOperationMetadataResponseBody。

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

URI

GET /v1/stack-sets/{stack_set_name}/operations/{stack_set_operation_id}/metadata

表1 路径参数

参数

是否必选

参数类型

描述

stack_set_name

是

String

资源栈集的名称。此名字在domain_id+region下应唯一，可以使用中文、大小写英文、数字、下划线、中划线。首字符需为中文或者英文，区分大小写。

stack_set_operation_id

是

String

资源栈集操作（stack_set_operation）的唯一Id。

此ID由资源编排服务在生成资源栈集操作的时候生成，为UUID。
表2 Query参数

参数

是否必选

参数类型

描述

stack_set_id

否

String

资源栈集（stack_set）的唯一ID。

此ID由资源编排服务在生成资源栈集的时候生成，为UUID。

由于资源栈集名称仅仅在同一时间下唯一，即用户允许先生成一个叫HelloWorld的资源栈集，删除，再重新创建一个同名资源栈集。

对于团队并行开发，用户可能希望确保，当前我操作的资源栈集就是我认为的那个，而不是其他队友删除后创建的同名资源栈集。因此，使用ID就可以做到强匹配。

资源编排服务保证每次创建的资源栈集所对应的ID都不相同，更新不会影响ID。如果给予的stack_set_id和当前资源栈集的ID不一致，则返回400

call_identity

否

String

仅支持资源栈集权限模式为SERVICE_MANAGED时指定该参数。用于指定用户是以组织管理账号还是成员帐户中的服务委托管理员身份调用资源栈集。默认为SELF。

  • 无论指定何种用户身份，创建或部署的资源栈集始终在组织管理账号名下。*

    • SELF - 以组织管理账号身份调用。

    • DELEGATED_ADMIN - 以服务委托管理员身份调用。用户的华为云账号必须在组织中已经被注册为”资源编排资源栈集服务“的委托管理员。

请求参数

表3 请求Header参数

参数

是否必选

参数类型

描述

Client-Request-Id

是

String

用户指定的，对于此请求的唯一ID，用于定位某个请求，推荐使用UUID

响应参数

状态码： 200

表4 响应Body参数

参数

参数类型

描述

stack_set_operation_id

String

资源栈集操作（stack_set_operation）的唯一Id。

此ID由资源编排服务在生成资源栈集操作的时候生成，为UUID。

stack_set_id

String

资源栈集（stack_set）的唯一ID。

此ID由资源编排服务在生成资源栈集的时候生成，为UUID。

由于资源栈集名仅仅在同一时间下唯一，即用户允许先生成一个叫HelloWorld的资源栈集，删除，再重新创建一个同名资源栈集。

对于团队并行开发，用户可能希望确保，当前我操作的资源栈集就是我以为的那个，而不是被其他队友删除后创建的同名资源栈集。因此，使用ID就可以做到强匹配。

资源编排服务保证每次创建的资源栈集所对应的ID都不相同，更新不会影响ID。如果给予的stack_set_id和当前资源栈集的ID不一致，则返回400

stack_set_name

String

资源栈集（stack_set）的名字。此名字在domain_id+region下应唯一，可以使用中文、大小写英文、数字、下划线、中划线。首字符需为中文或者英文，区分大小写。

status

String

资源栈集操作状态

  • QUEUE_IN_PROGRESS - 正在排队

  • OPERATION_IN_PROGRESS - 正在操作

  • OPERATION_COMPLETE - 操作完成

  • OPERATION_FAILED - 操作失败

  • STOP_IN_PROGRESS - 正在停止

  • STOP_COMPLETE - 停止完成

  • STOP_FAILED - 停止失败

status_message

String

资源栈集操作失败时会展示此次操作失败的原因，例如，资源栈实例部署或删除失败个数超过上限或资源栈集操作超时。

如果需要查看详细失败信息，可通过ListStackInstances API获取查看资源栈实例的status_message。

action

String

用户当前的操作

  • CREATE_STACK_INSTANCES - 创建资源栈实例

  • DELETE_STACK_INSTANCES - 删除资源栈实例

  • DEPLOY_STACK_SET - 部署资源栈集

  • DEPLOY_STACK_INSTANCES - 部署资源栈实例

  • UPDATE_STACK_INSTANCES - 更新资源栈实例

administration_agency_name

String

管理委托名称

资源编排服务使用该委托获取成员账号委托给管理账号的权限。该委托中必须含有iam:tokens:assume权限，用以后续获取被管理委托凭证。如果不包含，则会在新增或者部署实例时报错。

当用户定义SELF_MANAGED权限类型时，administration_agency_name和administration_agency_urn 必须有且只有一个存在。

推荐用户在使用信任委托时给予administration_agency_urn，administration_agency_name只支持接收委托名称，如果给予了信任委托名称，则会在部署模板时失败。

当用户使用SERVICE_MANAGED权限类型时，指定该参数将报错400。

创建委托及授权方式

administration_agency_urn

String

管理委托URN

资源编排服务使用该委托获取成员账号委托给管理账号的权限。该委托中必须含有sts:tokens:assume权限，用以后续获取被管理委托凭证。如果不包含，则会在新增或者部署实例时报错。

当用户定义SELF_MANAGED权限类型时，administration_agency_name和administration_agency_urn 必须有且只有一个存在。

推荐用户在使用信任委托时给予administration_agency_urn，administration_agency_name只支持接收委托名称，如果给予了信任委托名称，则会在部署模板时失败。

当用户使用SERVICE_MANAGED权限类型时，指定该参数将报错400。

managed_agency_name

String

被管理的委托名称。

资源编排服务会使用该委托获取实际部署资源所需要的权限

不同成员账号委托给管理账号的委托名称需要保持一致。暂不支持根据不同provider定义不同委托权限

当用户定义SELF_MANAGED权限类型时，必须指定该参数。当用户使用SERVICE_MANAGED权限类型时，指定该参数将报错400

创建委托及授权方式

deployment_targets

deployment_targets object

部署目标信息。

create_time

String

资源栈集操作的创建时间，格式为YYYY-MM-DDTHH:mm:ss.SSSZ，精确到毫秒，UTC时区，即，如1970-01-01T00:00:00.000Z。

update_time

String

资源栈集操作的更新时间，格式为YYYY-MM-DDTHH:mm:ss.SSSZ，精确到毫秒，UTC时区，即，如1970-01-01T00:00:00.000Z。

operation_preferences

operation_preferences object

资源栈集操作（stack_set_operation）的部署策略。该参数只在指定的单次操作中生效。

当用户不指定该参数时，默认的操作部署策略为区域（region）内资源栈实例串行部署，即每次只执行一个资源栈实例，区域（region）间随机且串行部署，执行完一个region下的全部资源栈实例后，才会选择另一个region部署，容错次数默认为0。

该参数可以在生成资源栈集操作的四个API中指定：

创建资源栈实例（CreateStackInstance），部署资源栈集（DeployStackSet），更新资源栈实例（UpdateStackInstance），删除资源栈实例（DeleteStackInstance）
表5 deployment_targets

参数

参数类型

描述

regions

Array of strings

用户指定资源栈集操作所涉及的区域。

在DeployStackSet API中，根据用户输入regions和domain_ids列表，以笛卡尔积的形式选择资源栈集中存在的资源栈实例进行部署。如果指定了没有被资源栈集所管理的region，则会报错。

domain_ids

Array of strings

当资源栈集权限模型是SELF_MANAGED时，用户指定包含本次操作涉及到的租户ID内容。

在DeployStackSet API中，如果指定该参数，根据用户输入的domain_ids列表和regions列表，以笛卡尔积的形式选择资源栈集中存在的资源栈实例进行部署。如果指定了没有被资源栈集所管理的domain_id，则会报错。

当资源栈集权限模型是SERVICE_MANAGED时，该参数需结合domain_id_filter_type使用。用于指定资源栈集操作涉及到的，从所提供的OU中指定或排除部署的租户ID信息，或除提供的OU外，还进行额外部署的租户ID信息。

domain_ids和domain_ids_uri 有且仅有一个存在。

domain_ids_uri

String

当资源栈集权限模型是SELF_MANAGED时，用户指定包含本次操作涉及到的租户ID内容文件的OBS地址。

内容格式要求每个租户ID以逗号（,）分隔，支持换行。当前仅支持csv文件，且文件的编码格式须为UTF-8。文件内容大小不超过100KB。

上传的csv文件应尽量避免Excel操作，以防出现读取内容不一致的问题。推荐使用记事本打开确认内容是否符合预期。

在DeployStackSet API中，如果指定该参数，根据用户输入的domain_ids_uri文件内容和regions列表，以笛卡尔积的形式选择资源栈集中存在的资源栈实例进行部署。如果内容包含了没有被资源栈集所管理的domain_id，则会报错。

当资源栈集权限模型是SERVICE_MANAGED时，该参数需结合domain_id_filter_type使用。链接文件内容用于指定资源栈集操作涉及到的，从所提供的OU中指定或排除部署的租户ID信息，或除提供的OU外，还进行额外部署的租户ID信息。

domain_ids和domain_ids_uri有且仅有一个存在。

organizational_unit_ids

Array of strings

组织单元（Organizational Unit，缩写OU）ID列表，仅在资源栈集权限模型是SERVICE_MANAGED时，才允许指定该参数。

用户指定的Organization组织部署的ID列表，可以是根组织（Root）ID，也可以是某些组织单元的ID。

创建资源栈实例 （CreateStackInstances）API 必须指定该参数，该API 会异步校验OU IDs 的合法性，校验有效的OU IDs 及其所有非空子OU ID 都会被资源栈集记录管理。该API允许指定没有或者已经被资源栈集管理的OU IDs。

  • 若资源栈集不自动部署，空子OU不会被资源栈集记录管理（特指子OU下无成员账号或部署排除其下所有成员账号）。*

  • 【暂不支持】若资源栈集开启自动部署，空子OU也会被资源栈集记录管理（特指子OU下无成员账号或部署排除其下所有成员账号），自动部署仅针对成员账号变动，不针对其他组织结构变化，例如新增OU等，新增OU不会自动被资源栈集管理。*

部署或删除资源栈实例（DeployStackSet、UpdateStackInstances、DeleteStackInstances） API，只允许指定已经被资源栈集管理的OU IDs。若指定了没有被资源栈集记录管理的OU IDs，则会报错。

删除资源栈实例 （DeleteStackInstances）API 必须指定该参数。

用户可以通过获取资源栈集元数据（ShowStackSetMetadata）API ，获取通过创建资源栈实例（CreateStackInstances）API 请求指定过的OU IDs。

资源栈集不仅会部署到目标 OU 中的用户，同时还会部署所有子 OU 下的用户。指定该参数后，资源栈集会根据用户输入的 OU 列表下所有的用户信息（包含子 OU 下的用户）和region列表，以笛卡尔积的形式，选择资源栈实例进行创建或部署。

资源栈集不会选择组织管理员作为部署目标，进行资源栈实例的创建或部署，即使组织管理员位于给与的组织或组织的 OU 中。

domain_id_filter_type

String

租户ID筛选类型，仅支持资源栈集权限模型是SERVICE_MANAGED时指定该参数。默认为NONE

用户可以指定不同的筛选类型，通过domain_ids或domain_ids_uri 指定或排除部署的用户信息，以增加或限制部署目标用户范围，实现不同的部署策略。

  • INTERSECTION - 从所提供的 OUs 中选择指定用户进行部署。指定该类型时，domain_ids和domain_ids_uri 有且仅能有一个存在。

  • DIFFERENCE - 从所提供的 OUs 中排除指定用户部署。指定该类型时，domain_ids和domain_ids_uri 有且仅能有一个存在。

  • UNION - 除了部署到提供的 OUs 外，还将部署到指定的账户中。用户可以通过同时指定organizational_unit_ids 和 domain_ids/domain_ids_uri 以实现在同一请求中部署整个OU和来自不同OU的特定个人账户。指定该类型时，domain_ids和domain_ids_uri 有且仅能有一个存在。创建资源栈实例（CreateStackInstances）除外，该API 不允许指定使用该类型。

  • NONE - 只部署在指定 OUs 中的所有账户。该类型下domain_ids和domain_ids_uri字段必须为空。
表6 operation_preferences

参数

参数类型

描述

region_concurrency_type

String

部署资源栈实例时区域（region）的执行策略，分为两种，SEQUENTIAL和PARALLEL，区分大小写，默认值为SEQUENTIAL

详细介绍：

  • SEQUENTIAL：顺序执行，执行完一个region下的全部资源栈实例后再去执行另一个region。默认顺序执行。

  • PARALLEL：并发执行，并发部署所有指定区域的资源栈实例。

region_order

Array of strings

区域（region）部署顺序。只有当用户指定region_concurrency_type为SEQUENTIAL时才会允许指定该参数。用户指定部署region的顺序，不允许出现资源栈集管理之外的region。

如果不指定，实际部署region顺序随机。部署顺序仅在当次部署时生效，应该包含且仅包含本次部署的所有region。

failure_tolerance_count

Long

容错次数。用户定义在每个区域（region）下，允许部署失败的资源栈实例数量。该参数取值默认为0，限定0和正整数。

如果定义region顺序执行（region_concurrency_type值为SEQUENTIAL），在某个region超过容错次数时，资源栈集会取消所有状态仍处于WAIT_IN_PROGRESS状态的实例。被取消的实例状态最终变为CANCEL_COMPLETE；

如果是region并行执行（region_concurrency_type值为PARALLEL），在某个region超过容错次数时，资源栈集只会取消该region下所有处于WAIT_IN_PROGRESS状态的实例。被取消的实例状态最终变为CANCEL_COMPLETE。

对处于OPERATION_IN_PROGRESS，或已经部署完成，即处于OPERATION_COMPLETE或者OPERATION_FAILED状态的资源栈实例，不受影响，状态不变。

failure_tolerance_count 和 failure_tolerance_percentage 仅能有一个存在。

failure_tolerance_percentage

Long

容错百分比。定义每个区域（region）下，允许部署失败的资源栈实例数占该region下所有资源栈实例数的百分比。该参数取值默认为0，限定0和正整数。

通过容错百分比*资源栈实例数，并向下取整，得到实际容错次数。

failure_tolerance_count 和 failure_tolerance_percentage 仅能有一个存在。

max_concurrent_count

Long

每个区域（region）下可同时部署资源栈实例的最大账户数。该参数取值默认为1，限定为正整数。

最大并发账户数最多比容错次数多1。如果用户指定failure_tolerance_percentage，最大并发账户数最多比 failure_tolerance_percentage * 资源栈实例数多1。保证部署在所需的容错级别停止。

max_concurrent_count 和 max_concurrent_percentage 仅能有一个存在。

max_concurrent_percentage

Long

最大并发账户百分比，每个区域（region）中可同时部署的资源栈实例的最大账户百分比。该参数取值默认为1，限定正整数。

RFS根据百分比 *（每个region下资源栈实例数）得到的值，再向下取整，得到实际最大并发账户数。如果实际最大并发账户数向下取整值为0时，则默认选择最大并发账户数为1。

通过百分比计算得到的实际最大并发账户数最多比容错次数多1。如果用户指定failure_tolerance_percentage，实际最大并发账户数最多比 failure_tolerance_percentage * 资源栈实例数多1。保证部署在所需的容错级别停止。

max_concurrent_count 和 max_concurrent_percentage 仅能有一个存在。

failure_tolerance_mode

String

资源栈集操作部署的失败容忍模式，分为两种，STRICT_FAILURE_TOLERANCE和SOFT_FAILURE_TOLERANCE，区分大小写，默认值为STRICT_FAILURE_TOLERANCE。

详细介绍：

  • STRICT_FAILURE_TOLERANCE：此选项会动态降低并发级别，以确保同region下部署失败的账户数量永远不超过 failure_tolerance_count + 1。当用户指定failure_tolerance_percentage时，确保同region下部署失败的账户数量不超过 failure_tolerance_percentage * 资源栈实例数 + 1。

  • 初始实际最大并发数为max_concurrent_count，如果用户指定的是max_concurrent_percentage，则初始实际最大并发数为 max_concurrent_percentage * 资源栈实例数，随后，实际最大并发数会根据失败次数增加而减少。

  • SOFT_FAILURE_TOLERANCE：此选项将failure_tolerance_count (failure_tolerance_percentage) 与实际并发数分离开。该参数允许资源栈集操作始终以指定的 max_concurrent_count 或 max_concurrent_percentage 操作资源栈实例。

  • 此时不保证资源栈实例失败总数小于 failure_tolerance_count + 1，如果用户指定的是failure_tolerance_percentage的值，则不保证资源栈实例失败总数小于 failure_tolerance_percentage * 资源栈实例数 + 1。

状态码： 400

表7 响应Body参数

参数

参数类型

描述

error_code

String

响应码

error_msg

String

响应消息

encoded_authorization_message

String

包含有关未经授权请求的信息。

details

Array of Detail objects

权限拒绝时服务返回的详细错误信息。
表8 Detail

参数

参数类型

描述

error_code

String

响应码

error_msg

String

响应消息

状态码： 401

表9 响应Body参数

参数

参数类型

描述

error_code

String

响应码

error_msg

String

响应消息

encoded_authorization_message

String

包含有关未经授权请求的信息。

details

Array of Detail objects

权限拒绝时服务返回的详细错误信息。
表10 Detail

参数

参数类型

描述

error_code

String

响应码

error_msg

String

响应消息

状态码： 403

表11 响应Body参数

参数

参数类型

描述

error_code

String

响应码

error_msg

String

响应消息

encoded_authorization_message

String

包含有关未经授权请求的信息。

details

Array of Detail objects

权限拒绝时服务返回的详细错误信息。
表12 Detail

参数

参数类型

描述

error_code

String

响应码

error_msg

String

响应消息

状态码： 404

表13 响应Body参数

参数

参数类型

描述

error_code

String

响应码

error_msg

String

响应消息

encoded_authorization_message

String

包含有关未经授权请求的信息。

details

Array of Detail objects

权限拒绝时服务返回的详细错误信息。
表14 Detail

参数

参数类型

描述

error_code

String

响应码

error_msg

String

响应消息

状态码： 429

表15 响应Body参数

参数

参数类型

描述

error_code

String

响应码

error_msg

String

响应消息

encoded_authorization_message

String

包含有关未经授权请求的信息。

details

Array of Detail objects

权限拒绝时服务返回的详细错误信息。
表16 Detail

参数

参数类型

描述

error_code

String

响应码

error_msg

String

响应消息

状态码： 500

表17 响应Body参数

参数

参数类型

描述

error_code

String

响应码

error_msg

String

响应消息

encoded_authorization_message

String

包含有关未经授权请求的信息。

details

Array of Detail objects

权限拒绝时服务返回的详细错误信息。
表18 Detail

参数

参数类型

描述

error_code

String

响应码

error_msg

String

响应消息

请求示例

获取资源栈集操作的元数据

GET https://{endpoint}/v1/stack-sets/{stack_set_name}/operations/{stack_set_operation_id}/metadata

响应示例

状态码： 200

获取资源栈集操作元数据成功

{
  "stack_set_operation_id" : "daa46d87-045b-4a50-a0d5-c167fc34b632",
  "stack_set_id" : "10f29827-939f-4a11-8bcc-65b051257860",
  "stack_set_name" : "my_hello_world_stack_set",
  "status" : "OPERATION_COMPLETE",
  "administration_agency_name" : "test_administration_agency_name",
  "managed_agency_name" : "test_managed_agency_name",
  "action" : "CREATE_STACK_INSTANCES",
  "deployment_targets" : {
    "domain_ids" : [ "dfda721e8ecd46088662f2dc9e97b1c6", "dfda721e8ecd46088662f2dc9e97b1c7" ],
    "regions" : "cn-north-5"
  },
  "operation_preferences" : {
    "failure_tolerance_count" : 4,
    "max_concurrent_count" : 3,
    "region_order" : [ "cn-north-5" ],
    "region_concurrency_type" : "SEQUENTIAL",
    "failure_tolerance_mode" : "STRICT_FAILURE_TOLERANCE"
  },
  "create_time" : "2023-05-15T15:39:25.210Z",
  "update_time" : "2023-05-15T16:39:25.210Z"
}

状态码

状态码

描述

200

获取资源栈集操作元数据成功

400

用户请求非法

401

用户身份认证失败

403

用户无权限调用此API

404

资源栈集不存在或资源栈集操作不存在

429

请求数量过多

500

服务器内部错误
父主题： 资源栈集

相关文档