终止支持通知：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)。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 为组创建批量部署
您可以使用简单 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 命令*