教程：开发可推迟组件更新的 Greengrass 组件

在您的开发计算机上，运行以下命令从其安装最新版本的 GDK CLIGitHub知识库。

python3 -m pip install -U git+https://github.com/aws-greengrass/aws-greengrass-gdk-cli.git@v1.3.0

运行以下命令以验证 GDK CLI 是否已成功安装。

gdk --help

如果gdk找不到命令，将其文件夹添加到 PATH。

在开发计算机上，为组件源代码创建一个文件夹。

mkdir com.example.BatteryAwareHelloWorld
cd com.example.BatteryAwareHelloWorld

使用文本编辑器创建名为的文件gdk-config.json。GDK CLI 从GDK CLI 配置文件，被命名为gdk-config.json，用于构建和发布组件。此配置文件存在于组件文件夹的根目录中。

例如，在基于 Linux 的系统上，你可以运行以下命令来使用 GNU nano 来创建文件。

nano gdk-config.json

将以下 JSON 复制到文件中。

{
  "component": {
    "com.example.BatteryAwareHelloWorld": {
      "author": "Amazon",
      "version": "NEXT_PATCH",
      "build": {
        "build_system" : "zip"
      },
      "publish": {
        "region": "us-west-2",
        "bucket": "greengrass-component-artifacts"
      }
    }
  },
  "gdk_version": "1.0.0"
}

配置文件指定了以下内容：

使用文本编辑器在名为的文件中创建组件源代码main.py。

例如，在基于 Linux 的系统上，你可以运行以下命令来使用 GNU nano 来创建文件。

nano main.py

将以下 Python 代码复制到文件中。

import json
import os
import sys
import time
import traceback

from pathlib import Path

from awsiot.greengrasscoreipc.clientv2 import GreengrassCoreIPCClientV2

HELLO_WORLD_PRINT_INTERVAL = 15  # Seconds
DEFER_COMPONENT_UPDATE_INTERVAL = 30 * 1000  # Milliseconds


class BatteryAwareHelloWorldPrinter():
    def __init__(self, ipc_client: GreengrassCoreIPCClientV2, battery_file_path: Path, battery_threshold: float):
        self.battery_file_path = battery_file_path
        self.battery_threshold = battery_threshold
        self.ipc_client = ipc_client
        self.subscription_operation = None

    def on_component_update_event(self, event):
        try:
            if event.pre_update_event is not None:
                if self.is_battery_below_threshold():
                    self.defer_update(event.pre_update_event.deployment_id)
                    print('Deferred update for deployment %s' %
                          event.pre_update_event.deployment_id)
                else:
                    self.acknowledge_update(
                        event.pre_update_event.deployment_id)
                    print('Acknowledged update for deployment %s' %
                          event.pre_update_event.deployment_id)
            elif event.post_update_event is not None:
                print('Applied update for deployment')
        except:
            traceback.print_exc()

    def subscribe_to_component_updates(self):
        if self.subscription_operation == None:
            # SubscribeToComponentUpdates returns a tuple with the response and the operation.
            _, self.subscription_operation = self.ipc_client.subscribe_to_component_updates(
                on_stream_event=self.on_component_update_event)

    def close_subscription(self):
        if self.subscription_operation is not None:
            self.subscription_operation.close()
            self.subscription_operation = None

    def defer_update(self, deployment_id):
        self.ipc_client.defer_component_update(
            deployment_id=deployment_id, recheck_after_ms=DEFER_COMPONENT_UPDATE_INTERVAL)

    def acknowledge_update(self, deployment_id):
        # Specify recheck_after_ms=0 to acknowledge a component update.
        self.ipc_client.defer_component_update(
            deployment_id=deployment_id, recheck_after_ms=0)

    def is_battery_below_threshold(self):
        return self.get_battery_level() < self.battery_threshold

    def get_battery_level(self):
        # Read the battery level from the virtual battery level file.
        with self.battery_file_path.open('r') as f:
            data = json.load(f)
            return float(data['battery_level'])

    def print_message(self):
        message = 'Hello, World!'
        if self.is_battery_below_threshold():
            message += ' Battery level (%d) is below threshold (%d), so the component will defer updates' % (
                self.get_battery_level(), self.battery_threshold)
        else:
            message += ' Battery level (%d) is above threshold (%d), so the component will acknowledge updates' % (
                self.get_battery_level(), self.battery_threshold)
        print(message)


def main():
    # Read the battery threshold and virtual battery file path from command-line args.
    args = sys.argv[1:]
    battery_threshold = float(args[0])
    battery_file_path = Path(args[1])
    print('Reading battery level from %s and deferring updates when below %d' % (
        str(battery_file_path), battery_threshold))

    try:
        # Create an IPC client and a Hello World printer that defers component updates.
        ipc_client = GreengrassCoreIPCClientV2()
        hello_world_printer = BatteryAwareHelloWorldPrinter(
            ipc_client, battery_file_path, battery_threshold)
        hello_world_printer.subscribe_to_component_updates()
        try:
            # Keep the main thread alive, or the process will exit.
            while True:
                hello_world_printer.print_message()
                time.sleep(HELLO_WORLD_PRINT_INTERVAL)
        except InterruptedError:
            print('Subscription interrupted')
        hello_world_printer.close_subscription()
    except Exception:
        print('Exception occurred', file=sys.stderr)
        traceback.print_exc()
        exit(1)


