终止支持通知：2026 年 10 月 7 日， AWS 将停止对的支持。 AWS IoT Greengrass Version 1 2026 年 10 月 7 日之后，您将无法再访问这些 AWS IoT Greengrass V1 资源。如需了解更多信息，请访问[迁移自 AWS IoT Greengrass Version 1](https://docs.aws.amazon.com/greengrass/v2/developerguide/migrate-from-v1.html)。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 将 AWS IoT Greengrass 群组部署到 AWS IoT Greengrass 核心
使用 AWS IoT Greengrass 群组来组织边缘环境中的实体。您也可以使用组来控制组中的实体如何相互交互并与 AWS 云交互。例如，只针对本地运行部署组中的 Lambda 函数，仅组中的设备可以使用本地 MQTT 服务器进行通信。
一个组必须包括一个[内核](gg-core.md)，即运行 AWS IoT Greengrass 核心软件的 AWS IoT 设备。核心充当边缘网关，在边缘环境中提供 AWS IoT Core 功能。根据您的业务需求，还可以向组中添加以下实体：
+ **客户端设备**。在 AWS IoT 注册表中表示为事物。这些设备必须运行 [FreeRTOS](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-lib-gg-connectivity.html) 或使用 [AWS IoT 设备开发工具包](what-is-gg.md#iot-device-sdk)或[AWS IoT Greengrass 发现 API](gg-discover-api.md) 来获取核心的连接信息。只有作为组成员的客户端设备才可以连接到核心。
+ **Lambda 函数**。在核心上运行代码的用户定义的无服务器应用程序。Lambda 函数是在 Greengrass 群 AWS Lambda 组中编写和引用的。有关更多信息，请参阅 [在核心上运行 Lambda 函数 AWS IoT Greengrass](lambda-functions.md)。
+ **连接器**。在核心上运行代码的预定义无服务器应用程序。连接器可以提供与本地基础架构、设备协议和其他云服务的内置集成。 AWS有关更多信息，请参阅 [使用 Greengrass 连接器与服务和协议集成](connectors.md)。
+ **订阅**。定义有权进行 MQTT 通信的发布者、订阅者和 MQTT 主题（或对象）。
+ **资源**。引用本地[设备和卷](access-local-resources.md)、[机器学习模型](ml-inference.md)和[密钥](secrets.md)（用于通过 Greengrass Lambda 函数和连接器进行访问控制）。
+ **日志**。 AWS IoT Greengrass 系统组件和 Lambda 函数的日志配置。有关更多信息，请参阅 [使用 AWS IoT Greengrass 日志进行监控](greengrass-logs-overview.md)。
你可以在中管理你的 Greengrass 群组，然后将其部署 AWS 云 到核心。部署会将组配置复制到核心设备上的 `group.json` 文件。此文件位于 `greengrass-root/ggc/deployments/group` 中：
![\[部署到核心设备上的 Greengrass 组的云定义。\]](http://docs.aws.amazon.com/zh_cn/greengrass/v1/developerguide/images/group-deploy.png)
**注意**
在部署期间，核心设备上的 Greengrass 守护程序进程停止，然后重新启动。
## 从 AWS IoT 控制台部署群组
您可以通过 AWS IoT 控制台中的群组配置页面部署群组并管理其部署。
**注意**
要在控制台中打开此页面，请依次选择 **Greengrass 设备**和**组 (V1)**，然后在 **Greengrass 组**下选择您的组。
**部署当前版本的组**
+ 在组配置页面上，选择 **部署**。
**查看组的部署历史记录**
组的部署历史记录包括每次部署尝试的日期和时间、组版本和状态。
1. 在组配置页面中，选择**部署**选项卡。
1. 要查看有关部署的更多信息（包括错误消息），请在 AWS IoT 控制台的 **Greengrass** 设备下选择**部署**。
**重新部署组部署**
如果当前部署失败，您可能希望重新部署一个部署，或者恢复为不同的组版本。
1. **在 AWS IoT 控制台中，选择 **Greengrass** 设备，然后选择群组 (V1)。**
1. 选择 **部署** 选项卡。
1. 选择要重新部署的部署，然后选择**重新部署**。
**重置组部署**
您可能希望重置组部署以移动或删除组或删除部署信息。有关更多信息，请参阅 [重置部署](reset-deployments-scenario.md)。
1. **在 AWS IoT 控制台中，选择 **Greengrass** 设备，然后选择群组 (V1)。**
1. 选择 **部署** 选项卡。
1. 选择要重置的部署，然后选择**重置部署**。
## 使用 AWS IoT Greengrass API 部署群组
AWS IoT Greengrass API 提供以下操作来部署 AWS IoT Greengrass 群组和管理群组部署。您可以从 AWS CLI、 AWS IoT Greengrass API 或 AWS SDK 调用这些操作。
| 操作 | 描述 |
| --- | --- |
| [CreateDeployment](https://docs.aws.amazon.com/greengrass/v1/apireference/createdeployment-post.html) | 创建 `NewDeployment` 或 `Redeployment` 部署。 如果当前部署失败，您可能希望重新部署一个部署。或者，您可能希望重新部署，以恢复到另一个组版本。 |
| [GetDeploymentStatus](https://docs.aws.amazon.com/greengrass/v1/apireference/getdeploymentstatus-get.html) | 返回部署的状态：`Building`、`InProgress`、`Success` 或 `Failure`。 您可以将 Amazon EventBridge 事件配置为接收部署通知。有关更多信息，请参阅 [获取部署通知](deployment-notifications.md)。 |
| [ListDeployments](https://docs.aws.amazon.com/greengrass/v1/apireference/listdeployments-get.html) | 返回组的部署历史记录。 |
| [ResetDeployments](https://docs.aws.amazon.com/greengrass/v1/apireference/resetdeployments-post.html) | 重置组的部署。 您可能希望重置组部署以移动或删除组或删除部署信息。有关更多信息，请参阅 [重置部署](reset-deployments-scenario.md)。 |
**注意**
有关批量部署操作的更多信息，请参阅 [为组创建批量部署](bulk-deploy-cli.md)。
### 获取组 ID
组 ID 通常用于 API 操作中。您可以使用该[ListGroups](https://docs.aws.amazon.com/greengrass/v1/apireference/listgroups-get.html)操作从群组列表中查找目标群组的 ID。例如，在中 AWS CLI，使用`list-groups`命令。
```
aws greengrass list-groups
```
您还可以包含用于筛选结果的 `query` 选项。例如：
+ 要获取最近创建的组，请执行以下操作：
```
aws greengrass list-groups --query "reverse(sort_by(Groups, &CreationTimestamp))[0]"
```
+ 按名称获取组：
```
aws greengrass list-groups --query "Groups[?Name=='MyGroup']"
```
系统不要求组名称是唯一的，所以可能会返回多个组。
以下为 `list-groups` 响应示例。每个组的信息都包含组 ID（在 `Id` 属性中）和最新组版本 ID（在 `LatestVersion` 属性中）。要获取群组的其他版本 IDs ，请使用群组 ID 和[ListGroupVersions](https://docs.aws.amazon.com/greengrass/v1/apireference/listgroupversions-get.html)。
**注意**
您也可以在 AWS IoT 控制台中找到这些值。组 ID 显示在组的**设置**页面上。群组版本显示 IDs 在群组的 “**部署**” 选项卡上。
```
{
"Groups": [
{
"LatestVersionArn": "arn:aws:us-west-2:123456789012:/greengrass/groups/00dedaaa-ac16-484d-ad77-c3eedEXAMPLE/versions/4cbc3f07-fc5e-48c4-a50e-7d356EXAMPLE",
"Name": "MyFirstGroup",
"LastUpdatedTimestamp": "2019-11-11T05:47:31.435Z",
"LatestVersion": "4cbc3f07-fc5e-48c4-a50e-7d356EXAMPLE",
"CreationTimestamp": "2019-11-11T05:47:31.435Z",
"Id": "00dedaaa-ac16-484d-ad77-c3eedEXAMPLE",
"Arn": "arn:aws:us-west-2:123456789012:/greengrass/groups/00dedaaa-ac16-484d-ad77-c3eedEXAMPLE"
},
{
"LatestVersionArn": "arn:aws:us-west-2:123456789012:/greengrass/groups/036ceaf9-9319-4716-ba2a-237f9EXAMPLE/versions/8fe9e8ec-64d1-4647-b0b0-01dc8EXAMPLE",
"Name": "GreenhouseSensors",
"LastUpdatedTimestamp": "2020-01-07T19:58:36.774Z",
"LatestVersion": "8fe9e8ec-64d1-4647-b0b0-01dc8EXAMPLE",
"CreationTimestamp": "2020-01-07T19:58:36.774Z",
"Id": "036ceaf9-9319-4716-ba2a-237f9EXAMPLE",
"Arn": "arn:aws:us-west-2:123456789012:/greengrass/groups/036ceaf9-9319-4716-ba2a-237f9EXAMPLE"
},
...
]
}
```
如果您未指定 AWS 区域，则 AWS CLI 命令将使用您个人资料中的默认区域。要返回不同地区的群组，请添加*region*选项。例如：
```
aws greengrass list-groups --region us-east-1
```
## AWS IoT Greengrass 群组对象模型概述
在使用 AWS IoT Greengrass API 进行编程时，理解 Greengrass 群组对象模型会很有帮助。
### 组
在 AWS IoT Greengrass API 中，顶级`Group`对象由元数据和`GroupVersion`对象列表组成。 `GroupVersion`对象与 b `Group` y ID 相关联。
![\[组的示意图，包含元数据和组版本的列表。\]](http://docs.aws.amazon.com/zh_cn/greengrass/v1/developerguide/images/om-group.png)
### 组版本
`GroupVersion` 对象可定义组成员资格。每个 `GroupVersion` 通过 ARN 引用一个 `CoreDefinitionVersion` 和其他组件版本。这些引用可确定组中要包括哪些实体。
![\[通过 ARN 引用其他版本类型的组版本的示意图。\]](http://docs.aws.amazon.com/zh_cn/greengrass/v1/developerguide/images/om-groupversion.png)
例如，要在组中包含三个 Lambda 函数、一个设备和两个订阅，`GroupVersion` 引用：
+ 包含所需核心的 `CoreDefinitionVersion`。
+ 包含三个函数的 `FunctionDefinitionVersion`。
+ 包含客户端设备的 `DeviceDefinitionVersion`。
+ 包含两个订阅的 `SubscriptionDefinitionVersion`。
部署到核心设备的 `GroupVersion` 决定了本地环境中的可用实体及其它们如何进行交互。
### 组组件
添加到组中的组件具有三级层次结构：
+ 引用给定类型*DefinitionVersion*对象列表的*定义*。例如，`DeviceDefinition` 引用 `DeviceDefinitionVersion` 对象的列表。
+ *DefinitionVersion*包含一组给定类型的实体的类型。例如，`DeviceDefinitionVersion` 包含 `Device` 对象的列表。
+ 用于定义其属性和行为的各个实体。例如，a `Device` 定义了 AWS IoT 注册表中相应客户端设备的 ARN、其设备证书的 ARN 以及其本地影子是否自动与云同步。
您可以向组中添加以下类型的实体：
+ [连接器](https://docs.aws.amazon.com/greengrass/v1/apireference/definitions-connector.html)
+ [核心实例](https://docs.aws.amazon.com/greengrass/v1/apireference/definitions-core.html)
+ [设备](https://docs.aws.amazon.com/greengrass/v1/apireference/definitions-device.html)
+ [函数](https://docs.aws.amazon.com/greengrass/v1/apireference/definitions-function.html)
+ [Logger](https://docs.aws.amazon.com/greengrass/v1/apireference/definitions-logger.html)
+ [资源](https://docs.aws.amazon.com/greengrass/v1/apireference/definitions-resource.html)
+ [订阅](https://docs.aws.amazon.com/greengrass/v1/apireference/definitions-subscription.html)
以下示例 `DeviceDefinition` 会引用三个 `DeviceDefinitionVersion` 对象，每个都包含多个 `Device` 对象。一个组中一次只使用一个 `DeviceDefinitionVersion`。
![\[设备层次结构图，由 DeviceDefinition DeviceDefinitionVersion、和设备对象组成。\]](http://docs.aws.amazon.com/zh_cn/greengrass/v1/developerguide/images/om-devicedefinition.png)
### 更新组
在 AWS IoT Greengrass API 中，您可以使用版本来更新群组的配置。版本是不可变的，因此要添加、移除或更改组组件，必须创建包含新的或更新的实*DefinitionVersion*体的对象。
您可以将新*DefinitionVersions*对象与新的或现有的*定义*对象相关联。例如，您可以使用 `CreateFunctionDefinition` 操作来创建 `FunctionDefinition`（其中包含作为初始版本的 `FunctionDefinitionVersion`），也可以使用 `CreateFunctionDefinitionVersion` 操作并引用现有 `FunctionDefinition`。
创建组组件后，您将创建一个`GroupVersion`包含要包含在组中的所有*DefinitionVersion*对象。然后，部署 `GroupVersion`。
要部署 `GroupVersion`，则必须引用包含一个 `Core` 的 `CoreDefinitionVersion`。所有引用的实体必须是组的成员。此外，[Greengrass 服务](service-role.md)角色必须与 AWS 账户 您在部署的位置相关联 AWS 区域 。`GroupVersion`
**注意**
API 中的 `Update` 操作用于更改 `Group` 或组件 *Definition* 对象的名称。
**更新引用 AWS 资源的实体**
Greengrass Lambda 函数[和秘密资源定义了 GreenGrass 特有的属性，](secrets.md)还引用了相应的资源。 AWS 要更新这些实体，您可以更改相应的 AWS 资源，而不是 Greengrass 对象。例如，Lambda 函数引用了中的 AWS Lambda 函数，还定义了生命周期和其他特定于 Greengrass 组的属性。
+ 要更新 Lambda 函数代码或打包依赖项，请在 AWS Lambda中进行更改。在下次群组部署期间，这些更改将从您的本地环境中检索 AWS Lambda 并复制到您的本地环境中。
+ 要更新 [Greengrass 特定的属性](lambda-group-config.md)，您可以创建一个包含已更新 `Function` 属性的 `FunctionDefinitionVersion`。
**注意**
Greengrass Lambda 函数可以通过别名 ARN 或版本 ARN 引用 Lambda 函数。如果您引用别名 ARN（推荐），则在 AWS Lambda中发布新的函数版本时不需要更新 `FunctionDefinitionVersion`（或 `SubscriptionDefinitionVersion`）。有关更多信息，请参阅 [按别名或版本引用 Lambda 函数](lambda-functions.md#lambda-versions-aliases)。
## 另请参阅
+ [获取部署通知](deployment-notifications.md)
+ [重置部署](reset-deployments-scenario.md)
+ [为组创建批量部署](bulk-deploy-cli.md)
+ [排查部署问题](gg-troubleshooting.md#gg-troubleshooting-deploymentissues)
+ [AWS IoT Greengrass Version 1 API 引用](https://docs.aws.amazon.com/greengrass/v1/apireference/)
+ [AWS IoT Greengrass 命令](https://docs.aws.amazon.com/cli/latest/reference/greengrass/index.html)*参考中的AWS CLI 命令*
# 获取部署通知
亚马逊 EventBridge 事件规则为您提供有关您的 Greengrass 群组部署状态变化的通知。 EventBridge 提供描述 AWS 资源变化的近乎实时的系统事件流。 AWS IoT Greengrass *至少将这些事件发送到 EventBridge 一次*。这意味着 AWS IoT Greengrass 可能会发送给定事件的多个副本以确保交付。此外，事件侦听器可能无法按事件的发生顺序接收事件。
**注意**
Amazon EventBridge 是一项事件总线服务，可用于将应用程序与来自各种来源（例如 [Greengrass](telemetry.md) 核心设备和部署通知）的数据连接起来。有关更多信息，请参阅[什么是亚马逊 EventBridge？](https://docs.aws.amazon.com/eventbridge/latest/userguide/what-is-amazon-eventbridge.html) 在《*亚马逊 EventBridge 用户指南》*中。
AWS IoT Greengrass 当组部署状态发生变化时会发出一个事件。您可以创建一条 EventBridge 规则，该规则适用于所有状态转换或向指定状态的过渡。当部署进入启动规则的状态时， EventBridge 调用规则中定义的目标操作。这样，您就可以发送通知、捕获事件信息、采取纠正措施或启动其他事件以响应状态更改。例如，您可以为以下使用案例创建规则：
+ 启动部署后操作，例如下载资产和通知人员。
+ 在部署成功或失败时发送通知。
+ 发布关于部署事件的自定义指标。
AWS IoT Greengrass 当部署进入以下状态时会发出一个事件：`Building`、`InProgress``Success`、和。`Failure`
**注意**
目前不支持对[批量部署](bulk-deploy-cli.md)操作状态的监控。但是，对于 AWS IoT Greengrass 作为批量部署一部分的单个组部署，会发出状态更改事件。
## 组部署状态更改事件
部署状态更改的[事件](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/CloudWatchEventsandEventPatterns.html)采用以下格式：
```
{
"version":"0",
"id":" cd4d811e-ab12-322b-8255-EXAMPLEb1bc8",
"detail-type":"Greengrass Deployment Status Change",
"source":"aws.greengrass",
"account":"123456789012",
"time":"2018-03-22T00:38:11Z",
"region":"us-west-2",
"resources":[],
"detail":{
"group-id": "284dcd4e-24bc-4c8c-a770-EXAMPLEf03b8",
"deployment-id": "4f38f1a7-3dd0-42a1-af48-EXAMPLE09681",
"deployment-type": "NewDeployment|Redeployment|ResetDeployment|ForceResetDeployment",
"status": "Building|InProgress|Success|Failure"
}
}
```
您可以创建适用于一个或多个组的规则。您可以按以下一种或多种部署类型和部署状态筛选规则：
**部署类型**
+ `NewDeployment`. 组版本的第一次部署。
+ `ReDeployment`. 组版本的重新部署。
+ `ResetDeployment`。 删除存储在 AWS 云 和 AWS IoT Greengrass 核心上的部署信息。有关更多信息，请参阅 [重置部署](reset-deployments-scenario.md)。
+ `ForceResetDeployment`. 删除存储在 AWS 云 中的部署信息并报告成功，而无需等待核心进行响应。如果核心已连接或当下次连接时，会同时删除存储在核心中的部署信息。
**部署状态**
+ `Building`。 AWS IoT Greengrass 正在验证组配置并构建部署工件。
+ `InProgress`。 AWS IoT Greengrass 核心部署正在进行中。
+ `Success`. 部署成功。
+ `Failure`. 部署失败。
可能是事件重复或者顺序颠倒。要确定事件的顺序，请使用 `time` 属性。
**注意**
AWS IoT Greengrass 不使用该`resources`属性，因此它始终为空。
## 创建 EventBridge 规则的先决条件
在为创建 EventBridge 规则之前 AWS IoT Greengrass，请执行以下操作：
+ 熟悉中的事件、规则和目标。 EventBridge
+ 创建和配置您的 EventBridge 规则调用的目标。规则可以调用许多类型的目标，包括：
+ Amazon Simple Notification Service (Amazon SNS)
+ AWS Lambda 函数
+ Amazon Kinesis Video Streams
+ Amazon Simple Queue Service（Amazon SQS）队列
有关更多信息，请参阅[什么是亚马逊 EventBridge？](https://docs.aws.amazon.com/eventbridge/latest/userguide/what-is-amazon-eventbridge.html) 以及《[亚马逊* EventBridge 用户指南》 EventBridge中的 “亚马逊*入门](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-getting-set-up.html)”。
## 配置部署通知（控制台）
使用以下步骤创建 EventBridge 规则，以便在群组的部署状态发生变化时发布 Amazon SNS 主题。这样，Web 服务器、电子邮件地址和其他主题订阅者就可以响应事件。有关更多信息，请参阅 *Amazon EventBridge 用户指南*中的[创建针对来自 AWS 资源的事件触发的 EventBridge 规则](https://docs.aws.amazon.com/eventbridge/latest/userguide/create-eventbridge-rule.html)。
1. 打开[亚马逊 EventBridge控制台](https://console.aws.amazon.com/events/)。
1. 在导航窗格中，选择**规则**。
1. 选择**创建规则**。
1. 为规则输入名称和描述。
规则不能与同一区域中的另一个规则和同一事件总线上的名称相同。
1. 对于**事件总线**，请选择要与此规则关联的事件总线。如果您希望此规则对来自您自己的账户的匹配事件触发，请选择 **AWS 默认事件总线**。当你账户中的某项 AWS 服务发出事件时，它总是会进入你账户的默认事件总线。
1. 对于**规则类型**，选择**具有事件模式的规则**。
1. 选择**下一步**。
1. 对于**事件源**，选择**AWS 服务**。
1. 在**事件模式**中，选择 **AWS 服务**。
1. 对于**AWS 服务**，选择 Greengrass。
1. 对于 **Event type (事件类型)**，选择 **Greengrass Deployment Status Change (Greengrass 部署状态更改)**。
**注意**
**AWS API 通过 CloudTrail事件调用**类型基于与的 AWS IoT Greengrass 集成 AWS CloudTrail。您可以使用此选项创建通过对 AWS IoT Greengrass API 的读取或写入调用启动的规则。有关更多信息，请参阅 [使用记录 AWS IoT Greengrass API 调用 AWS CloudTrail](logging-using-cloudtrail.md)。
1. 选择将启动通知的部署状态。
+ 要接收所有状态更改事件的通知，请选择 **Any state (任何状态)**。
+ 要仅接收某些状态更改事件的通知，请选择 **Specific state(s) (特定状态)**，然后选择目标状态。
1. 选择将启动通知的部署类型。
+ 要接收所有部署类型的通知，请选择 **Any state (任何状态)**。
+ 要仅接收某些部署类型的通知，请选择 **Specific state(s) (特定状态)**，然后选择目标部署类型。
1. 选择**下一步**。
1. 对于**目标类型**，选择**AWS 服务**。
1. 在 **选择目标** 下，配置您的目标。此示例使用了 Amazon SNS 主题，而您可以配置其他目标类型来发送通知。
1. 对于 **Target (目标)**，选择 **SNS topic (SNS 主题)**。
1. 对于 **Topic (主题)**，请选择您的目标主题。
1. 选择**下一步**。
1. 在 **标签** 下，定义规则的标签或将字段留空。
1. 选择**下一步**。
1. 查看规则详细信息并选择**创建规则**。
## 配置部署通知 (CLI)
使用以下步骤创建 EventBridge 规则，以便在群组的部署状态发生变化时发布 Amazon SNS 主题。这样，Web 服务器、电子邮件地址和其他主题订阅者就可以响应事件。
1. 创建 规则。
+ *group-id*替换为您的 AWS IoT Greengrass 群组的 ID。
```
aws events put-rule \
--name TestRule \
--event-pattern "{\"source\": [\"aws.greengrass\"], \"detail\": {\"group-id\": [\"group-id\"]}}"
```
模式中省略的属性将被忽略。
1. 将主题添加为规则目标。
+ *topic-arn*替换为您的 Amazon SNS 主题的 ARN。
```
aws events put-targets \
--rule TestRule \
--targets "Id"="1","Arn"="topic-arn"
```
**注意**
要允许 Amazon EventBridge 调用您的目标主题，您必须在主题中添加基于资源的策略。有关更多信息，请参阅《[亚马逊* EventBridge 用户指南》中的 Ama* zon SNS 权限](https://docs.aws.amazon.com/eventbridge/latest/userguide/resource-based-policies-eventbridge.html#sns-permissions)。
有关更多信息，请参阅 *Amazon EventBridge 用户指南 EventBridge*[中的事件和事件模式](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html)。
## 配置部署通知 (CloudFormation)
使用 CloudFormation 模板创建 EventBridge 规则，发送有关 Greengrass 群组部署状态变更的通知。有关更多信息，请参阅*AWS CloudFormation 用户指南*中的 [Amazon EventBridge 资源类型参考](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/AWS_Events.html)。
## 另请参阅
+ [将 AWS IoT Greengrass 群组部署到 AWS IoT Greengrass 核心](deployments.md)
+ [什么是亚马逊 EventBridge？](https://docs.aws.amazon.com/eventbridge/latest/userguide/what-is-amazon-eventbridge.html) 在《*亚马逊 EventBridge 用户指南》*中
# 重置部署
此功能适用于 AWS IoT Greengrass 酷睿 v1.1 及更高版本。
您可能希望重置组的部署以执行以下操作：
+ 删除组，例如当您要将组的核心移至另一个组时，或者组的核心已重新制作了映像时。在删除组之前，您必须重置该组的部署，以便将核心与另一个 Greengrass 组结合使用。
+ 将组的核心移到不同的组。
+ 将组恢复到任何部署之前的状态。
+ 从核心设备删除部署配置。
+ 从核心设备或云中删除敏感数据。
+ 将新的组配置部署到一个核心而不必将该核心替换成当前组中的另一个核心。
**注意**
AWS IoT Greengrass 核心软件 v1.0.0 中不支持重置部署功能。您不能删除已使用 v1.0.0 部署的组。
重置部署操作首先会清除存储在云中的指定组的所有部署信息。然后，它将指示该组的核心设备也清理其所有部署相关部署信息（Lambda 函数、用户日志、影子数据库和服务器证书，但不包括用户定义的 `config.json` 或 Greengrass 核心证书。） 如果一个组目前的部署状态为 `In Progress` 或 `Building`，则无法为其启动部署重置。
## 从 AWS IoT 控制台重置部署
您可以从 AWS IoT 控制台的群组配置页面重置群组部署。
1. **在 AWS IoT 控制台导航窗格的**管理**下，展开 **Greengrass** 设备，然后选择群组 (V1)。**
1. 选择目标组。
1. 在 **部署** 选项卡中，选择 **重置部署**。
1. 在**重置此 Greengrass 组的部署**对话框中，键入 **confirm** 以表示同意，然后选择**重置部署**。
## 使用 AWS IoT Greengrass API 重置部署
您可以使用 AWS CLI、 AWS IoT Greengrass API 或 AWS SDK 中的`ResetDeployments`操作来重置部署。本主题中的示例使用 CLI。
```
aws greengrass reset-deployments --group-id GroupId [--force]
````reset-deployments` CLI 命令的参数：
`--group-id`
组 ID。使用 `list-groups` 命令以获取此值。
`--force`
可选。如果组的核心设备丢失、被盗或损毁，则使用此参数。该选项可使重置部署过程在云中的所有部署信息都清理完后即报告成功，而不必等待核心设备响应。但是，如果核心设备处于或变为活动状态，它还会执行清理操作。
`reset-deployments` CLI 命令的输出如下所示：
```
{
"DeploymentId": "4db95ef8-9309-4774-95a4-eea580b6ceef",
"DeploymentArn": "arn:aws:greengrass:us-west-2:106511594199:/greengrass/groups/b744ed45-a7df-4227-860a-8d4492caa412/deployments/4db95ef8-9309-4774-95a4-eea580b6ceef"
}
```
可以使用 `get-deployment-status` CLI 命令查看重置部署的状态：
```
aws greengrass get-deployment-status --deployment-id DeploymentId --group-id GroupId
````get-deployment-status` CLI 命令的参数：
`--deployment-id`
部署 ID。
`--group-id`
组 ID。
`get-deployment-status` CLI 命令的输出如下所示：
```
{
"DeploymentStatus": "Success",
"UpdatedAt": "2017-04-04T00:00:00.000Z"
}
```
当重置部署正在准备时，`DeploymentStatus` 设置为 `Building`。当重置部署准备就绪但 AWS IoT Greengrass 核心尚未启动重置部署时，则`DeploymentStatus`为`InProgress`。
如果重置操作失败，将在响应中返回错误信息。
## 另请参阅
+ [将 AWS IoT Greengrass 群组部署到 AWS IoT Greengrass 核心](deployments.md)
+ [ResetDeployments ](https://docs.aws.amazon.com/greengrass/v1/apireference/resetdeployments-post.html)在 *AWS IoT Greengrass Version 1 API 参考*中
+ [GetDeploymentStatus](https://docs.aws.amazon.com/greengrass/v1/apireference/getdeploymentstatus-get.html)在 *AWS IoT Greengrass Version 1 API 参考*中
# 为组创建批量部署
您可以使用简单 API 调用一次部署大量 Greengrass 组。这些部署通过具有固定上限的自适应速率触发。
本教程介绍如何使用在中 AWS CLI 创建和监控批量组部署 AWS IoT Greengrass。本教程中的批量部署示例包含多个组。您可以在您的实施中使用该示例根据需要添加任意数量的组。
本教程包含以下概括步骤：
1. [创建并上传批量部署输入文件](#bulk-deploy-cli-create-input-file)
1. [创建并配置 IAM 执行角色用于批量部署](#bulk-deploy-cli-create-role)
1. [允许您的执行角色访问您的 S3 存储桶](#bulk-deploy-cli-modify-bucket)
1. [部署组](#bulk-deploy-cli-start-bulk-deployments)
1. [测试部署](#bulk-deploy-cli-test)
## 先决条件
要完成此教程，需要：
+ 一个或多个可部署的 Greengrass 组。有关创建 AWS IoT Greengrass 组和核心的更多信息，请参阅[入门 AWS IoT Greengrass](gg-gs.md)。
+ AWS CLI 已在您的计算机上安装和配置。有关信息，请参阅 [AWS CLI 用户指南](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)。
+ 在相同的 a AWS 区域 s 中创建的 S3 存储桶 AWS IoT Greengrass。有关信息，请参阅 *Amazon Simple Storage Service 用户指南*中的[创建和配置 S3 存储桶](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-configure-bucket.html)。
**注意**
目前，不支持启用了 SSE KMS 的存储桶。
## 步骤 1：创建并上传批量部署输入文件
在此步骤中，您将创建一个部署输入文件并将其上传到您的 Amazon S3 存储桶。此文件是一个以行分隔的序列化的 JSON 文件，其中包含有关批量部署中每个组的信息。 AWS IoT Greengrass 在初始化批量群组部署时，使用此信息代表您部署每个群组。
1. 运行以下命令以获取要部署的每个组的 `groupId`。在批量部署输入文件中输入 `groupId`，让 AWS IoT Greengrass 可以识别要部署的每个组。
**注意**
您也可以在 AWS IoT 控制台中找到这些值。组 ID 显示在组的**设置**页面上。群组版本显示 IDs 在群组的 “**部署**” 选项卡上。
```
aws greengrass list-groups
```
回复中包含有关您 AWS IoT Greengrass 账户中每个群组的信息：
```
{
"Groups": [
{
"Name": "string",
"Id": "string",
"Arn": "string",
"LastUpdatedTimestamp": "string",
"CreationTimestamp": "string",
"LatestVersion": "string",
"LatestVersionArn": "string"
}
],
"NextToken": "string"
}
```
运行以下命令以获取要部署的每个组的 `groupVersionId`。
```
list-group-versions --group-id groupId
```
该响应包含有关组中的所有版本的信息。记下要使用的组版本的 `Version` 值。
```
{
"Versions": [
{
"Arn": "string",
"Id": "string",
"Version": "string",
"CreationTimestamp": "string"
}
],
"NextToken": "string"
}
```
1. 在您选择的计算机终端或编辑器中*MyBulkDeploymentInputFile*，根据以下示例创建一个文件。此文件包含有关要包含在批量部署中的每个 AWS IoT Greengrass 组的信息。虽然此示例定义多个组，但在本教程中，您的文件只能包含一个组。
**注意**
此文件的大小必须小于 100 MB。
```
{"GroupId":"groupId1", "GroupVersionId":"groupVersionId1", "DeploymentType":"NewDeployment"}
{"GroupId":"groupId2", "GroupVersionId":"groupVersionId2", "DeploymentType":"NewDeployment"}
{"GroupId":"groupId3", "GroupVersionId":"groupVersionId3", "DeploymentType":"NewDeployment"}
...
```
每个记录（或行）包含一个组对象。每个组对象包含其相应 `GroupId`、`GroupVersionId` 和 `DeploymentType`。目前，仅 AWS IoT Greengrass 支持`NewDeployment`批量部署类型。
保存并关闭该文件。记下该文件的位置。
1. 在您的终端中使用以下命令将输入文件上传到 Amazon S3 存储桶。将文件路径替换为该文件的位置和名称。有关信息，请参阅[将对象添加到存储桶](https://docs.aws.amazon.com/AmazonS3/latest/gsg/PuttingAnObjectInABucket.html)。
```
aws s3 cp path/MyBulkDeploymentInputFile s3://amzn-s3-demo-bucket/
```
## 步骤 2：创建并配置 IAM 执行角色
在此步骤中，您将使用 IAM 控制台创建一个独立的执行角色。然后，您可以在角色和之间建立信任关系， AWS IoT Greengrass 并确保您的 IAM 用户拥有执行角色的`PassRole`权限。这 AWS IoT Greengrass 允许您担任执行角色并代表您创建部署。
1. 使用以下策略创建一个执行角色。此策略文档允许 AWS IoT Greengrass 在代表您创建每个部署时访问批量部署输入文件。
有关创建 IAM 角色及委派权限的更多信息，请参阅[创建 IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html)。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": "greengrass:CreateDeployment",
"Resource": [
"arn:aws:greengrass:us-east-1:123456789012:/greengrass/groups/groupId1",
"arn:aws:greengrass:us-east-1:123456789012:/greengrass/groups/groupId2",
"arn:aws:greengrass:us-east-1:123456789012:/greengrass/groups/groupId3"
]
}
]
}
```
------
**注意**
此策略必须在批量部署输入文件中包含要由 AWS IoT Greengrass部署的每个组或组版本的资源。要允许访问所有组，请为 `Resource` 指定一个星号：
```
"Resource": ["*"]
```
1. 修改该执行角色的信任关系以包含 AWS IoT Greengrass。这允许 AWS IoT Greengrass 使用该执行角色及向其附加的权限。有关信息，请参阅[编辑现有角色的信任关系](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/edit_trust.html)。
我们建议您在信任策略中加入 `aws:SourceArn` 和 `aws:SourceAccount` 全局条件上下文键，以帮助防止出现*混淆代理人*安全问题。条件上下文键可限制访问权限，仅允许来自指定账户和 Greengrass 工作空间的请求。有关混淆代理人问题的更多信息，请参阅 [防止跨服务混淆代理](cross-service-confused-deputy-prevention.md)。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "greengrass.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:greengrass:us-east-1:123456789012:*"
}
}
}
]
}
```
------
1. 为 IAM 用户赋予执行角色的 IAM `PassRole` 权限。此 IAM 用户是用于启动批量部署的用户。`PassRole` 权限允许您的 IAM 用户将该执行角色传递给 AWS IoT Greengrass 以供使用。有关更多信息，请参阅[向用户授予将角色传递给 AWS 服务的权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_passrole.html)。
使用以下示例更新附加到您的执行角色的 IAM policy。根据需要修改此示例。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Stmt1508193814000",
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": [
"arn:aws:iam::123456789012:user/executionRoleArn"
],
"Condition": {
"StringEquals": {
"iam:PassedToService": "greengrass.amazonaws.com"
}
}
}
]
}
```
------
## 步骤 3：允许您的执行角色访问您的 S3 存储桶
要启动批量部署，您的执行角色必须能够从 Amazon S3 存储桶读取批量部署输入文件。将以下示例策略附加到 Amazon S3 存储桶，这样其 `GetObject` 权限便可供您的执行角色访问。
有关更多信息，请参阅[如何添加 S3 存储桶策略？](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/add-bucket-policy.html)
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id": "examplePolicy",
"Statement": [
{
"Sid": "Stmt1535408982966",
"Effect": "Allow",
"Principal": {
"AWS": [
"executionRoleArn"
]
},
"Action": "s3:GetObject",
"Resource":
"arn:aws:s3:::amzn-s3-demo-bucket/objectKey"
}
]
}
```
------
您可以在终端中使用以下命令检查存储桶的策略：
```
aws s3api get-bucket-policy --bucket amzn-s3-demo-bucket
```
**注意**
您可以直接修改您的执行角色，改为向该角色授予对 Amazon S3 存储桶的 `GetObject` 权限。为此，请将以下示例策略附加到您的执行角色。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/objectKey"
}
]
}
```
## 步骤 4：部署组
在此步骤中，您将对批量部署输入文件中配置的所有组版本启动一个批量部署操作。每个组版本的部署操作均为 `NewDeploymentType` 类型。
**注意**
当同一账户中的其他批量部署仍在运行时，您无法调用 **StartBulkDeployment**。请求被拒绝。
1. 使用以下命令启动批量部署。
我们建议您在每个 **StartBulkDeployment** 请求中包含 `X-Amzn-Client-Token` 令牌。这些请求在令牌和请求参数方面是幂等的。此令牌可以是唯一的、区分大小写的且最多不超过 64 个 ASCII 字符的任意字符串。
```
aws greengrass start-bulk-deployment --cli-input-json "{
"InputFileUri":"URI of file in S3 bucket",
"ExecutionRoleArn":"ARN of execution role",
"AmznClientToken":"your Amazon client token"
}"
```
该命令应生成成功状态代码 `200`，以及以下响应：
```
{
"bulkDeploymentId": UUID
}
```
记下批量部署 ID。它可用于检查批量部署的状态。
**注意**
尽管目前不支持批量部署操作，但您可以创建 Amazon EventBridge 事件规则来获取有关各个群组部署状态变化的通知。有关更多信息，请参阅 [获取部署通知](deployment-notifications.md)。
1. 使用以下命令检查批量部署的状态。
```
aws greengrass get-bulk-deployment-status --bulk-deployment-id 1234567
```
除了 JSON 信息负载之外，该命令还应返回一个成功状态代码 `200`：
```
{
"BulkDeploymentStatus": Running,
"Statistics": {
"RecordsProcessed": integer,
"InvalidInputRecords": integer,
"RetryAttempts": integer
},
"CreatedAt": "string",
"ErrorMessage": "string",
"ErrorDetails": [
{
"DetailedErrorCode": "string",
"DetailedErrorMessage": "string"
}
]
}
```
`BulkDeploymentStatus` 包含批量执行的当前状态。该执行可具有六个不同的状态之一：
+ `Initializing`. 批量部署请求已收到，并且执行正在准备启动。
+ `Running`. 批量部署执行已启动。
+ `Completed`. 批量部署执行已完成所有记录的处理。
+ `Stopping`. 批量部署执行已收到停止命令，并将很快终止。当之前的部署处于 `Stopping` 状态时，您无法启动新的批量部署。
+ `Stopped`. 批量部署执行已手动停止。
+ `Failed`. 批量部署执行遇到了错误并终止。您可以在 `ErrorDetails` 字段中找到错误详细信息。
JSON 负载还包含有关批量部署进度的统计信息。您可以使用此信息确定多少个组已处理以及多少个组已失败。统计信息包含：
+ `RecordsProcessed`：已尝试的组记录的数量。
+ `InvalidInputRecords`：返回了不可重试错误的记录总数。例如，如果输入文件中的组记录使用无效格式或指定不存在的组版本，或者执行未授予部署组或组版本的权限，则可能会发生此错误。
+ `RetryAttempts`：返回了可重试错误的部署尝试次数。例如，如果部署组的尝试返回一个限流错误，则将触发重试。一个组部署最多可重试五次。
如果批量部署执行失败，则此负载还包含一个 `ErrorDetails` 节，可用于排查问题。该节包含有关执行失败原因的信息。
您可以定期检查批量部署的状态，以确认它正在正常进行处理。在部署完成后，`RecordsProcessed` 应等于批量部署输入文件中的部署组的数量。这表示每个记录均已得到处理。
## 步骤 5：测试部署
使用 **ListBulkDeployments** 命令找到批量部署的 ID。
```
aws greengrass list-bulk-deployments
```
此命令会返回所有批量部署的列表（从新到旧），包括 `BulkDeploymentId`。
```
{
"BulkDeployments": [
{
"BulkDeploymentId": 1234567,
"BulkDeploymentArn": "string",
"CreatedAt": "string"
}
],
"NextToken": "string"
}
```
现在，调用 **ListBulkDeploymentDetailedReports** 命令以收集有关每个部署的详细信息。
```
aws greengrass list-bulk-deployment-detailed-reports --bulk-deployment-id 1234567
```
该命令应返回一个成功状态代码 `200` 以及 JSON 信息负载：
```
{
"BulkDeploymentResults": [
{
"DeploymentId": "string",
"GroupVersionedArn": "string",
"CreatedAt": "string",
"DeploymentStatus": "string",
"ErrorMessage": "string",
"ErrorDetails": [
{
"DetailedErrorCode": "string",
"DetailedErrorMessage": "string"
}
]
}
],
"NextToken": "string"
}
```
此负载通常包含每个部署及其部署状态的分页列表（从新到旧）。此外，还包含批量部署执行失败时的更多信息。同样，列出的部署总数应等于批量部署输入文件中标识的组的数量。
返回的信息可能会有所有变化，直到部署处于最终状态（成功或失败）。您可以在此之前定期调用此命令。
## 批量部署问题排查
如果批量部署未成功，您可以尝试以下问题排查步骤。在您的终端中运行命令。
### 排查输入文件错误
如果批量部署输入文件中存在语法错误，则批量部署可能会失败。这会返回批量部署状态 `Failed`，并显示一条错误消息，指出第一个验证错误的行号。有四个可能的错误：
+
```
InvalidInputFile: Missing GroupId at line number: line number
```
此错误指出给定输入文件行无法注册指定的参数。可能缺少参数的是 `GroupId` 和 `GroupVersionId`。
+
```
InvalidInputFile: Invalid deployment type at line number : line number. Only valid type is 'NewDeployment'.
```
此错误指出给定输入文件行列出了无效的部署类型。此时，唯一受支持的部署类型为 `NewDeployment`。
+
```
Line %s is too long in S3 File. Valid line is less than 256 chars.
```
此错误指出给定输入文件行过长，必须缩短。
+
```
Failed to parse input file at line number: line number
```
此错误指出给定输入文件行被视为无效 json。
### 检查是否存在并发批量部署
当其他部署仍在运行或处于非最终状态时，您无法启动新的批量部署。这可能会导致 `Concurrent Deployment Error`。您可以使用 **ListBulkDeployments** 命令来验证批量部署当前是否正在运行。此命令列出您的批量部署（从新到旧）。
```
{
"BulkDeployments": [
{
"BulkDeploymentId": BulkDeploymentId,
"BulkDeploymentArn": "string",
"CreatedAt": "string"
}
],
"NextToken": "string"
}
```
使用第一个列出的批量部署的 `BulkDeploymentId` 运行 **GetBulkDeploymentStatus** 命令。如果最新批量部署处于正在运行状态（`Initializing` 或 `Running`），请使用以下命令停止批量部署。
```
aws greengrass stop-bulk-deployment --bulk-deployment-id BulkDeploymentId
```
此操作会生成 `Stopping` 状态，直到该部署的状态变为 `Stopped`。在该部署达到 `Stopped` 状态后，您便可启动一个新的批量部署。
### 查看 ErrorDetails
运行 `GetBulkDeploymentStatus` 命令以返回一个 JSON 负载，其中包含关于所有批量部署执行失败的详细信息。
```
"Message": "string",
"ErrorDetails": [
{
"DetailedErrorCode": "string",
"DetailedErrorMessage": "string"
}
]
```
如果退出时出现错误，则此调用返回的 `ErrorDetails` JSON 负载包含有关批量部署执行失败的更多信息。例如，`400` 系列中的错误状态代码指示输入参数或调用方依赖项中的输入错误。
### 查看 AWS IoT Greengrass 核心日志
您可以通过查看 AWS IoT Greengrass 核心日志来解决问题。使用以下命令查看 `runtime.log`：
```
cd /greengrass/ggc/var/log
sudo cat system/runtime.log | more
```
有关 AWS IoT Greengrass 日志记录的更多信息，请参阅[使用 AWS IoT Greengrass 日志进行监控](greengrass-logs-overview.md)。
## 另请参阅
有关更多信息，请参阅以下资源：
+ [将 AWS IoT Greengrass 群组部署到 AWS IoT Greengrass 核心](deployments.md)
+ *AWS CLI 命令参考* 中的 [Amazon S3 API 命令](https://docs.aws.amazon.com/cli/latest/reference/s3api)。
+ [AWS IoT Greengrass 命令](https://docs.aws.amazon.com/cli/latest/reference/greengrass/index.html)*参考中的AWS CLI 命令*