本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 將 AWS IoT Greengrass 元件部署至裝置
您可以使用 AWS IoT Greengrass 將元件部署至裝置或裝置群組。您可以使用*部署*來定義傳送至裝置的元件和組態。 會 AWS IoT Greengrass 部署到代表 Greengrass 核心裝置*的目標*、 AWS IoT 物件或物件群組。 AWS IoT Greengrass 會使用[AWS IoT Core 任務](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)來部署到您的核心裝置。您可以設定任務如何推展至您的裝置。
## 核心裝置部署
每個核心裝置都會執行該裝置部署的元件。相同目標的新部署會覆寫目標的先前部署。建立部署時，您可以定義要套用至核心裝置現有軟體的元件和組態。
當您修改目標的部署時，您可以將先前修訂版中的元件取代為新修訂版中的元件。例如，您將 [日誌管理員](log-manager-component.md)和 [秘密管理員](secret-manager-component.md)元件部署到物件群組 `TestGroup`。然後，您可以為 建立另一個部署`TestGroup`，只指定秘密管理員元件。因此，該群組中的核心裝置不再執行日誌管理員。
## 平台相依性解析
當核心裝置收到部署時，它會檢查以確保元件與核心裝置相容。例如，如果您將 部署[Firehose](kinesis-firehose-component.md)到 Windows 目標，部署將會失敗。
## 元件相依性解析
在元件部署期間，核心裝置會驗證物件群組中所有元件相依性和版本需求的相容性。此驗證可確保在繼續部署之前，所有元件及其相依性的版本限制都受到滿足。
相依性解析程序從識別其配方中沒有相依性的目標元件開始。然後，系統會使用廣度優先搜尋 (BFS) 建構相依性樹狀結構，系統性地探索每個目標節點，並在繼續下一個節點之前先尋找其相依性。每個節點都包含目標元件做為 金鑰，並將版本需求做為 值。
版本需求結合三組限制條件：
+ 已在現有物件群組中建立的版本需求。
+ 部署所需的元件版本。您必須在進行或更新部署時選取元件版本。
+ 在配方相依性區段中定義的任何元件版本限制。
### 解決元件相依性
在部署期間，Greengrass 核會先嘗試尋找目前在滿足需求的裝置上執行的本機候選項目。如果執行中的元件滿足需求，則核會從配方資料夾取得儲存的配方路徑，並在本機存放區中找到最新的本機版本。
對於 AWS 雲端 部署，核接著會呼叫 [ResolveComponentCandidates API](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_ResolveComponentCandidates.html)。此 API 將從最新的可用版本開始，並檢查是否符合相依性和要求。當核心從 API 取得回應時，它會選取該最新版本。如果找不到符合 AWS 雲端 需求的 版本，則部署會失敗。如果裝置離線，則會回到找到的原始本機候選項目。如果找不到符合需求的本機候選項目，則部署會失敗。
對於本機部署，如果存在且符合要求，則核只會使用本機候選項目，而不會進行協商 AWS 雲端。如果沒有這類候選項目，則部署會失敗。
**注意**
所有已解析的配方都會儲存在本機以供日後參考。
如需詳細資訊，請參閱 GitHub 中的[相依性解析](https://github.com/aws-greengrass/aws-greengrass-nucleus/wiki/Deployment#dependency-resolution)一節。
如果 Greengrass 核能夠成功解析所有元件，則核日誌將包含以下行。
```
resolve-all-group-dependencies-finish. Finish resolving all groups dependencies.
```
**Example**
以下是 核如何解決元件需求的範例。
+ 您可以部署ComponentAComponentC。
+ 您也可以部署取決於 ComponentC 1.4.0-1.9.5 版的 ComponentBComponentB 。
透過元件相依性解析， 核會部署最新版本的 ComponentC 版本，以滿足 ComponentA 和 ComponentB 的需求。此最新版本的 ComponentC 是 1.9.0 版。
#### 常見元件相依性解析失敗
元件相依性解析可能會因為兩個主要原因失敗：目標版本需求衝突或元件相依性需求衝突。
##### 案例 1：目標版本需求衝突
+ 物件存在於一個物件群組中，您也想要將該物件新增至新的物件群組。如果新物件群組需要不同的物件版本，則部署會失敗。
+ 如果物件屬於物件群組，且想要透過物件部署更新元件版本，則部署也可能會失敗。
![\[導致部署失敗的元件相依性。\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/images/dependency-4.png)
*失敗日誌範例：*
```
2025-04-11T06:16:03.315Z [ERROR] (pool-3-thread-27) com.aws.greengrass.componentmanager.ComponentManager: Failed to negotiate version with cloud and no local version to fall back to. {componentName=ComponentC, versionRequirement={thing/ABC==2.0.0, thinggroup/ThingGroupA==1.0.0}}
2025-04-11T06:16:03.316Z [ERROR] (pool-3-thread-26) com.aws.greengrass.deployment.DeploymentService: Error occurred while processing deployment. {deploymentId=fbac24de-4ef9-44b0-a685-fdc63b0f02b8, serviceName=DeploymentService, currentState=RUNNING}
java.util.concurrent.ExecutionException: com.aws.greengrass.componentmanager.exceptions.NoAvailableComponentVersionException: No local or cloud component version satisfies the requirements Check whether the version constraints conflict and that the component exists in your AWS account with a version that matches the version constraints. If the version constraints conflict, revise deployments to resolve the conflict. Component ComponentC version constraints: thing/ABC requires =2.0.0, thinggroup/ThingGroupA requires =1.0.0.
at java.base/java.util.concurrent.FutureTask.report(FutureTask.java:122)
at java.base/java.util.concurrent.FutureTask.get(FutureTask.java:191)
at com.aws.greengrass.deployment.DefaultDeploymentTask.call(DefaultDeploymentTask.java:127)
at com.aws.greengrass.deployment.DefaultDeploymentTask.call(DefaultDeploymentTask.java:50)
at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264)
at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
at java.base/java.lang.Thread.run(Thread.java:829)
Caused by: com.aws.greengrass.componentmanager.exceptions.NoAvailableComponentVersionException: No local or cloud component version satisfies the requirements Check whether the version constraints conflict and that the component exists in your AWS account with a version that matches the version constraints. If the version constraints conflict, revise deployments to resolve the conflict. Component ComponentC version constraints: thing/ABC requires =2.0.0, thinggroup/ThingGroupA requires =1.0.0.
at com.aws.greengrass.componentmanager.ComponentManager.negotiateVersionWithCloud(ComponentManager.java:232)
at com.aws.greengrass.componentmanager.ComponentManager.resolveComponentVersion(ComponentManager.java:167)
at com.aws.greengrass.componentmanager.DependencyResolver.lambda$resolveDependencies$0(DependencyResolver.java:134)
at com.aws.greengrass.componentmanager.DependencyResolver.resolveComponentDependencies(DependencyResolver.java:231)
at com.aws.greengrass.componentmanager.DependencyResolver.resolveDependencies(DependencyResolver.java:131)
at com.aws.greengrass.deployment.DefaultDeploymentTask.lambda$call$2(DefaultDeploymentTask.java:125)
... 4 more
```
日誌指出版本衝突錯誤，因為核心找不到同時符合兩個衝突需求的元件版本。
##### 如何解決此問題
+ 如果您想要在每個物件群組中保留元件，請在每個物件群組中選取該元件的相同版本。
+ 選取符合部署需求的元件版本。
+ 如果您想要使用不符合物件群組需求的元件版本，請選取符合物件群組版本需求的元件版本，並僅在該物件群組中使用該元件。
##### 案例 2：元件相依性版本需求衝突
如果元件是不同元件的相依性，且元件需要不同版本或該元件的不同版本範圍，則可能沒有可用的版本可滿足所有版本需求。在此案例中，部署將會失敗。
**Example**
ComponentA (v2.5.0)、 ComponentB (v1.3.0) 和 ComponentC (v1.0.0) 的部署
+ ComponentA 要求 ComponentB 版本 >=1.0.0。
```
---
...
ComponentName: ComponentA
ComponentVersion: "2.5.0"
ComponentDependencies:
ComponentB:
VersionRequirement: ">=1.0.0"
DependencyType: "HARD"
...
```
+ ComponentC 需要 ComponentA 版本 <2.0.0。
```
---
...
ComponentName: ComponentC
ComponentVersion: "1.0.0"
ComponentDependencies:
ComponentA:
VersionRequirement: "<2.0.0"
DependencyType: "HARD"
...
```
ComponentA 的兩個要求之間存在版本衝突：
+ 此部署中 ComponentA 需要 2.5.0 版
+ ComponentC 需要低於 2.0.0 的 ComponentA 版本
這兩個要求彼此矛盾，使得核心無法找到滿足這兩個要求的 ComponentA 版本。因此，相依性解析會失敗。
![\[導致部署失敗的元件相依性。\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/images/dependency-3.png)
*失敗日誌範例：*
```
2025-04-11T06:07:18.291Z [ERROR] (pool-3-thread-25) com.aws.greengrass.componentmanager.ComponentManager: Failed to negotiate version with cloud and no local version to fall back to. {componentName=ComponentA, versionRequirement={ComponentC=<2.0.0, thinggroup/ThingGroupA==2.5.0}}
2025-04-11T06:07:18.292Z [ERROR] (pool-3-thread-24) com.aws.greengrass.deployment.DeploymentService: Error occurred while processing deployment. {deploymentId=2ffac4df-1ac9-405c-8c11-28494a1b4382, serviceName=DeploymentService, currentState=RUNNING}
java.util.concurrent.ExecutionException: com.aws.greengrass.componentmanager.exceptions.NoAvailableComponentVersionException: No local or cloud component version satisfies the requirements Check whether the version constraints conflict and that the component exists in your AWS account with a version that matches the version constraints. If the version constraints conflict, revise deployments to resolve the conflict. Component ComponentA version constraints: ComponentC requires <2.0.0, thinggroup/ThingGroupA requires =2.5.0.
at java.base/java.util.concurrent.FutureTask.report(FutureTask.java:122)
at java.base/java.util.concurrent.FutureTask.get(FutureTask.java:191)
at com.aws.greengrass.deployment.DefaultDeploymentTask.call(DefaultDeploymentTask.java:127)
at com.aws.greengrass.deployment.DefaultDeploymentTask.call(DefaultDeploymentTask.java:50)
at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264)
at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
at java.base/java.lang.Thread.run(Thread.java:829)
Caused by: com.aws.greengrass.componentmanager.exceptions.NoAvailableComponentVersionException: No local or cloud component version satisfies the requirements Check whether the version constraints conflict and that the component exists in your AWS account with a version that matches the version constraints. If the version constraints conflict, revise deployments to resolve the conflict. Component ComponentA version constraints: ComponentC requires <2.0.0, thinggroup/ThingGroupA requires =2.5.0.
at com.aws.greengrass.componentmanager.ComponentManager.negotiateVersionWithCloud(ComponentManager.java:232)
at com.aws.greengrass.componentmanager.ComponentManager.resolveComponentVersion(ComponentManager.java:167)
at com.aws.greengrass.componentmanager.DependencyResolver.lambda$resolveDependencies$0(DependencyResolver.java:134)
at com.aws.greengrass.componentmanager.DependencyResolver.resolveComponentDependencies(DependencyResolver.java:231)
at com.aws.greengrass.componentmanager.DependencyResolver.resolveDependencies(DependencyResolver.java:131)
at com.aws.greengrass.deployment.DefaultDeploymentTask.lambda$call$2(DefaultDeploymentTask.java:125)
... 4 more
```
日誌指出 核找不到符合下列需求的 ComponentA 版本。
+ ComponentA 的要求完全是 2.5.0 版 （來自 ThingGroupA)。
+ 使用低於 2.0.0 的 ComponentC 版本的需求。
##### 如何解決此問題
+ 如果您想要在每個物件群組中保留元件，請在每個物件群組中選取該元件的相同版本。
+ 選取符合部署需求的元件版本。
+ 如果您想要使用不符合物件群組需求的元件版本，請選取符合物件群組版本需求的元件版本，並僅在該物件群組中使用該元件。
**提示**
如果您在任何 AWS 提供的元件上看到此錯誤，您可以透過將衝突的元件更新到最新版本來解決它。
## 從物件群組移除裝置
當您從物件群組移除核心裝置時，元件部署行為取決於核心裝置執行的 [Greengrass 核心](greengrass-nucleus-component.md)版本。
------
#### [ 2.5.1 and later ]
當您從物件群組移除核心裝置時，行為取決於 AWS IoT 政策是否授予`greengrass:ListThingGroupsForCoreDevice`許可。如需核心裝置此許可和 AWS IoT 政策的詳細資訊，請參閱 [的裝置身分驗證和授權 AWS IoT Greengrass](device-auth.md)。
+ **如果 AWS IoT 政策授予此許可**
當您從物件群組移除核心裝置時，下次對裝置進行部署時， 會 AWS IoT Greengrass 移除物件群組的元件。如果裝置的元件包含在下一次部署中，則該元件不會從裝置中移除。
+ **如果 AWS IoT 政策未授予此許可**
當您從物件群組中移除核心裝置時， AWS IoT Greengrass 不會從裝置刪除該物件群組的元件。
若要從裝置移除元件，請使用 Greengrass CLI 的[部署建立](gg-cli-deployment.md#deployment-create)命令。使用 `--remove` 引數指定要移除的元件，並使用 `--groupId`引數指定物件群組。
------
#### [ 2.5.0 ]
當您從物件群組移除核心裝置時，下次對裝置進行部署時， 會 AWS IoT Greengrass 移除物件群組的元件。如果裝置的元件包含在下一次部署中，則該元件不會從裝置中移除。
此行為需要核心裝置的 AWS IoT 政策授予 `greengrass:ListThingGroupsForCoreDevice`許可。如果核心裝置沒有此許可，則核心裝置無法套用部署。如需詳細資訊，請參閱[的裝置身分驗證和授權 AWS IoT Greengrass](device-auth.md)。
------
#### [ 2.0.x - 2.4.x ]
當您從物件群組中移除核心裝置時， AWS IoT Greengrass 不會從裝置刪除該物件群組的元件。
若要從裝置移除元件，請使用 Greengrass CLI 的[部署建立](gg-cli-deployment.md#deployment-create)命令。使用 `--remove` 引數指定要移除的元件，並使用 `--groupId`引數指定物件群組。
------
## 部署
部署是連續的。當您建立部署時， 會將部署 AWS IoT Greengrass 轉出至線上的目標裝置。如果目標裝置未上線，則下次連線時會接收部署 AWS IoT Greengrass。當您將核心裝置新增至目標物件群組時， 會將該物件群組的最新部署 AWS IoT Greengrass 傳送給裝置。
在核心裝置部署元件之前，預設會通知裝置上的每個元件。Greengrass 元件可以回應通知以延遲部署。如果裝置電池電量低或正在執行無法中斷的程序，建議您延遲部署。如需詳細資訊，請參閱[教學課程：開發可延遲元件更新的 Greengrass 元件](defer-component-updates-tutorial.md)。建立部署時，您可以將其設定為部署，而無需通知元件。
每個目標物件或物件群組一次可以有一個部署。這表示當您為目標建立部署時， AWS IoT Greengrass 不會再部署該目標部署的先前修訂版。
## 部署選項
部署提供多種選項，可讓您控制哪些裝置接收更新，以及更新如何部署。建立部署時，您可以設定下列選項：
+ **AWS IoT Greengrass 元件**
定義要在目標 device. AWS IoT Greengrass components 上安裝和執行的元件是您在 Greengrass 核心裝置上部署和執行的軟體模組。只有在元件支援裝置的平台時，裝置才會接收元件。這可讓您部署至裝置群組，即使目標裝置在多個平台上執行也一樣。如果元件不支援裝置的平台，則元件不會部署到裝置。
您可以將自訂元件和 AWS提供的元件部署至您的裝置。當您部署元件時， 會 AWS IoT Greengrass 識別任何元件相依性，也會進行部署。如需詳細資訊，請參閱[開發 AWS IoT Greengrass 元件](develop-greengrass-components.md)及[AWS提供的元件](public-components.md)。
您可以定義要為每個元件部署的版本和組態更新。*組態更新*指定如何在核心裝置上修改元件的現有組態，如果元件不存在於核心裝置上，則修改元件的預設組態。您可以指定要重設為預設值的組態值，以及要合併到核心裝置的新組態值。當核心裝置收到不同目標的部署，且每個部署指定相容的元件版本時，核心裝置會根據您建立部署時的時間戳記，依序套用組態更新。如需詳細資訊，請參閱[更新元件組態](update-component-configurations.md)。
**重要**
部署元件時， 會 AWS IoT Greengrass 安裝該元件所有相依性的最新支援版本。因此，如果您將新裝置新增至物件群組，或者您更新以這些裝置為目標的部署，則可能會自動將 AWS新修補程式版本的公有元件部署到您的核心裝置。有些自動更新，例如核更新，可能會導致您的裝置意外重新啟動。
為了防止在您裝置上執行之元件的意外更新，我們建議您[在建立部署](create-deployments.md)時直接包含該元件的偏好版本。如需 AWS IoT Greengrass Core 軟體更新行為的詳細資訊，請參閱 [更新 AWS IoT Greengrass 核心軟體 (OTA)](update-greengrass-core-v2.md)。
+ **部署政策**
定義何時可以安全地部署組態，以及部署失敗時該怎麼做。您可以指定是否等待元件報告他們可以更新。如果裝置套用失敗的部署，您也可以指定是否要將裝置復原至先前的組態。
+ **停止組態**
定義停止部署的時間和方式。如果符合您定義的條件，部署會停止並失敗。例如，您可以設定部署，在最小數量的裝置接收後，有一定百分比的裝置無法套用該部署時停止。
+ **推展組態**
定義部署推展到目標裝置的速率。您可以使用最小和最大速率邊界來設定指數速率增加。
+ **逾時組態**
定義每個裝置必須套用部署的時間上限。如果裝置超過您指定的持續時間，則裝置無法套用部署。
**重要**
自訂元件可以在 S3 儲存貯體中定義成品。 AWS IoT Greengrass 核心軟體部署元件時，會從 下載元件的成品 AWS 雲端。根據預設，核心裝置角色不允許存取 S3 儲存貯體。若要部署定義 S3 儲存貯體中成品的自訂元件，核心裝置角色必須授予從該儲存貯體下載成品的許可。如需詳細資訊，請參閱[允許存取元件成品的 S3 儲存貯體](device-service-role.md#device-service-role-access-s3-bucket)。
**Topics**
+ [核心裝置部署](#core-device-deployments)
+ [平台相依性解析](#platform-dependency-resolution)
+ [元件相依性解析](#component-dependency-resolution)
+ [從物件群組移除裝置](#thing-group-removal-behavior)
+ [部署](#deployments)
+ [部署選項](#deployment-options)
+ [建立部署](create-deployments.md)
+ [建立子部署](create-subdeployments.md)
+ [修訂部署](revise-deployments.md)
+ [取消部署](cancel-deployments.md)
+ [檢查部署狀態](check-deployment-status.md)
# 建立部署
您可以建立以物件或物件群組為目標的部署。
當您建立部署時，您可以設定要部署的軟體元件，以及部署任務如何推展到目標裝置。您可以在您提供給 的 JSON 檔案中定義部署 AWS CLI。
部署目標會決定您要在其中執行元件的裝置。若要部署到一個核心裝置，請指定物件。若要部署到多個核心裝置，請指定包含這些裝置的物件群組。如需如何設定物件群組的詳細資訊，請參閱《 *AWS IoT 開發人員指南*》中的[靜態物件群組](https://docs.aws.amazon.com/iot/latest/developerguide/thing-groups.html)和[動態物件群組](https://docs.aws.amazon.com/iot/latest/developerguide/dynamic-thing-groups.html)。
請依照本節中的步驟來建立目標的部署。如需如何更新具有部署之目標上的軟體元件的詳細資訊，請參閱[修訂部署](revise-deployments.md)。
**警告**
[CreateDeployment](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_CreateDeployment.html) 操作可以從核心裝置解除安裝元件。如果元件存在於先前的部署中，而非新的部署中，核心裝置會解除安裝該元件。為了避免解除安裝元件，請先使用 [ListDeployments](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_ListDeployments.html) 操作來檢查部署的目標是否已有現有的部署。然後，當您建立新的部署時，請使用 [GetDeployment](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_GetDeployment.html) 操作從該現有部署開始。
**建立部署 (AWS CLI)**
1. 建立名為 的檔案`deployment.json`，然後將下列 JSON 物件複製到 檔案。將 *targetArn* 取代為要用於部署之 AWS IoT 物件或物件群組的 ARN。物件和物件群組 ARNs的格式如下：
+ 物件：`arn:aws:iot:region:account-id:thing/thingName`
+ 物件群組：`arn:aws:iot:region:account-id:thinggroup/thingGroupName`
```
{
"targetArn": "targetArn"
}
```
1. 檢查部署目標是否有您要修改的現有部署。請執行下列操作：
1. 執行下列命令來列出部署目標的部署。將 *targetArn* 取代為目標 AWS IoT 物件或物件群組的 ARN。
```
aws greengrassv2 list-deployments --target-arn targetArn
```
回應包含具有目標最新部署的清單。如果回應是空的，則目標沒有現有的部署，您可以跳到 [Step 3](#create-deployment-define-name-step)。否則，`deploymentId`請從回應中複製 以用於下一個步驟。
**注意**
您也可以修訂目標最新修訂版以外的部署。指定`--history-filter ALL`引數以列出目標的所有部署。然後，複製您要修改的部署 ID。
1. 執行下列命令以取得部署的詳細資訊。這些詳細資訊包括中繼資料、元件和任務組態。將 *deploymentId* 取代為上一個步驟的 ID。
```
aws greengrassv2 get-deployment --deployment-id deploymentId
```
回應包含部署的詳細資訊。
1. 將下列任一鍵/值對從上一個命令的回應複製到 `deployment.json`。您可以變更新部署的這些值。
+ `deploymentName` – 部署的名稱。
+ `components` – 部署的元件。若要解除安裝元件，請從此物件中移除它。
+ `deploymentPolicies` – 部署的政策。
+ `iotJobConfiguration` – 部署的任務組態。
+ `tags` – 部署的標籤。
1. （選用） 定義部署的名稱。將 *deploymentName* 取代為部署的名稱。
```
{
"targetArn": "targetArn",
"deploymentName": "deploymentName"
}
```
1. 新增每個元件以部署目標裝置。若要這樣做，請將索引鍵/值對新增至`components`物件，其中索引鍵是元件名稱，而值是包含該元件詳細資訊的物件。為您新增的每個元件指定下列詳細資訊：
+ `version` – 要部署的元件版本。
+ `configurationUpdate` – 要部署的[組態更新](update-component-configurations.md)。更新是一種修補程式操作，可修改元件在每個目標裝置上的現有組態，如果元件不存在於目標裝置上，則會修改元件的預設組態。您可以指定下列組態更新：
+ 重設更新 (`reset`) – （選用） JSON 指標清單，定義要重設為目標裝置上的預設值的組態值。 AWS IoT Greengrass 核心軟體會在套用合併更新之前套用重設更新。如需詳細資訊，請參閱[重設更新](update-component-configurations.md#reset-configuration-update)。
+ 合併更新 (`merge`) – （選用） 定義要合併到目標裝置的組態值的 JSON 文件。您必須將 JSON 文件序列化為字串。如需詳細資訊，請參閱[合併更新](update-component-configurations.md#merge-configuration-update)。
+ `runWith` – （選用） AWS IoT Greengrass 核心軟體用來在核心裝置上執行此元件程序的系統程序選項。如果您省略`runWith`物件中的參數， AWS IoT Greengrass Core 軟體會使用您在 [Greengrass 核元件](greengrass-nucleus-component.md)上設定的預設值。
您可以指定下列任一選項：
+ `posixUser` – POSIX 系統使用者和選用的群組，用於在 Linux 核心裝置上執行此元件。如果指定，使用者和群組必須存在於每個 Linux 核心裝置上。以下列格式指定使用者和群組，並以冒號 (`:`) 分隔：`user:group`。群組為選用項目。如果您未指定群組，則 AWS IoT Greengrass Core 軟體會使用使用者的主要群組。如需詳細資訊，請參閱[設定執行元件的使用者](configure-greengrass-core-v2.md#configure-component-user)。
+ `windowsUser` – 用來在 Windows 核心裝置上執行此元件的 Windows 使用者。使用者必須存在於每個 Windows 核心裝置上，且其名稱和密碼必須存放在 LocalSystem 帳戶的 Credentials Manager 執行個體中。如需詳細資訊，請參閱[設定執行元件的使用者](configure-greengrass-core-v2.md#configure-component-user)。
此功能適用於 [Greengrass 核元件](greengrass-nucleus-component.md)的 v2.5.0 和更新版本。
+ `systemResourceLimits` – 要套用至此元件程序的系統資源限制。您可以將系統資源限制套用至一般和非容器 Lambda 元件。如需詳細資訊，請參閱[設定元件的系統資源限制](configure-greengrass-core-v2.md#configure-component-system-resource-limits)。
您可以指定下列任一選項：
+ `cpus` – 此元件程序可在核心裝置上使用的 CPU 時間上限。核心裝置的 CPU 總時間等於裝置的 CPU 核心數。例如，在具有 4 個 CPU 核心的核心裝置上，您可以將此值設定為 `2`，將此元件的程序限制為每個 CPU 核心的 50% 用量。在具有 1 個 CPU 核心的裝置上，您可以將此值設定為 `0.25`，以將此元件的程序限制為 CPU 的 25% 用量。如果您將此值設定為大於 CPU 核心數量的數字，則 AWS IoT Greengrass Core 軟體不會限制元件的 CPU 使用量。
+ `memory` – 此元件的程序可在核心裝置上使用的 RAM 數量上限 （以 KB 為單位）。
此功能適用於 2.4.0 版及更新版本的 [Greengrass 核元件](greengrass-nucleus-component.md)。目前 AWS IoT Greengrass 不支援 Windows 核心裝置上的此功能。
**Example 範例基本組態更新**
下列範例`components`物件指定 來部署元件 `com.example.PythonRuntime`，該元件預期組態參數名為 `pythonVersion`。
```
{
"targetArn": "targetArn",
"deploymentName": "deploymentName",
"components": {
"com.example.PythonRuntime": {
"componentVersion": "1.0.0",
"configurationUpdate": {
"merge": "{\"pythonVersion\":\"3.7\"}"
}
}
}
}
```
**Example 具有重設和合併更新的範例組態更新**
請考慮`com.example.IndustrialDashboard`具有下列預設組態的範例工業儀表板元件 。
```
{
"name": null,
"mode": "REQUEST",
"network": {
"useHttps": true,
"port": {
"http": 80,
"https": 443
},
},
"tags": []
}
```
下列組態更新會指定下列指示：
1. 將 HTTPS 設定重設為其預設值 (`true`)。
1. 將工業標籤清單重設為空白清單。
1. 合併工業標籤清單，以識別兩個鍋爐的溫度和壓力資料串流。
```
{
"reset": [
"/network/useHttps",
"/tags"
],
"merge": {
"tags": [
"/boiler/1/temperature",
"/boiler/1/pressure",
"/boiler/2/temperature",
"/boiler/2/pressure"
]
}
}
```
下列範例`components`物件會指定 部署此工業儀表板元件和組態更新。
```
{
"targetArn": "targetArn",
"deploymentName": "deploymentName",
"components": {
"com.example.IndustrialDashboard": {
"componentVersion": "1.0.0",
"configurationUpdate": {
"reset": [
"/network/useHttps",
"/tags"
],
"merge": "{\"tags\":[\"/boiler/1/temperature\",\"/boiler/1/pressure\",\"/boiler/2/temperature\",\"/boiler/2/pressure\"]}"
}
}
}
}
```
1. （選用） 定義部署的部署政策。您可以設定核心裝置何時可以安全地套用部署，或如果核心裝置無法套用部署時該怎麼辦。若要這麼做，請將`deploymentPolicies`物件新增至 `deployment.json`，然後執行下列任何動作：
1. （選用） 指定元件更新政策 (`componentUpdatePolicy`)。此政策會定義部署是否允許元件延遲更新，直到準備好更新為止。例如，元件可能需要清除資源或完成關鍵動作，才能重新啟動以套用更新。此政策也會定義元件必須回應更新通知的時間量。
此政策是具有下列參數的物件：
+ `action` – （選用） 是否要通知元件，並等待元件準備好更新時回報。您可以從以下選項中選擇：
+ `NOTIFY_COMPONENTS` – 部署會在停止前向每個元件發出通知並更新該元件。元件可以使用 [SubscribeToComponentUpdates](ipc-component-lifecycle.md#ipc-operation-subscribetocomponentupdates) IPC 操作來接收這些通知。
+ `SKIP_NOTIFY_COMPONENTS` – 部署不會向元件發出通知，也不會等到可安全更新元件時才更新。
預設為 `NOTIFY_COMPONENTS`。
+ `timeoutInSeconds` 每個元件必須使用 [DeferComponentUpdate](ipc-component-lifecycle.md#ipc-operation-defercomponentupdate) IPC 操作回應更新通知的時間，以秒為單位。如果元件未在此時間內回應，則部署會在核心裝置上繼續。
預設為 60 秒。
1. （選用） 指定組態驗證政策 (`configurationValidationPolicy`)。此政策定義每個元件必須驗證部署中組態更新的時間長度。元件可以使用 [SubscribeToValidateConfigurationUpdates](ipc-component-configuration.md#ipc-operation-subscribetovalidateconfigurationupdates) IPC 操作來訂閱通知，以取得自己的組態更新。然後，元件可以使用 [SendConfigurationValidityReport](ipc-component-configuration.md#ipc-operation-sendconfigurationvalidityreport) IPC 操作來告知 AWS IoT Greengrass Core 軟體組態更新是否有效。如果組態更新無效，部署會失敗。
此政策是具有下列參數的物件：
+ `timeoutInSeconds` （選用） 每個元件驗證組態更新所需的秒數。如果元件未在此時間內回應，則部署會在核心裝置上繼續。
預設為 30 秒。
1. （選用） 指定失敗處理政策 (`failureHandlingPolicy`)。此政策是字串，可定義部署失敗時是否要復原裝置。您可以從以下選項中選擇：
+ `ROLLBACK` – 如果核心裝置上的部署失敗，則 AWS IoT Greengrass 核心軟體會將該核心裝置復原為先前的組態。
+ `DO_NOTHING` – 如果在核心裝置上部署失敗，則 AWS IoT Greengrass 核心軟體會保留新的組態。如果新組態無效，這可能會導致元件損壞。
預設為 `ROLLBACK`。
您在 中的部署`deployment.json`可能看起來類似下列範例：
```
{
"targetArn": "targetArn",
"deploymentName": "deploymentName",
"components": {
"com.example.IndustrialDashboard": {
"componentVersion": "1.0.0",
"configurationUpdate": {
"reset": [
"/network/useHttps",
"/tags"
],
"merge": "{\"tags\":[\"/boiler/1/temperature\",\"/boiler/1/pressure\",\"/boiler/2/temperature\",\"/boiler/2/pressure\"]}"
}
}
},
"deploymentPolicies": {
"componentUpdatePolicy": {
"action": "NOTIFY_COMPONENTS",
"timeoutInSeconds": 30
},
"configurationValidationPolicy": {
"timeoutInSeconds": 60
},
"failureHandlingPolicy": "ROLLBACK"
}
}
```
1. （選用） 定義部署如何停止、推展或逾時。 AWS IoT Greengrass AWS IoT Core 使用任務將部署傳送至核心裝置，因此這些選項與 AWS IoT Core 任務的組態選項相同。如需詳細資訊，請參閱《 *AWS IoT 開發人員指南*》中的[任務推出和中止組態](https://docs.aws.amazon.com/iot/latest/developerguide/job-rollout-abort.html)。
若要定義任務選項，請將`iotJobConfiguration`物件新增至 `deployment.json`。然後，定義要設定的選項。
您在 中的部署`deployment.json`可能看起來類似下列範例：
```
{
"targetArn": "targetArn",
"deploymentName": "deploymentName",
"components": {
"com.example.IndustrialDashboard": {
"componentVersion": "1.0.0",
"configurationUpdate": {
"reset": [
"/network/useHttps",
"/tags"
],
"merge": "{\"tags\":[\"/boiler/1/temperature\",\"/boiler/1/pressure\",\"/boiler/2/temperature\",\"/boiler/2/pressure\"]}"
}
}
},
"deploymentPolicies": {
"componentUpdatePolicy": {
"action": "NOTIFY_COMPONENTS",
"timeoutInSeconds": 30
},
"configurationValidationPolicy": {
"timeoutInSeconds": 60
},
"failureHandlingPolicy": "ROLLBACK"
},
"iotJobConfiguration": {
"abortConfig": {
"criteriaList": [
{
"action": "CANCEL",
"failureType": "ALL",
"minNumberOfExecutedThings": 100,
"thresholdPercentage": 5
}
]
},
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": 5,
"incrementFactor": 2,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": 10,
"numberOfSucceededThings": 5
}
},
"maximumPerMinute": 50
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": 5
}
}
}
```
1. （選用） 為部署新增標籤 (`tags`)。如需詳細資訊，請參閱[標記您的 AWS IoT Greengrass Version 2 資源](tag-resources.md)。
1. 執行下列命令，從 建立部署`deployment.json`。
```
aws greengrassv2 create-deployment --cli-input-json file://deployment.json
```
回應包含可識別此部署`deploymentId`的 。您可以使用部署 ID 來檢查部署的狀態。如需詳細資訊，請參閱[檢查部署狀態](check-deployment-status.md#check-cloud-deployment-status)。
# 更新元件組態
元件組態是定義每個元件參數的 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",
]
}
```
# 建立子部署
**注意**
子部署功能可在 Greengrass nucleus 2.9.0 版及更新版本上使用。無法將組態部署到具有舊版 Greengrass 核元件的子部署。
子部署是針對父部署中較小裝置子集的部署。您可以使用子部署將組態部署到較小的裝置子集。您也可以建立子部署，在該父部署中的一或多個裝置失敗時重試失敗的父部署。使用此功能，您可以選取在該父部署中失敗的裝置，並建立子部署以測試組態，直到子部署成功為止。子部署成功後，您可以將該組態重新部署到父部署。
遵循本節中的步驟來建立子部署並檢查其狀態。如需如何建立部署的詳細資訊，請參閱[建立部署](https://docs.aws.amazon.com/greengrass/v2/developerguide/create-deployments.html)。
**建立子部署 (AWS CLI)**
1. 執行下列命令來擷取物件群組的最新部署。將命令中的 ARN 取代為要查詢之物件群組的 ARN。`--history-filter` 設定為 **LATEST\$1ONLY**以查看該物件群組的最新部署。
```
aws greengrassv2 list-deployments --target-arn arn:aws:iot:region:account-id:thinggroup/thingGroupName --history-filter LATEST_ONLY
```
1. 將 `deploymentId` 從回應複製到 **list-deployments**命令，以在下一個步驟中使用。
1. 執行下列命令來擷取部署的狀態。`deploymentId` 將 取代為要查詢之部署的 ID。
```
aws greengrassv2 get-deployment --deployment-id deploymentId
```
1. 將 `iotJobId` 從回應複製到 **get-deployment**命令，以在下列步驟中使用。
1. 執行下列命令，以擷取指定任務的任務執行清單。將 *jobID* 取代為上一個步驟`iotJobId`的 。將*狀態*取代為您要篩選的狀態。您可以篩選具有下列狀態的結果：
+ `QUEUED`
+ `IN_PROGRESS`
+ `SUCCEEDED`
+ `FAILED`
+ `TIMED_OUT`
+ `REJECTED`
+ `REMOVED`
+ `CANCELED`
```
aws iot list-job-executions-for-job --job-id jobID --status status
```
1. 為您的子部署建立新的 AWS IoT 物件群組，或使用現有的物件群組。然後，將 AWS IoT 物件新增至此物件群組。您可以使用物件群組來管理 Greengrass 核心裝置的機群。當您將軟體元件部署到裝置時，您可以鎖定個別裝置或裝置群組。您可以將裝置新增至具有作用中 Greengrass 部署的物件群組。新增後，您就可以將該物件群組的軟體元件部署到該裝置。
若要建立新的物件群組並將您的裝置新增至其中，請執行下列動作：
1. 建立 AWS IoT 物件群組。將 *MyGreengrassCoreGroup* 取代為新物件群組的名稱。您無法在物件群組名稱中使用冒號 (：)。
**注意**
如果子部署的物件群組與一個 搭配使用`parentTargetArn`，則無法與不同的父機群重複使用。如果物件群組已用於為另一個機群建立子部署，則 API 會傳回錯誤。
```
aws iot create-thing-group --thing-group-name MyGreengrassCoreGroup
```
如果請求成功，回應看起來與下列範例類似：
```
{
"thingGroupName": "MyGreengrassCoreGroup",
"thingGroupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/MyGreengrassCoreGroup",
"thingGroupId": "4df721e1-ff9f-4f97-92dd-02db4e3f03aa"
}
```
1. 將佈建的 Greengrass 核心新增至您的物件群組。使用這些參數執行下列命令：
+ 將 *MyGreengrassCore* 取代為您佈建的 Greengrass 核心的名稱。
+ 將 *MyGreengrassCoreGroup* 取代為您的物件群組名稱。
```
aws iot add-thing-to-thing-group --thing-name MyGreengrassCore --thing-group-name MyGreengrassCoreGroup
```
如果請求成功，命令不會有任何輸出。
1. 建立名為 的檔案`deployment.json`，然後將下列 JSON 物件複製到 檔案。將 *targetArn* 取代為 AWS IoT 物件群組的 ARN，以鎖定子部署的目標。子部署目標只能是物件群組。物件群組 ARNs的格式如下：
+ **物件群組** – `arn:aws:iot:region:account-id:thinggroup/thingGroupName`
```
{
"targetArn": "targetArn"
}
```
1. 再次執行下列命令，以取得原始部署的詳細資訊。這些詳細資訊包括中繼資料、元件和任務組態。將 *deploymentId* 取代為來自 的 ID[Step 1](#create-subdeployments-step1)。您可以使用此部署組態來設定子部署，並視需要進行變更。
```
aws greengrassv2 get-deployment --deployment-id deploymentId
```
回應包含部署的詳細資訊。將下列任一鍵值對從**get-deployment**命令的回應複製到 `deployment.json`。您可以變更子部署的這些值。如需此命令詳細資訊的詳細資訊，請參閱 [GetDeployment](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_GetDeployment.html)。
+ `components` – 部署的元件。若要解除安裝元件，請從此物件中移除它。
+ `deploymentName` – 部署的名稱。
+ `deploymentPolicies` – 部署的政策。
+ `iotJobConfiguration` – 部署的任務組態。
+ `parentTargetArn` – 父系部署的目標。
+ `tags` – 部署的標籤。
1. 執行下列命令，從 建立子部署`deployment.json`。將 *subdeploymentName* 取代為子部署的名稱。
```
aws greengrassv2 create-deployment --deployment-name subdeploymentName --cli-input-json file://deployment.json
```
回應包含可識別此子部署`deploymentId`的 。您可以使用部署 ID 來檢查部署的狀態。如需詳細資訊，請參閱[檢查部署狀態](https://docs.aws.amazon.com/greengrass/v2/developerguide/check-deployment-status.html#check-cloud-deployment-status)。
1. 如果子部署成功，您可以使用其組態來修改父部署。複製`deployment.json`您在上一個步驟中使用的 。`targetArn` 將 JSON 檔案中的 取代為父系部署的 ARN，並執行下列命令來使用此新組態建立父系部署。
**注意**
如果您建立新的父機群部署修訂版，它會取代該父部署的所有部署修訂版和子部署。如需詳細資訊，請參閱[修訂部署](https://docs.aws.amazon.com/greengrass/v2/developerguide/revise-deployments.html)。
```
aws greengrassv2 create-deployment --cli-input-json file://deployment.json
```
回應包含可識別此部署`deploymentId`的 。您可以使用部署 ID 來檢查部署的狀態。如需詳細資訊，請參閱[檢查部署狀態](check-deployment-status.md#check-cloud-deployment-status)。
# 修訂部署
每個目標物件或物件群組一次可以有一個作用中的部署。當您為已經有部署的目標建立部署時，新部署中的軟體元件會取代先前部署的軟體元件。如果新部署未定義先前部署定義的元件，則 AWS IoT Greengrass Core 軟體會從目標核心裝置移除該元件。您可以修改現有的部署，以免將核心裝置上執行的元件從先前的部署移除到目標。
若要修改部署，您可以建立從先前部署中存在的相同元件和組態開始的部署。您可以使用 [CreateDeployment](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_CreateDeployment.html) 操作，這是您用來[建立部署](create-deployments.md)的相同操作。
**修改部署 (AWS CLI)**
1. 執行下列命令來列出部署目標的部署。將 *targetArn* 取代為目標 AWS IoT 物件或物件群組的 ARN。
```
aws greengrassv2 list-deployments --target-arn targetArn
```
回應包含具有目標最新部署的清單。`deploymentId` 從回應中複製 以用於下一個步驟。
**注意**
您也可以修改目標最新修訂版以外的部署。指定`--history-filter ALL`引數以列出目標的所有部署。然後，複製您要修改的部署 ID。
1. 執行下列命令以取得部署的詳細資訊。這些詳細資訊包括中繼資料、元件和任務組態。將 *deploymentId* 取代為上一個步驟的 ID。
```
aws greengrassv2 get-deployment --deployment-id deploymentId
```
回應包含部署的詳細資訊。
1. 建立名為 `deployment.json` 的文件，並將前一個命令的回應複製到檔案中。
1. 從 JSON 物件的 `deployment.json` 中移除以下鍵值組：
+ `deploymentId`
+ `revisionId`
+ `iotJobId`
+ `iotJobArn`
+ `creationTimestamp`
+ `isLatestForTarget`
+ `deploymentStatus`
[CreateDeployment](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_CreateDeployment.html) 操作預期承載具有下列結構。
```
{
"targetArn": "String",
"components": Map of components,
"deploymentPolicies": DeploymentPolicies,
"iotJobConfiguration": DeploymentIoTJobConfiguration,
"tags": Map of tags
}
```
1. 在 `deployment.json` 中，執行下列任何一項：
+ 變更部署的名稱 (`deploymentName`)。
+ 變更部署的元件 (`components`)。
+ 變更部署的政策 (`deploymentPolicies`)。
+ 變更部署的任務組態 (`iotJobConfiguration`)。
+ 變更部署的標籤 (`tags`)。
如需如何定義這些部署詳細資訊的詳細資訊，請參閱[建立部署](create-deployments.md)。
1. 執行下列命令，從 建立部署`deployment.json`。
```
aws greengrassv2 create-deployment --cli-input-json file://deployment.json
```
回應包含可識別此部署`deploymentId`的 。您可以使用部署 ID 來檢查部署的狀態。如需詳細資訊，請參閱[檢查部署狀態](check-deployment-status.md#check-cloud-deployment-status)。
# 取消部署
您可以取消作用中部署，以防止其軟體元件安裝在 AWS IoT Greengrass 核心裝置上。如果您取消以物件群組為目標的部署，您新增至群組的核心裝置將不會收到該持續部署。如果核心裝置已執行部署，則當您取消部署時，不會變更該裝置上的元件。您必須[建立新的部署](create-deployments.md)[或修改部署](revise-deployments.md)，以修改在接收已取消部署的核心裝置上執行的元件。
**取消部署 (AWS CLI)**
1. 執行下列命令來尋找目標的最新部署修訂的 ID。最新修訂是唯一可以對目標啟用的部署，因為先前部署會在您建立新的修訂時取消。將 *targetArn* 取代為目標 AWS IoT 物件或物件群組的 ARN。
```
aws greengrassv2 list-deployments --target-arn targetArn
```
回應包含具有目標最新部署的清單。`deploymentId` 從回應中複製 以用於下一個步驟。
1. 執行下列命令來取消部署。將 *deploymentId* 取代為上一個步驟的 ID。
```
aws greengrassv2 cancel-deployment --deployment-id deploymentId
```
如果操作成功，部署狀態會變更為 `CANCELED`。
# 檢查部署狀態
您可以檢查您在其中建立的部署狀態 AWS IoT Greengrass。您也可以檢查將部署推展到每個核心裝置 AWS IoT 的任務狀態。當部署處於作用中狀態時， AWS IoT 任務的狀態為 `IN_PROGRESS`。建立新的部署修訂版之後，上一個修訂版 AWS IoT 的任務狀態會變更為 `CANCELLED`。
**Topics**
+ [檢查部署狀態](#check-cloud-deployment-status)
+ [檢查裝置部署狀態](#check-device-deployment-status)
## 檢查部署狀態
您可以檢查依目標或其 ID 識別的部署狀態。
**依目標檢查部署狀態 (AWS CLI)**
+ 執行下列命令，以擷取目標的最新部署狀態。將 *targetArn* 取代為部署目標 AWS IoT 之實物或實物群組的 Amazon Resource Name (ARN)。
```
aws greengrassv2 list-deployments --target-arn targetArn
```
回應包含具有目標最新部署的清單。此部署物件包含部署的狀態。
**依 ID 檢查部署狀態 (AWS CLI)**
+ 執行下列命令來擷取部署的狀態。將 *deploymentId* 取代為要查詢的部署 ID。
```
aws greengrassv2 get-deployment --deployment-id deploymentId
```
回應包含部署的狀態。
## 檢查裝置部署狀態
您可以檢查套用至個別核心裝置的部署任務狀態。您也可以檢查物件群組部署的部署任務狀態。
**檢查核心裝置的部署任務狀態 (AWS CLI)**
+ 執行下列命令，以擷取核心裝置的所有部署任務狀態。將 *coreDeviceName* 取代為要查詢的核心裝置名稱。
```
aws greengrassv2 list-effective-deployments --core-device-thing-name coreDeviceName
```
回應包含核心裝置的部署任務清單。您可以透過任務的 `deploymentId`或 來識別部署的任務`targetArn`。每個部署任務都包含核心裝置上任務的狀態。
**檢查物件群組的部署狀態 (AWS CLI)**
1. 執行下列命令來擷取現有部署的 ID。將 *targetArn* 取代為目標物件群組的 ARN。
```
aws greengrassv2 list-deployments --target-arn targetArn
```
回應包含具有目標最新部署的清單。`deploymentId` 從回應中複製 以用於下一個步驟。
**注意**
您也可以列出目標最新部署以外的部署。指定引`--history-filter ALL`數以列出目標的所有部署。然後，複製您要檢查狀態的部署 ID。
1. 執行下列命令以取得部署的詳細資訊。將 *deploymentID* 取代為上一個步驟的 ID。
```
aws greengrassv2 get-deployment --deployment-id deploymentId
```
回應包含部署的相關資訊。`iotJobId` 從回應中複製 以用於下列步驟。
1. 執行下列命令來描述核心裝置在部署時的任務執行。將 *iotJobId* 和 *coreDeviceThingName* 取代為上一個步驟的任務 ID，以及您要檢查狀態的核心裝置。
```
aws iot describe-job-execution --job-id iotJobId --thing-name coreDeviceThingName
```
回應包含核心裝置部署任務執行的狀態，以及狀態的詳細資訊。`detailsMap` 包含下列資訊：
+ `detailed-deployment-status` – 部署結果狀態，可以是下列其中一個值：
+ `SUCCESSFUL` – 部署成功。
+ `FAILED_NO_STATE_CHANGE` – 核心裝置準備套用部署時，部署失敗。
+ `FAILED_ROLLBACK_NOT_REQUESTED` – 部署失敗，而且部署未指定 轉返先前的工作組態，因此核心裝置可能無法正常運作。
+ `FAILED_ROLLBACK_COMPLETE` – 部署失敗，核心裝置成功復原至先前的工作組態。
+ `FAILED_UNABLE_TO_ROLLBACK` – 部署失敗，且核心裝置無法復原至先前的工作組態，因此核心裝置可能無法正常運作。
如果部署失敗，請檢查 `deployment-failure-cause`值和核心裝置的日誌檔案，以識別問題。如需如何存取核心裝置日誌檔案的詳細資訊，請參閱[監控 AWS IoT Greengrass 日誌](monitor-logs.md)。
+ `deployment-failure-cause` – 錯誤訊息，提供任務執行失敗原因的其他詳細資訊。
回應看起來與下列範例類似。
```
{
"execution": {
"jobId": "2cc2698a-5175-48bb-adf2-1dd345606ebd",
"status": "FAILED",
"statusDetails": {
"detailsMap": {
"deployment-failure-cause": "No local or cloud component version satisfies the requirements. Check whether the version constraints conflict and that the component exists in your AWS 帳戶 with a version that matches the version constraints. If the version constraints conflict, revise deployments to resolve the conflict. Component com.example.HelloWorld version constraints: LOCAL_DEPLOYMENT requires =1.0.0, thinggroup/MyGreengrassCoreGroup requires =1.0.1.",
"detailed-deployment-status": "FAILED_NO_STATE_CHANGE"
}
},
"thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyGreengrassCore",
"queuedAt": "2022-02-15T14:45:53.098000-08:00",
"startedAt": "2022-02-15T14:46:05.670000-08:00",
"lastUpdatedAt": "2022-02-15T14:46:20.892000-08:00",
"executionNumber": 1,
"versionNumber": 3
}
}
```