if __name__ == '__main__':
    main()

此 Python 应用程序执行以下操作：

使用文本编辑器在名为的文件中创建组件配方recipe.json要么recipe.yaml。该组件食谱定义组件的元数据、默认配置参数和特定于平台的生命周期脚本。

此食谱指定了以下内容：

有关组件配方的更多信息，请参阅Amazon IoT Greengrass组件配方参考。

运行以下命令使用 GDK CLI 构建组件。这个组件构建命令基于 GDK CLI 配置文件创建配方和构件。在此过程中，GDK CLI 会创建一个包含组件源代码的 ZIP 文件。

gdk component build

您应该看到与以下示例类似的消息。

[2022-04-28 11:20:16] INFO - Getting project configuration from gdk-config.json
[2022-04-28 11:20:16] INFO - Found component recipe file 'recipe.yaml' in the  project directory.
[2022-04-28 11:20:16] INFO - Building the component 'com.example.BatteryAwareHelloWorld' with the given project configuration.
[2022-04-28 11:20:16] INFO - Using 'zip' build system to build the component.
[2022-04-28 11:20:16] WARNING - This component is identified as using 'zip' build system. If this is incorrect, please exit and specify custom build command in the 'gdk-config.json'.
[2022-04-28 11:20:16] INFO - Zipping source code files of the component.
[2022-04-28 11:20:16] INFO - Copying over the build artifacts to the greengrass component artifacts build folder.
[2022-04-28 11:20:16] INFO - Updating artifact URIs in the recipe.
[2022-04-28 11:20:16] INFO - Creating component recipe in 'C:\Users\finthomp\greengrassv2\com.example.BatteryAwareHelloWorld\greengrass-build\recipes'.

运行以下命令将组件发布到Amazon IoT Greengrass云服务。这个组件发布命令将组件的 ZIP 文件构件上传到 S3 存储桶。然后，它在组件配方中更新 ZIP 文件的 S3 URI 并将配方上传到Amazon IoT Greengrass服务。在此过程中，GDK CLI 会检查 Hello World 组件已在哪个版本中可用Amazon IoT Greengrass云服务，因此它可以选择该版本之后的下一个补丁版本。如果该组件尚不存在，则 GDK CLI 使用版本1.0.0。

gdk component publish

您应该看到与以下示例类似的消息。输出告诉你 GDK CLI 创建的组件的版本。

[2022-04-28 11:20:29] INFO - Getting project configuration from gdk-config.json
[2022-04-28 11:20:29] INFO - Found component recipe file 'recipe.yaml' in the  project directory.
[2022-04-28 11:20:29] INFO - Found credentials in shared credentials file: ~/.aws/credentials
[2022-04-28 11:20:30] INFO - No private version of the component 'com.example.BatteryAwareHelloWorld' exist in the account. Using '1.0.0' as the next version to create.
[2022-04-28 11:20:30] INFO - Publishing the component 'com.example.BatteryAwareHelloWorld' with the given project configuration.
[2022-04-28 11:20:30] INFO - Uploading the component built artifacts to s3 bucket.
[2022-04-28 11:20:30] INFO - Uploading component artifacts to S3 bucket: greengrass-component-artifacts-us-west-2-123456789012. If this is your first time using this bucket, add the 's3:GetObject' permission to each core device's token exchange role to allow it to download the component artifacts. For more information, see https://docs.aws.amazon.com/greengrass/v2/developerguide/device-service-role.html.
[2022-04-28 11:20:30] INFO - Not creating an artifacts bucket as it already exists.
[2022-04-28 11:20:30] INFO - Updating the component recipe com.example.BatteryAwareHelloWorld-1.0.0.
[2022-04-28 11:20:31] INFO - Creating a new greengrass component com.example.BatteryAwareHelloWorld-1.0.0
[2022-04-28 11:20:31] INFO - Created private version '1.0.0' of the component in the account.'com.example.BatteryAwareHelloWorld'.

从输出中复制 S3 存储桶名称。稍后您可以使用存储桶名称来允许核心设备从该存储桶下载组件构件。

（可选）在中查看组件Amazon IoT Greengrass控制台验证它是否成功上传。执行以下操作：

1. 在Amazon IoT Greengrass控制台导航菜单，选择组件。

2. 在组件页面，选择我的组件选项卡，然后选择com.example.BatteryAwareHelloWorld。

   在此页面上，您可以看到组件的配方以及有关该组件的其他信息。

允许核心设备访问 S3 存储桶中的组件项目。

