支援終止通知：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)相關文章。
+ 在相同 中建立的 S3 儲存貯體 AWS 區域 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 會顯示在群組的 **Settings (設定)** 頁面上。群組版本 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 `PassRole`許可授予您的 IAM 使用者。此 IAM 使用者是用來啟動大量部署的使用者。 `PassRole`許可可讓您的 IAM 使用者將您的執行角色傳遞給 AWS IoT Greengrass 以供使用。如需詳細資訊，請參閱[授予使用者將角色傳遞至 AWS 服務的許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_passrole.html)。
使用下列範例來更新連接至執行角色的 IAM 政策。視需要修改此範例。
------
#### [ 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
```
除了 JSON 承載資訊，此命令還應該會傳回成功狀態碼 `200`：
```
{
"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)
+ 《 [命令參考》中的 Amazon S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api) 命令 *AWS CLI *
+ [AWS IoT Greengrass 命令](https://docs.aws.amazon.com/cli/latest/reference/greengrass/index.html)*AWS CLI 參考中的 命令*