本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 更新元件組態
元件組態是定義每個元件參數的 JSON 物件。每個元件的配方都會定義其預設組態，當您將元件部署到核心裝置時，會對其進行修改。
建立部署時，您可以指定要套用至每個元件的*組態更新*。組態更新是修補程式操作，這表示更新會修改核心裝置上存在的元件組態。如果核心裝置沒有 元件，則組態更新會修改並套用該部署的預設組態。
組態更新會定義*重設*更新和*合併*更新。重設更新會定義要重設為其預設值或移除的組態值。合併更新會定義要為元件設定的新組態值。部署組態更新時， AWS IoT Greengrass 核心軟體會在合併更新之前執行重設更新。
元件可以驗證您部署的組態更新。當部署變更其組態時，元件會訂閱以接收通知，而且可以拒絕不支援的組態。如需詳細資訊，請參閱[與元件組態互動](ipc-component-configuration.md)。
**Topics**
+ [重設更新](#reset-configuration-update)
+ [合併更新](#merge-configuration-update)
+ [範例](#configuration-update-example)
## 重設更新
重設更新會定義要重設為核心裝置上的預設值的組態值。如果組態值沒有預設值，則重設更新會從元件的組態中移除該值。這可協助您修正因無效的組態而中斷的元件。
使用 JSON 指標清單來定義要重設的組態值。JSON 指標以正斜線 開頭`/`。若要識別巢狀元件組態中的值，請使用正斜線 (`/`) 來分隔組態中每個層級的索引鍵。如需詳細資訊，請參閱 [JSON 指標規格](https://tools.ietf.org/html/rfc6901)。
**注意**
您只能將整個清單重設為其預設值。您無法使用重設更新來重設清單中的個別元素。
若要將元件的整個組態重設為其預設值，請指定單一空字串做為重設更新。
```
"reset": [""]
```
## 合併更新
合併更新會定義要插入核心元件組態的組態值。合併更新是 AWS IoT Greengrass Core 軟體在重設重設更新中指定路徑中的值後，會合併的 JSON 物件。使用 AWS CLI 或 AWS SDKs 時，您必須將此 JSON 物件序列化為字串。
您可以合併不存在於元件預設組態中的鍵/值對。您也可以合併與具有相同索引鍵的值類型不同的索引鍵/值對。新值會取代舊值。這表示您可以變更組態物件的結構。
您可以合併 null 值和空字串、清單和物件。
**注意**
您無法將合併更新用於將 元素插入或附加至清單。您可以取代整個清單，也可以定義每個元素都有唯一索引鍵的物件。
AWS IoT Greengrass 使用 JSON 做為組態值。JSON 會指定數字類型，但不會區分整數和浮點數。因此，組態值可能會轉換為浮點數 AWS IoT Greengrass。為了確保您的元件使用正確的資料類型，建議您將數值組態值定義為字串。然後，讓您的元件將它們剖析為整數或浮點數。這可確保您的組態值在組態和核心裝置上具有相同的類型。
### 在合併更新中使用配方變數
此功能適用於 [Greengrass 核元件](greengrass-nucleus-component.md)的 v2.6.0 和更新版本。
如果您將 Greengrass 核的 [interpolateComponentConfiguration](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-interpolate-component-configuration) 組態選項設定為 `true`，您可以在合併更新中使用配方變數以外的`component_dependency_name:configuration:json_pointer`配方變數。例如，您可以在合併更新中使用`{iot:thingName}`配方變數，在元件組態值中包含核心裝置的 AWS IoT 物件名稱，例如[程序間通訊 (IPC) 授權政策](interprocess-communication.md#ipc-authorization-policies)。
## 範例
下列範例示範具有下列預設組態之儀表板元件的組態更新。此範例元件會顯示工業設備的相關資訊。
```
{
"name": null,
"mode": "REQUEST",
"network": {
"useHttps": true,
"port": {
"http": 80,
"https": 443
},
},
"tags": []
}
```
### 工業儀表板元件配方
------
#### [ JSON ]
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.IndustrialDashboard",
"ComponentVersion": "1.0.0",
"ComponentDescription": "Displays information about industrial equipment.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"name": null,
"mode": "REQUEST",
"network": {
"useHttps": true,
"port": {
"http": 80,
"https": 443
},
},
"tags": []
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"Run": "python3 -u {artifacts:path}/industrial_dashboard.py"
}
},
{
"Platform": {
"os": "windows"
},
"Lifecycle": {
"Run": "py -3 -u {artifacts:path}/industrial_dashboard.py"
}
}
]
}
```
------
#### [ YAML ]
```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.IndustrialDashboard
ComponentVersion: '1.0.0'
ComponentDescription: Displays information about industrial equipment.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
name: null
mode: REQUEST
network:
useHttps: true
port:
http: 80
https: 443
tags: []
Manifests:
- Platform:
os: linux
Lifecycle:
Run: |
python3 -u {artifacts:path}/industrial_dashboard.py
- Platform:
os: windows
Lifecycle:
Run: |
py -3 -u {artifacts:path}/industrial_dashboard.py
```
------
**Example 範例 1：合併更新**
您可以建立套用下列組態更新的部署，這會指定合併更新，但不會指定重設更新。此組態更新會通知元件在 HTTP 連接埠 8080 上顯示儀表板，其中包含來自兩個沸騰器的資料。
**要合併的組態**
```
{
"name": "Factory 2A",
"network": {
"useHttps": false,
"port": {
"http": 8080
}
},
"tags": [
"/boiler/1/temperature",
"/boiler/1/pressure",
"/boiler/2/temperature",
"/boiler/2/pressure"
]
}
```
下列命令會建立核心裝置的部署。
```
aws greengrassv2 create-deployment --cli-input-json file://dashboard-deployment.json
```
`dashboard-deployment.json` 檔案包含下列 JSON 文件。
```
{
"targetArn": "arn:aws:iot:us-west-2:123456789012:thing/MyGreengrassCore",
"deploymentName": "Deployment for MyGreengrassCore",
"components": {
"com.example.IndustrialDashboard": {
"componentVersion": "1.0.0",
"configurationUpdate": {
"merge": "{\"name\":\"Factory 2A\",\"network\":{\"useHttps\":false,\"port\":{\"http\":8080}},\"tags\":[\"/boiler/1/temperature\",\"/boiler/1/pressure\",\"/boiler/2/temperature\",\"/boiler/2/pressure\"]}"
}
}
}
}
```
下列 [Greengrass CLI](greengrass-cli-component.md) 命令會在核心裝置上建立本機部署。
```
sudo greengrass-cli deployment create \
--recipeDir recipes \
--artifactDir artifacts \
--merge "com.example.IndustrialDashboard=1.0.0" \
--update-config dashboard-configuration.json
```
`dashboard-configuration.json` 檔案包含下列 JSON 文件。
```
{
"com.example.IndustrialDashboard": {
"MERGE": {
"name": "Factory 2A",
"network": {
"useHttps": false,
"port": {
"http": 8080
}
},
"tags": [
"/boiler/1/temperature",
"/boiler/1/pressure",
"/boiler/2/temperature",
"/boiler/2/pressure"
]
}
}
}
```
在此更新之後，儀表板元件具有下列組態。
```
{
"name": "Factory 2A",
"mode": "REQUEST",
"network": {
"useHttps": false,
"port": {
"http": 8080,
"https": 443
}
},
"tags": [
"/boiler/1/temperature",
"/boiler/1/pressure",
"/boiler/2/temperature",
"/boiler/2/pressure"
]
}
```
**Example 範例 2：重設和合併更新**
然後，您可以建立套用下列組態更新的部署，指定重設更新和合併更新。這些更新指定在預設 HTTPS 連接埠上顯示儀表板，其中包含來自不同沸騰器的資料。這些更新會修改先前範例中組態更新所產生的組態。
**重設路徑**
```
[
"/network/useHttps",
"/tags"
]
```
**要合併的組態**
```
{
"tags": [
"/boiler/3/temperature",
"/boiler/3/pressure",
"/boiler/4/temperature",
"/boiler/4/pressure"
]
}
```
下列命令會建立核心裝置的部署。
```
aws greengrassv2 create-deployment --cli-input-json file://dashboard-deployment2.json
```
`dashboard-deployment2.json` 檔案包含下列 JSON 文件。
```
{
"targetArn": "arn:aws:iot:us-west-2:123456789012:thing/MyGreengrassCore",
"deploymentName": "Deployment for MyGreengrassCore",
"components": {
"com.example.IndustrialDashboard": {
"componentVersion": "1.0.0",
"configurationUpdate": {
"reset": [
"/network/useHttps",
"/tags"
],
"merge": "{\"tags\":[\"/boiler/3/temperature\",\"/boiler/3/pressure\",\"/boiler/4/temperature\",\"/boiler/4/pressure\"]}"
}
}
}
}
```
下列 [Greengrass CLI](greengrass-cli-component.md) 命令會在核心裝置上建立本機部署。
```
sudo greengrass-cli deployment create \
--recipeDir recipes \
--artifactDir artifacts \
--merge "com.example.IndustrialDashboard=1.0.0" \
--update-config dashboard-configuration2.json
```
`dashboard-configuration2.json` 檔案包含下列 JSON 文件。
```
{
"com.example.IndustrialDashboard": {
"RESET": [
"/network/useHttps",
"/tags"
],
"MERGE": {
"tags": [
"/boiler/3/temperature",
"/boiler/3/pressure",
"/boiler/4/temperature",
"/boiler/4/pressure"
]
}
}
}
```
在此更新之後，儀表板元件具有下列組態。
```
{
"name": "Factory 2A",
"mode": "REQUEST",
"network": {
"useHttps": true,
"port": {
"http": 8080,
"https": 443
}
},
"tags": [
"/boiler/3/temperature",
"/boiler/3/pressure",
"/boiler/4/temperature",
"/boiler/4/pressure",
]
}
```