本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用更新资源 AWS 云端控制 API
<a name="resource-operations-update"></a>

使用 `update-resource` 命令可以对现有资源进行更新。这包括最初未使用 Cloud Control API 预置的资源。

**重要**  
我们强烈建议不要使用 Cloud Control API 来更新其他服务当前管理的资源。这样做可能会导致意外结果。例如，不要使用 Cloud Control API 来更新当前属于 CloudFormation 堆栈的资源。

要更新现有资源，您必须指定资源的标识符。有关确定资源标识符的更多信息，请参阅[使用资源的主标识符](resource-identifier.md#resource-identifier-using)。

更新资源需要更改资源属性值。资源的属性在其资源类型架构中定义。这包括属性是否为必需属性、有效值和其他属性约束。有关查看资源属性定义的更多信息，请参阅[查看资源类型架构](resource-types.md#resource-types-schemas)。

## 编写补丁文档
<a name="resource-operations-update-patch"></a>

要更新资源，首先要将更新定义为 JSON 补丁文档中包含的*补丁操作*列表。此补丁文档必须符合 [https://datatracker.ietf.org/doc/html/rfc6902](https://datatracker.ietf.org/doc/html/rfc6902) 补丁中定义的标准。

每个补丁操作都会定义对特定资源属性的单一更新。需要具有以下属性：
+ `op`：操作类型。Cloud Control API 支持 RFC 6902 中定义的所有操作：`add`、`remove`、`replace`、`move`、`copy` 和 `test`。
+ `path`：相对于资源架构的 `properties` 部分的资源属性路径。

根据操作的不同，可能需要其他属性。有关具体信息，请参阅 RFC 6902。

使用 `update-resource` 命令时，可以将补丁文档内联指定为字符串，也可以指定文件位置。

以下示例将名为的[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html)资源的保留策略更新`CloudControlApiLogGroup`为 90 天。

```
$ aws cloudcontrol update-resource --type-name AWS::Logs::LogGroup \
    --identifier CloudControlApiLogGroup \
    --patch-document '[{"op":"replace","path":"RetentionInDays","value":90}]'
```

## Cloud Control API 如何更新资源
<a name="resource-operations-update-how"></a>

为了更新资源，Cloud Control API 会首先检索资源的当前状态，然后通过以下两步过程更新资源：
+ Cloud Control API 将更新请求中指定的补丁操作与资源的当前状态相结合，以在资源更新后生成所需的资源状态。系统按操作在补丁文档中出现的顺序依次应用操作。序列中的每个操作都应用于资源的当前状态；生成的资源状态将成为下一个操作的目标。

  此时，如果出现以下情况，整个更新请求将失败：
  + 请求中包含的补丁操作无效。
  + `op` 类型 `test` 的补丁操作失败。

  在这种情况下，整个更新请求将会失败，Cloud Control API 不会对资源进行任何更新。
+ 然后，Cloud Control API 会调用该资源类型的更新处理程序来更新资源。

  无论更新处理程序何时失败，*Cloud Control API 都不会将资源回滚到其之前的状态。*

例如，考虑以下为更新[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html)资源而定义的补丁文档。该文档包含两个补丁操作。第一个操作是 `test` 类型的操作，此操作检查资源的保留策略是否设置为 3653 天。如果是这样的话，资源将通过测试，Cloud Control API 会继续执行下一个操作。此操作会将当前的保留策略值替换为 180 天。如果资源的保留策略设置为 3653 天以外的其他值，则第一个 `test` 操作将失败，Cloud Control API 将永远不会运行第二个 `replace` 操作。

```
[
  {
    "op": "test",
    "path": "/RetentionInDays",
    "value":3653
  },
  {
    "op": "replace",
    "path": "/RetentionInDays",
    "value":180
  }
]
```

## 跟踪更新资源请求的进度
<a name="resource-operations-update-progress"></a>

该 `update-resource` 命令将返回一个 `ProgressEvent` 对象，您可以使用该对象跟踪资源操作请求的当前状态。有关更多信息，请参阅 [跟踪资源操作请求的进度](resource-operations-manage-requests.md#resource-operations-manage-requests-track)。