使用 AWS CLI 的 cloudcontrol update-resource 更新云资源属性：JSON Patch 补丁文档实战指南

使用 AWS CLI 的 cloudcontrol update-resource 更新云资源属性JSON Patch 补丁文档实战指南【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli本文以 AWS CLI 官方示例 update-resource.rst 为核心详细讲解如何通过aws cloudcontrol update-resource命令更新现有 AWS 资源的属性。你将掌握 Cloud Control API 的更新调用方式、RFC 6902 JSON Patch 补丁文档的编写规则、异步操作进度事件ProgressEvent的解读方法以及如何结合get-resource-request-status、wait子命令与get-resource完成一次完整、可验证的资源更新流程。一、update-resource 命令的定位与适用场景AWS Cloud Control API 提供了一套统一、标准化的资源管理接口允许开发者通过一致的方式对 100 多种 AWS 服务资源进行创建、读取、更新、删除和列表CRUDL操作。它对应的 CLI 子命令组就是aws cloudcontrol本仓库中完整收录了该服务组的全部官方示例位于 awscli/examples/cloudcontrol/包括create-resource.rst创建资源get-resource.rst读取资源当前状态update-resource.rst更新资源属性本文主题delete-resource.rst删除资源list-resources.rst列举某类型资源get-resource-request-status.rst查询资源操作请求状态list-resource-requests.rst列举资源操作请求update-resource在其中的职责非常明确对已经存在的资源按需修改其一个或多个属性。与直接调用各服务专有命令如aws logs put-retention-policy不同Cloud Control API 的更新路径是统一的——你不需要记住每个服务的更新命令只需掌握「类型名 标识符 JSON Patch 补丁文档」这一套通用范式即可。二、官方示例更新 LogGroup 的保留策略以下是仓库中 update-resource.rst 的完整示例它演示了如何把名为ExampleLogGroup的AWS::Logs::LogGroup资源的保留天数更新为 90 天aws cloudcontrol update-resource \ --type-name AWS::Logs::LogGroup \ --identifier ExampleLogGroup \ --patch-document [{\op\:\replace\,\path\:\/RetentionInDays\,\value\:90}]命令返回的典型输出如下{ ProgressEvent: { EventTime: 2021-08-09T18:17:15.219Z, TypeName: AWS::Logs::LogGroup, OperationStatus: IN_PROGRESS, Operation: UPDATE, Identifier: ExampleLogGroup, RequestToken: 5f40c577-3534-4b20-9599-0b0123456789 } }从输出中可以看出几个关键事实更新操作是异步的返回时OperationStatus为IN_PROGRESS而非SUCCESS说明请求已被接收并进入执行阶段每个请求都有唯一的RequestToken它是后续查询该操作进度的凭证Operation固定为UPDATE表明这是一次更新类资源操作。三、请求参数详解根据服务模型 service-2.json 中UpdateResourceInput的定义该命令共有 6 个参数其中 3 个为必填参数必填说明--type-name是资源类型名称例如AWS::Logs::LogGroup、AWS::Kinesis::Stream--identifier是资源的标识符可以是主标识符也可以是资源 schema 中定义的任意二级标识符一次只能指定一个--patch-document是描述待应用属性变更的 JSON Patch 文档详见下一节--type-version-id否对私有资源类型指定本次操作使用的类型版本不指定时使用默认版本--role-arn否Cloud Control API 执行本次操作时所使用的 IAM 角色 ARN不指定时使用基于你 AWS 用户凭证创建的临时会话--client-token否幂等令牌用于区分请求重试与新请求令牌自使用起 36 小时内有效超过后相同令牌会被当作新请求3.1 关于 --identifier 的两种形态服务模型对Identifier给出了精确定义主标识符可以以字符串或 JSON 形式指定二级标识符必须以 JSON 形式指定。对于由多个属性拼接而成的复合主标识符若要以字符串形式指定需要按照主标识符定义中的属性顺序列出各属性值并以|分隔。在本文示例中ExampleLogGroup是AWS::Logs::LogGroup的简单主标识符直接以字符串形式传入即可。3.2 --patch-document 的底层约束模型中的PatchDocumentshapeservice-2.json明确规定了该参数的边界长度约束最少 1 个字符最多 262144 字符256K敏感字段该参数被标记为sensitive意味着在调试日志、历史记录中会被遮蔽处理。四、JSON Patch 补丁文档变更的表达语言--patch-document是本次更新的核心参数。Cloud Control API 要求其内容遵循RFC 6902JavaScript Object Notation (JSON) Patch标准——这一点在服务模型UpdateResource的文档说明中有明确交代。简而言之补丁文档是一个由若干「补丁操作」组成的 JSON 数组每个操作对象通常包含三个字段op操作类型标准定义了六种add添加、remove移除、replace替换、move移动、copy复制、test测试path指向资源属性 JSON 结构中目标位置的 JSON 指针表达式以/开头按层级逐级定位value新值replace、add、copy等操作需要提供。本文示例使用的正是最常用的replace操作[{op:replace,path:/RetentionInDays,value:90}]其含义是将资源属性中/RetentionInDays路径上的值替换为90。这里有一个容易被忽略的细节value是数值90不带引号如果写成字符串90部分资源类型可能因类型不匹配而在 handler 阶段校验失败。需要说明的是并非所有资源属性都允许更新。服务模型中的HandlerErrorCode枚举service-2.json包含了NotUpdatable错误码即「指定资源不支持该更新操作」——当补丁文档试图修改只读属性或资源类型本身不支持更新时操作将以此错误码失败。五、异步操作模型理解 ProgressEventupdate-resource返回的是一个ProgressEvent结构service-2.json它代表资源操作请求的当前状态。其字段包括字段说明TypeName本次操作涉及的资源类型Identifier资源的主标识符注意某些场景下资源操作尚未达到SUCCESS时标识符就可能已可用RequestToken唯一标识本次资源操作请求的令牌是查询进度的关键HooksRequestToken与本次请求关联的 Hooks 操作的令牌Operation资源操作类型OperationStatus操作当前状态详见下文EventTime资源操作请求发起的时间ResourceModel包含资源各属性当前值的 JSON 字符串StatusMessage解释当前状态的任意消息ErrorCode状态为FAILED时对应的错误码即HandlerErrorCodeRetryAfter建议的下一次状态查询时间5.1 Operation 与 OperationStatus 的合法取值服务模型中Operation枚举只有三个取值CREATE、DELETE、UPDATE。而OperationStatus则有六个状态构成了完整的异步生命周期状态含义PENDING资源操作尚未开始IN_PROGRESS资源操作正在执行SUCCESS资源操作已成功完成FAILED资源操作失败需查看ErrorCode与StatusMessageCANCEL_IN_PROGRESS资源操作正在被取消CANCEL_COMPLETE资源操作已被取消RequestToken的格式约束为[-A-Za-z0-9/]长度 1 到 128 个字符service-2.json。六、跟踪更新进度从轮询到自动等待由于update-resource是异步的你需要主动确认更新最终是否成功。6.1 使用 get-resource-request-status 轮询将返回的RequestToken传入 get-resource-request-status.rst 所示的命令即可查询该请求的最新状态aws cloudcontrol get-resource-request-status \ --request-token 5f40c577-3534-4b20-9599-0b0123456789当更新失败时返回内容会包含详细的错误信息。仓库示例给出了一个失败场景的典型返回其中OperationStatus为FAILEDStatusMessage明确说明失败原因ErrorCode为AlreadyExists{ ProgressEvent: { TypeName: AWS::Kinesis::Stream, Identifier: Demo, RequestToken: e1a6b86e-46bd-41ac-bfba-001234567890, Operation: CREATE, OperationStatus: FAILED, EventTime: 1632950268.481, StatusMessage: Resource of type AWS::Kinesis::Stream with identifier Demo already exists., ErrorCode: AlreadyExists } }6.2 使用 list-resource-requests 批量筛选如果你需要排查一段时间内失败的更新请求可以参考 list-resource-requests.rst 的用法通过--resource-request-status-filter按操作类型与状态筛选例如筛选所有CREATE和UPDATE中失败的请求aws cloudcontrol list-resource-requests \ --resource-request-status-filter OperationsCREATE,OperationStatusesFAILED6.3 使用 wait 子命令自动等待本仓库的 waiters-2.json 为 cloudcontrol 服务组定义了名为ResourceRequestSuccess的等待器其底层实现细节如下轮询操作GetResourceRequestStatus轮询间隔delay5 秒最大尝试次数maxAttempts24 次即最长约 2 分钟成功条件ProgressEvent.OperationStatus等于SUCCESS失败条件状态等于FAILED或CANCEL_COMPLETE。因此你可以在发起更新后直接使用等待器阻塞等待结果aws cloudcontrol wait resource-request-success \ --request-token 5f40c577-3534-4b20-9599-0b0123456789该命令会在操作达到SUCCESS时正常退出返回码 0在FAILED或CANCEL_COMPLETE时以非零退出码结束。七、更新后验证读取资源当前状态更新完成后最直接的验证方式是用 get-resource.rst 读取资源的当前属性。仓库示例展示了AWS::Kinesis::Stream的读取结果其中Properties是以 JSON 字符串形式返回的资源模型aws cloudcontrol get-resource \ --type-name AWS::Kinesis::Stream \ --identifier ResourceExample{ TypeName: AWS::Kinesis::Stream, ResourceDescription: { Identifier: ResourceExample, Properties: {\Arn\:\arn:aws:kinesis:us-west-2:099908667365:stream/ResourceExample\,\RetentionPeriodHours\:168,\Name\:\ResourceExample\,\ShardCount\:3} } }对应到 LogGroup 场景更新完成后你可以通过aws cloudcontrol get-resource --type-name AWS::Logs::LogGroup --identifier ExampleLogGroup确认RetentionInDays是否已变为 90。同理list-resources.rst 可用于列举某一类型下的全部资源aws cloudcontrol list-resources \ --type-name AWS::Kinesis::Stream八、完整实践流程与注意事项综合以上内容一次规范的资源更新操作应遵循如下流程构造补丁文档确认目标属性的 JSON 路径与合法操作类型建议replace注意数值属性不要加引号发起更新调用update-resource记录返回的RequestToken等待完成调用cloudcontrol wait resource-request-success自动轮询间隔 5 秒、最多 24 次或手动循环调用get-resource-request-status验证结果用get-resource读取资源属性确认变更生效若失败结合StatusMessage与ErrorCode定位原因。实践中有几个容易踩坑的点补丁文档大小上限 256KPatchDocument与Properties均被服务模型约束为最长 262144 字符超大属性集合需拆分处理更新后的EventTime与RetryAfter若返回RetryAfter应据此安排下一次轮询时间避免频繁请求触发限流HandlerErrorCode中的Throttling即与此相关幂等与重试网络异常导致的请求重试建议携带相同的--client-token36 小时内有效以便服务端去重NotUpdatable错误部分属性如只读属性无法通过补丁更新遇到该错误码应检查资源类型 schema 中handlers对update的支持范围敏感字段遮蔽PatchDocument被标记为sensitive在 CLI 的调试输出与历史记录中不会明文显示排查问题时可借助--debug之外的服务端返回信息。九、小结aws cloudcontrol update-resource的价值在于用「类型名 标识符 JSON Patch」的统一范式替代各服务千差万别的专有更新命令。本文结合仓库中的官方示例 update-resource.rst 与服务模型 service-2.json完整覆盖了参数语义、RFC 6902 补丁文档编写、异步ProgressEvent解读、状态跟踪与等待策略以及更新后的验证方法。掌握这套流程后你可以将同一种更新模式平滑应用到 Cloud Control API 所支持的任何资源类型上。如需深入理解各操作的错误码语义可进一步查阅服务模型中的HandlerErrorCode枚举定义。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考