尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

AWS CLI 云控制 API get-resource 实战指南:读取任意资源当前状态

AWS CLI 云控制 API get-resource 实战指南:读取任意资源当前状态 AWS CLI 云控制 API get-resource 实战指南读取任意资源当前状态【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli导读aws cloudcontrol get-resource是 AWS Command Line InterfaceAWS CLI中 Cloud Control API 的读取类命令用于返回账户与区域中指定资源的当前状态快照。通过统一的--type-name--identifier参数组合它能让开发者用同一套命令语法读取 Kinesis、S3、EC2 等各类 AWS 资源的最新属性——无论该资源是否由 Cloud Control API 创建。读完本文你将掌握get-resource的完整参数语义、输出结构、与create-resource/list-resources的联动用法以及从服务模型源码确认的底层行为与异常处理机制。一、命令定位Cloud Control API 的统一读接口Cloud Control API 的核心价值在于它不再为每项 AWS 服务单独维护一套 API 约定而是用一套标准化动作CreateResource、ReadResource、UpdateResource、DeleteResource、ListResources统一管理资源生命周期。在 AWS CLI 中这些动作被映射为cloudcontrol命令族的六个子命令见仓库 awscli/examples/cloudcontrol 目录下的示例文档CLI 子命令对应 API 动作典型用途create-resourceCreateResource创建资源get-resourceGetResource读取资源当前状态本文主题list-resourcesListResources列出指定类型的所有资源update-resourceUpdateResource更新资源属性delete-resourceDeleteResource删除资源get-resource-request-statusGetResourceRequestStatus查询资源操作请求进度其中get-resource负责读这一环节。根据服务模型 awscli/botocore/data/cloudcontrol/2021-09-30/service-2.json 中GetResource操作的定义其功能为Returns information about the current state of the specified resource. You can use this action to return information about an existing resource in your account and Amazon Web Services Region, whether those resources were provisioned using Cloud Control API.这段描述有两个关键点其一读取的是资源的当前状态其二无论资源是否由 Cloud Control API 创建只要该资源类型存在对应的资源类型定义Resource Type就能被读取。这意味着get-resource天然兼容账户内既有资源是统一审计、巡检与自动化编排中获取事实状态的可靠手段。二、命令语法与参数详解get-resource的最小调用形式只需两个必填参数aws cloudcontrol get-resource \ --type-name 资源类型名 \ --identifier 资源标识符2.1 完整参数表依据服务模型 GetResourceInput 的定义GetResource的输入包含以下成员参数必填说明--type-name是资源类型名称例如AWS::Kinesis::Stream、AWS::S3::Bucket。名称遵循 CloudFormation 资源类型格式组织::服务::类型。--identifier是资源标识符。可指定主标识符Primary Identifier或资源模式中定义的任意次标识符Secondary Identifier一次只能指定一个。--type-version-id否私有资源类型的版本 ID。若不指定CloudFormation 使用默认版本对公共资源类型通常无需填写。--role-arn否执行本次资源操作时 Cloud Control API 使用的 IAM 角色 ARN。角色必须具备资源类型模式中handlers段声明的权限不指定时Cloud Control API 会基于你的 AWS 用户凭证创建临时会话。值得注意的参数细节均来自服务模型注释原文--identifier的两种形态主标识符可以以字符串或 JSON 形式指定而次标识符必须使用 JSON 形式。复合主标识符当主标识符由多个资源属性拼接而成时若以字符串形式指定需按照主标识符定义中的属性顺序列出属性值并以|竖线分隔。--role-arn的格式约束模型对 RoleArn 定义了长度区间最短 20、最长 2048与正则模式arn:.:iam::[0-9]{12}:role/.即必须是标准的 IAM 角色 ARN。2.2 最小示例来自仓库示例文档 awscli/examples/cloudcontrol/get-resource.rst 的原始示例读取名为ResourceExample的AWS::Kinesis::Stream资源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} } }对照模型 GetResourceOutput 与 ResourceDescription输出由两个层级构成3.1 顶层字段字段类型含义TypeNamestring本次查询的资源类型名称原样回显请求参数ResourceDescriptionobject资源描述对象包含Identifier与Properties两个字段3.2 ResourceDescription 对象Identifier资源的主标识符字符串。在本例中即 Kinesis 流名称ResourceExample与请求参数一致。Properties资源属性及其当前值的序列化字符串本质是一个 JSON 字符串需要二次解析才能拿到结构化属性。在本例中解包后得到{ Arn: arn:aws:kinesis:us-west-2:099908667365:stream/ResourceExample, RetentionPeriodHours: 168, Name: ResourceExample, ShardCount: 3 }这与创建该流时传入的期望状态高度一致创建时设置了RetentionPeriodHours168、ShardCount3见 create-resource.rst同时服务端补全了只读的系统字段Arn。这一行为验证了get-resource的核心价值返回的是资源的真实当前状态包含服务端自动生成/衍生的属性而非创建请求的简单回显。3.3 在脚本中解析 Properties由于Properties是字符串Shell 脚本中常配合jq使用。例如提取流的 ARNaws cloudcontrol get-resource \ --type-name AWS::Kinesis::Stream \ --identifier ResourceExample \ --query ResourceDescription.Properties \ --output text | jq -r .Arn若不想依赖jq也可直接用--query结合from_json函数解析aws cloudcontrol get-resource \ --type-name AWS::Kinesis::Stream \ --identifier ResourceExample \ --query ResourceDescription.Properties | from_json().ShardCount \ --output text四、源码级原理GetResource 在 AWS CLI 中的定义AWS CLI 的每个子命令都由awscli/botocore/data目录下的服务模型驱动。Cloud Control API 的服务模型位于 awscli/botocore/data/cloudcontrol/2021-09-30/service-2.jsonAPI 版本2021-09-30。其中GetResource操作定义了几个值得留意的实现事实4.1 底层协议形态GetResource: { name: GetResource, http: { method: POST, requestUri: / }, input: {shape: GetResourceInput}, output: {shape: GetResourceOutput}, errors: [ ... 17 种异常 ... ] }也就是说虽然 CLI 层面表现为查询但GetResource在 HTTP 层面是一个POST / 请求请求与响应体均为 JSON。这是 Cloud Control API 所有操作的统一协议设计与 RESTful 的 GET 语义无关。4.2 完整的异常清单模型为GetResource声明了 17 种异常形状其中与读操作最相关的包括异常形状触发场景据模型注释ResourceNotFoundException指定标识符的资源找不到TypeNotFoundException指定的资源类型不存在InvalidRequestException请求参数不合法如标识符格式错误ThrottlingException请求被限流NotUpdatableException资源不支持更新读操作中亦可能抛出InvalidCredentialsException凭证无效HandlerInternalFailureException/HandlerFailureException资源类型 handler 执行失败ServiceInternalErrorException/GeneralServiceException服务端内部错误NetworkFailureException网络失败PrivateTypeException尝试以公共方式访问私有类型AlreadyExistsException、ServiceLimitExceededException、ResourceConflictException、NotStabilizedException、UnsupportedActionException其他资源级/操作级异常对排障的启示当get-resource报错时应优先核对--type-name拼写对应TypeNotFoundException与--identifier是否准确对应ResourceNotFoundException再考虑 IAM 权限与限流问题。4.3 与读取类操作的只读定位GetResource的操作注释特别强调其只读性无论资源如何被创建都能读取。同时模型允许GetResource通过RoleArn指定专门的执行角色这为只读巡检角色的精细化授权提供了支撑——你可以为查询任务单独配置一个仅含cloudcontrol:GetResource权限的 IAM 角色避免使用高权限凭证。五、实战组合创建 → 追踪 → 读取 → 列表5.1 与 create-resource 配套创建后验证实际状态Cloud Control API 的create-resource是异步的立即返回的只是ProgressEvent状态为IN_PROGRESS见 create-resource.rstaws cloudcontrol create-resource \ --type-name AWS::Kinesis::Stream \ --desired-state {\Name\: \ResourceExample\,\RetentionPeriodHours\:168, \ShardCount\:3}输出中的RequestToken如20999d87-e304-4725-ad84-832dcbfd7fc5可用于轮询进度。待创建完成后get-resource就成为验证实际状态是否符合预期的标准手段——正如第四节所述它能返回服务端补全的Arn等派生字段这是create-resource的响应中不包含的。5.2 与 get-resource-request-status 配套异步任务的完整闭环若创建或更新操作尚未完成可先查询请求状态见 get-resource-request-status.rstaws cloudcontrol get-resource-request-status \ --request-token e1a6b86e-46bd-41ac-bfba-001234567890其输出中的ProgressEvent.OperationStatus可取PENDING、IN_PROGRESS、SUCCESS、FAILED、CANCEL_IN_PROGRESS、CANCEL_COMPLETE等状态见模型 ResourceRequestStatusFilter 中的枚举说明。典型编排流程为create-resource发起创建得到RequestToken循环调用get-resource-request-status直到OperationStatus为SUCCESS或FAILED成功后调用get-resource读取完整属性用于后续配置下发或状态登记失败时从StatusMessage/ErrorCode中获取失败原因例如ErrorCode: AlreadyExists。5.3 与 list-resources 配套批量巡检若需要批量读取可先用list-resources获取同类型所有资源的标识符见 list-resources.rstaws cloudcontrol list-resources \ --type-name AWS::Kinesis::Stream{ TypeName: AWS::Kinesis::Stream, ResourceDescriptions: [ {Identifier: MyKinesisStream, Properties: {\Name\:\MyKinesisStream\}}, {Identifier: AnotherStream, Properties: {\Name\:\AnotherStream\}} ] }再对列表中的每个Identifier分别调用get-resource获取全量属性。需要说明的是list-resources的Properties可能只包含部分属性上述示例中仅含Name而get-resource返回的是完整当前状态因此先 list 后 get是获取全量属性的推荐路径。同时分页器模型 paginators-1.json 表明list-resources支持NextToken/MaxResults分页参数可用 AWS CLI 自带的--max-items与--page-size配合分页遍历。5.4 复合标识符的实战写法对于主标识符由多个属性构成的资源类型--identifier需按定义顺序拼接并以|分隔。例如某资源类型主标识符由VpcId与SubnetId组成可写为aws cloudcontrol get-resource \ --type-name 某组织::某服务::复合标识资源 \ --identifier vpc-0abc123def4567890|subnet-0123456789abcdef0若使用次标识符则必须传入 JSON例如aws cloudcontrol get-resource \ --type-name 某组织::某服务::某资源 \ --identifier {TagKey:Environment}六、常见错误排查速查表现象大概率原因处理建议ResourceNotFoundException--identifier与资源实际标识符不一致或资源已删除用list-resources核对标识符确认资源存在TypeNotFoundException--type-name拼写错误或该类型未注册核对类型名格式组织::服务::类型与大小写InvalidRequestException复合标识符未按顺序/未用|分隔次标识符未用 JSON按第四节 5.4 的规则重写--identifierInvalidCredentialsException凭证过期或无权调用cloudcontrol:GetResource检查 IAM 权限策略与凭证有效期ThrottlingException请求过于频繁增加重试间隔或采用指数退避HandlerFailureException资源类型的 handler 执行异常资源侧问题等待后重试或检查资源类型提供方七、小结aws cloudcontrol get-resource以--type-name--identifier两个必填参数提供了一条读取任意受支持 AWS 资源当前真实状态的统一路径其返回的ResourceDescription.Properties是包含服务端派生字段的完整 JSON 字符串可直接用于自动化校验与编排。结合 awscli/examples/cloudcontrol 目录下的create-resource、get-resource-request-status、list-resources示例以及服务模型 service-2.json 中关于参数约束、17 种异常与协议形态的权威定义开发者可以在脚本中构建出创建—追踪—读取—列表的完整资源生命周期闭环。进一步实践建议在只读巡检场景中为get-resource单独配置最小权限 IAM 角色并通过--role-arn传入批量场景遵循list 定位标识符 → get 获取全量属性的两段式策略编写脚本时优先用--queryfrom_json解析Properties字符串避免对字符串做脆弱的正则提取。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表