每个核心设备都有一个核心设备 IAM 角色这允许它与之互动Amazon IoT并将日志发送到Amazon云。默认情况下，此设备角色不允许访问 S3 存储桶，因此您必须创建并附加允许核心设备从 S3 存储桶检索组件构件的策略。

如果您的设备角色已经允许访问 S3 存储桶，则可以跳过此步骤。否则，创建允许访问的 IAM 策略并将其附加到角色，如下所示：

1. 在IAM 控制台导航菜单，选择政策，然后选择创建策略。

2. 在 JSON 选项卡中，将占位符内容替换为以下策略。替换greengrass-component-artifacts-us-west-2-123456789012使用 GDK CLI 上传组件工件的 S3 存储桶的名称。

   例如，如果你指定了greengrass-component-artifacts和us-west-2在 GDK CLI 配置文件中，而你的Amazon Web Services 账户身份证是123456789012，GDK CLI 使用名为的 S3 存储桶greengrass-component-artifacts-us-west-2-123456789012。

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "s3:GetObject"
         ],
         "Resource": "arn:aws:s3:::greengrass-component-artifacts-us-west-2-123456789012/*"
       }
     ]
   }

3. 选择下一步。

4. 在政策详情部分，对于姓名，输入MyGreengrassV2ComponentArtifactPolicy。

5. 选择 Create policy（创建策略）。

6. 在IAM 控制台导航菜单，选择角色，然后为核心设备选择角色的名称。您在安装时指定了此角色名称Amazon IoT Greengrass核心软件。如果您未指定名称，则默认为GreengrassV2TokenExchangeRole。

7. 下权限，选择添加权限，然后选择附加政策。

8. 在添加权限页面，选中旁边的复选框MyGreengrassV2ComponentArtifactPolicy您创建的策略，然后选择添加权限。

使用文本编辑器创建虚拟电池电量文件。这个文件模仿了真正的电池。

例如，在基于 Linux 的系统上，你可以运行以下命令来使用 GNU nano 来创建文件。

sudo nano /home/ggc_user/virtual_battery.json

将以下 JSON 复制到文件中。

{
  "battery_level": 50
}

将 Hello World 组件部署到核心设备。执行以下操作：

1. 在Amazon IoT Greengrass控制台导航菜单，选择组件。

2. 在组件页面，选择我的组件选项卡，然后选择com.example.BatteryAwareHelloWorld。

3. 在com.example.BatteryAwareHelloWorld页面，选择部署。

4. 来自添加到部署，选择要修改的现有部署，或者选择创建新部署，然后选择下一步。

5. 如果您选择创建新部署，请为部署选择目标核心设备或事物组。在指定目标页面，下方部署目标，选择核心设备或事物组，然后选择下一步。

6. 在选择组件页面，验证com.example.BatteryAwareHelloWorld组件被选中，选择下一步。

7. 在配置组件页面，选择com.example.BatteryAwareHelloWorld，然后执行以下操作：

   1. 选择配置组件。

   2. 在配置com.example.BatteryAwareHelloWorld模态，低于配置更新，在要合并的配置，输入以下配置更新。

      {
        "BatteryThreshold": 70
      }

   3. 选择确认关闭模态，然后选择下一步。

8. 在确认高级设置页面，在部署策略部分，下方组件更新政策，确认通知组件被选中。通知组件创建新部署时默认处于选中状态。

9. 在 Review（检查）页上，选择 Deploy（部署）。

   部署最多可能需要一分钟才能完成。

这个Amazon IoT Greengrass核心软件将 stdout 从组件进程保存到日志文件中logs文件夹。运行以下命令以验证 Hello World 组件是否运行并打印状态消息。

您应该看到与以下示例类似的消息。

Hello, World! Battery level (50) is below threshold (70), so the component will defer updates.

为核心设备创建新的部署，以验证该组件是否推迟更新。执行以下操作：

1. 在Amazon IoT Greengrass控制台导航菜单，选择部署。

2. 选择您之前创建或修改的部署。

3. 在部署页面上，选择修改。

4. 在修改部署模态，选择修改部署。

5. 选择下一步在每一步中，然后选择部署。

运行以下命令以再次查看组件的日志，并验证其是否推迟更新。

您应该看到与以下示例类似的消息。该组件将更新推迟 30 秒，因此该组件会重复打印此消息。

Deferred update for deployment 50722a95-a05f-4e2a-9414-da80103269aa.

使用文本编辑器编辑虚拟电池电量文件并将电池电量更改为高于阈值的值，这样部署就可以继续了。

例如，在基于 Linux 的系统上，你可以运行以下命令来使用 GNU nano 来创建文件。

sudo nano /home/ggc_user/virtual_battery.json

将电池电量更改为80。

{
  "battery_level": 80
}

运行以下命令再次查看组件的日志，并验证其是否确认更新。

您应该看到与以下示例类似的消息。

Hello, World! Battery level (80) is above threshold (70), so the component will acknowledge updates.
Acknowledged update for deployment f9499eb2-4a40-40a7-86c1-c89887d859f1.