本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 更新資源 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 天。如果是這種情況，資源會通過測試，雲端控制 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)。