创建 Amazon IoT Greengrass 组件 - Amazon IoT Greengrass
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

创建 Amazon IoT Greengrass 组件

您可以在本地开发计算机或 Greengrass 核心设备上开发自定义 Amazon IoT Greengrass 组件。 Amazon IoT Greengrass 提供了Amazon IoT Greengrass 开发套件命令行界面 (GDK CLI),可帮助您根据预定义的组件模板和社区组件创建、生成发布组件。您还可以运行内置的 shell 命令来创建、生成和发布组件。从以下选项中进行选择以创建自定义 Greengrass 组件:

  • 使用 Greengrass 开发套件 CLI

    使用 GDK CLI 在本地开发计算机上开发组件。GDK CLI 构建组件源代码并将其打包为配方和工件,您可以将其作为私有组件发布到该 Amazon IoT Greengrass 服务。您可以将 GDK CLI 配置为在发布组件时自动更新组件的版本和工件 URI,因此无需每次都更新配方。要使用 GDK CLI 开发组件,可以从 Gre engrass 软件目录中的模板或社区组件开始。有关更多信息,请参阅Amazon IoT Greengrass开发套件命令行界面

  • 运行内置 shell 命令

    您可以运行内置的 shell 命令在本地开发计算机或 Greengrass 核心设备上开发组件。您可以使用 shell 命令将组件源代码复制或构建到工件中。每次创建组件的新版本时,都必须使用新的组件版本创建或更新配方。将组件发布到 Amazon IoT Greengrass 服务时,必须更新配方中每个组件工件的 URI。

创建组件 (GDK CLI)

按照本节中的说明使用 GDK CLI 创建和构建组件。

开发 Greengrass 组件 (GDK CLI)
  1. 如果尚未安装 GDK CLI,请在开发计算机上安装 GDK CLI。有关更多信息,请参阅安装或更新Amazon IoT Greengrass开发套件命令行界面

  2. 切换到要在其中创建组件文件夹的文件夹。

    Linux or Unix
    mkdir ~/greengrassv2 cd ~/greengrassv2
    Windows Command Prompt (CMD)
    mkdir %USERPROFILE%\greengrassv2 cd %USERPROFILE%\greengrassv2
    PowerShell
    mkdir ~/greengrassv2 cd ~/greengrassv2
  3. 选择要下载的组件模板或社区组件。GDK CLI 下载模板或社区组件,因此您可以从功能示例开始。使用组件列表命令检索可用模板或社区组件的列表。

    • 要列出组件模板,请运行以下命令。响应中的每一行都包含模板的名称和编程语言。

      gdk component list --template
    • 要列出社区组件,请运行以下命令。

      gdk component list --repository
  4. 创建并更改为 GDK CLI 下载模板或社区组件的组件文件夹。HelloWorld替换为组件的名称或其他可帮助您识别此组件文件夹的名称。

    Linux or Unix
    mkdir HelloWorld cd HelloWorld
    Windows Command Prompt (CMD)
    mkdir HelloWorld cd HelloWorld
    PowerShell
    mkdir HelloWorld cd HelloWorld
  5. 将模板或社区组件下载到当前文件夹。使用组件 init 命令。

    • 要使用模板创建组件文件夹,请运行以下命令。HelloWorld替换为模板的名称,并将 python 替换为编程语言的名称。

      gdk component init --template HelloWorld --language python
    • 要从社区组件创建组件文件夹,请运行以下命令。ComponentName替换为社区组件的名称。

      gdk component init --repository ComponentName
    注意

    如果您使用 GDK CLI v1.0.0,则必须在空文件夹中运行此命令。GDK CLI 会将模板或社区组件下载到当前文件夹。

    如果您使用 GDK CLI v1.1.0 或更高版本,则可以指定--name参数来指定 GDK CLI 下载模板或社区组件的文件夹。如果使用此参数,请指定一个不存在的文件夹。GDK CLI 会为您创建文件夹。如果您未指定此参数,GDK CLI 将使用当前文件夹,该文件夹必须为空。

  6. GDK CLI 从名为 GDK CLI 的配置文件中读取数据gdk-config.json,以构建和发布组件。此配置文件存在于组件文件夹的根目录中。上一步将为您创建此文件。在此步骤中,您将gdk-config.json使用有关组件的信息进行更新。执行以下操作:

    1. 在文本编辑器中打开 gdk-config.json

    2. (可选)更改组件的名称。组件名称是component对象中的关键。

    3. 更改组件的作者。

    4. (可选)更改组件的版本。指定下列项之一:

      • NEXT_PATCH— 当您选择此选项时,GDK CLI 将在您发布组件时设置版本。GDK CLI 会查询 Amazon IoT Greengrass 服务以识别该组件的最新发布版本。然后,它将版本设置为该版本之后的下一个补丁版本。如果您之前没有发布过该组件,GDK CLI 将使用版本1.0.0

        如果选择此选项,则无法使用 Greengrass CLI 在本地部署该组件并将其测试到运行 Core 软件的本地开发计算机上。 Amazon IoT Greengrass 要启用本地部署,必须改为指定语义版本。

      • 语义版本,例如。1.0.0语义版本使用主调未成年人补丁编号系统。有关更多信息,请参阅语义版本规范

        如果您在 Greengrass 核心设备上开发要部署和测试该组件的组件,请选择此选项。要使用 Greengr ass CLI 创建本地部署,必须使用特定版本构建组件。

    5. (可选)更改组件的编译配置。构建配置定义了 GDK CLI 如何将组件的源代码构建为工件。从以下选项中进行选择build_system

      • zip— 将组件的文件夹打包为 ZIP 文件以定义为该组件的唯一构件。为以下类型的组件选择此选项:

        • 使用解释型编程语言的组件,例如 Python 或 JavaScript。

        • 打包除代码之外的文件的组件,例如机器学习模型或其他资源。

        GDK CLI 将组件的文件夹压缩为与组件文件夹同名的 zip 文件。例如,如果组件文件夹的名称为HelloWorld,则 GDK CLI 会创建一个名HelloWorld.zip为的 zip 文件。

        注意

        如果您在 Windows 设备上使用 GDK CLI 版本 1.0.0,则组件文件夹和 zip 文件名必须仅包含小写字母。

        当 GDK CLI 将组件的文件夹压缩为 zip 文件时,它会跳过以下文件:

        • gdk-config.json 文件

        • 配方文件(recipe.jsonrecipe.yaml

        • 生成文件夹,例如 greengrass-build

      • maven— 运行mvn clean package命令将组件的源代码构建为工件。对于使用 Mave n 的组件(例如 Java 组件),请选择此选项。

        在 Windows 设备上,此功能适用于 GDK CLI v1.1.0 及更高版本。

      • gradle— 运行gradle build命令将组件的源代码构建为工件。对于使用 Gradle 的组件,请选择此选项。此功能适用于 GDK CLI 版本 1.1.0 及更高版本。

        gradle译系统支持 Kotlin DSL 作为构建文件。此功能适用于 GDK CLI 版本 1.2.0 及更高版本。

      • gradlew— 运行gradlew命令将组件的源代码构建为工件。对于使用 Gradle 包装器的组件,请选择此选项。

        此功能适用于 GDK CLI 版本 1.2.0 及更高版本。

      • custom— 运行自定义命令将组件的源代码构建为配方和工件。在custom_build_command参数中指定自定义命令。

    6. 如果您custom为指定build_system,请将custom_build_command添加到build对象中。在中custom_build_command,指定单个字符串或字符串列表,其中每个字符串都是命令中的一个单词。例如,要为 C++ 组件运行自定义生成命令,可以指定["cmake", "--build", "build", "--config", "Release"]

    7. 如果您使用 GDK CLI v1.1.0 或更高版本,则可以指定--bucket参数来指定 GDK CLI 上传组件工件的 S3 存储桶。如果您不指定此参数,GDK CLI 会上传到名称为bucket-region-accountId、其中存储段和区域是您在中gdk-config.json指定的值,accountID 是您的 ID。 Amazon Web Services 账户 如果存储桶不存在,GDK CLI 会创建该存储桶。

      更改组件的发布配置。执行以下操作:

      1. 指定用于托管组件工件的 S3 存储桶的名称。

      2. 指定 GDK CLI 发布组件 Amazon Web Services 区域 的位置。

    完成此步骤后,gdk-config.json文件可能与以下示例类似。

    { "component": { "com.example.PythonHelloWorld": { "author": "Amazon", "version": "NEXT_PATCH", "build": { "build_system" : "zip" }, "publish": { "bucket": "greengrass-component-artifacts", "region": "us-west-2" } } }, "gdk_version": "1.0.0" }
  7. 更新名为recipe.yaml或的组件配方文件recipe.json。执行以下操作:

    1. 如果您下载了使用编zip译系统的模板或社区组件,请检查 zip 工件名称是否与组件文件夹的名称相匹配。GDK CLI 将组件文件夹压缩为与组件文件夹同名的 zip 文件。该配方在组件工件列表和使用 zip 构件中文件的生命周期脚本中包含 zip 工件名称。更新ArtifactsLifecycle定义,使 zip 文件名与组件文件夹的名称相匹配。以下部分配方示例突出显示了ArtifactsLifecycle定义中的 zip 文件名。

      JSON
      { ... "Manifests": [ { "Platform": { "os": "all" }, "Artifacts": [ { "URI": "s3://{COMPONENT_NAME}/{COMPONENT_VERSION}/HelloWorld.zip", "Unarchive": "ZIP" } ], "Lifecycle": { "run": "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}" } } ] }
      YAML
      --- ... Manifests: - Platform: os: all Artifacts: - URI: "s3://BUCKET_NAME/COMPONENT_NAME/COMPONENT_VERSION/HelloWorld.zip" Unarchive: ZIP Lifecycle: run: "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}"
    2. (可选)更新组件描述、默认配置、构件、生命周期脚本和平台支持。有关更多信息,请参阅Amazon IoT Greengrass 组件配方参考

    完成此步骤后,配方文件可能与以下示例类似。

    JSON
    { "RecipeFormatVersion": "2020-01-25", "ComponentName": "{COMPONENT_NAME}", "ComponentVersion": "{COMPONENT_VERSION}", "ComponentDescription": "This is a simple Hello World component written in Python.", "ComponentPublisher": "{COMPONENT_AUTHOR}", "ComponentConfiguration": { "DefaultConfiguration": { "Message": "World" } }, "Manifests": [ { "Platform": { "os": "all" }, "Artifacts": [ { "URI": "s3://{COMPONENT_NAME}/{COMPONENT_VERSION}/HelloWorld.zip", "Unarchive": "ZIP" } ], "Lifecycle": { "run": "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}" } } ] }
    YAML
    --- RecipeFormatVersion: "2020-01-25" ComponentName: "{COMPONENT_NAME}" ComponentVersion: "{COMPONENT_VERSION}" ComponentDescription: "This is a simple Hello World component written in Python." ComponentPublisher: "{COMPONENT_AUTHOR}" ComponentConfiguration: DefaultConfiguration: Message: "World" Manifests: - Platform: os: all Artifacts: - URI: "s3://BUCKET_NAME/COMPONENT_NAME/COMPONENT_VERSION/HelloWorld.zip" Unarchive: ZIP Lifecycle: run: "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}"
  8. 开发和构建 Greengrass 组件。组件构建命令会在组件文件夹的greengrass-build文件夹中生成配方和工件。运行以下命令。

    gdk component build

当您准备好测试组件时,请使用 GDK CLI 将其发布到 Amazon IoT Greengrass 服务。然后,您可以将该组件部署到 Greengrass 核心设备上。有关更多信息,请参阅发布组件以部署到您的核心设备

创建组件(外壳命令)

按照本节中的说明创建包含多个组件源代码和构件的配方和构件文件夹。

开发 Greengrass 组件(外壳命令)
  1. 为您的组件创建一个文件夹,其中包含用于存放配方和工件的子文件夹。在 Greengrass 核心设备上运行以下命令来创建这些文件夹并切换到组件文件夹。将 ~/greengrassv2 或 %USERPROFILE%\ greengrassv2 替换为用于本地开发的文件夹的路径。

    Linux or Unix
    mkdir -p ~/greengrassv2/{recipes,artifacts} cd ~/greengrassv2
    Windows Command Prompt (CMD)
    mkdir %USERPROFILE%\greengrassv2\\recipes, %USERPROFILE%\greengrassv2\\artifacts cd %USERPROFILE%\greengrassv2
    PowerShell
    mkdir ~/greengrassv2/recipes, ~/greengrassv2/artifacts cd ~/greengrassv2
  2. 使用文本编辑器创建用于定义组件元数据、参数、依赖关系、生命周期和平台功能的配方文件。在配方文件名中包含组件版本,这样您就可以确定哪个配方反映了哪个组件版本。你可以为你的食谱选择 YAML 或 JSON 格式。

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

    JSON
    nano recipes/com.example.HelloWorld-1.0.0.json
    YAML
    nano recipes/com.example.HelloWorld-1.0.0.yaml
    注意

    Amazon IoT Greengrass 使用组件的语义版本。语义版本遵循 major.minor.patch 编号系统。例如,版本1.0.0表示组件的第一个主要版本。有关更多信息,请参阅语义版本规范

  3. 为您的组件定义配方。有关更多信息,请参阅Amazon IoT Greengrass 组件配方参考

    您的食谱可能与以下 Hello World 示例食谱类似。

    JSON
    { "RecipeFormatVersion": "2020-01-25", "ComponentName": "com.example.HelloWorld", "ComponentVersion": "1.0.0", "ComponentDescription": "My first Amazon IoT Greengrass component.", "ComponentPublisher": "Amazon", "ComponentConfiguration": { "DefaultConfiguration": { "Message": "world" } }, "Manifests": [ { "Platform": { "os": "linux" }, "Lifecycle": { "run": "python3 -u {artifacts:path}/hello_world.py {configuration:/Message}" } }, { "Platform": { "os": "windows" }, "Lifecycle": { "run": "py -3 -u {artifacts:path}/hello_world.py {configuration:/Message}" } } ] }
    YAML
    --- RecipeFormatVersion: '2020-01-25' ComponentName: com.example.HelloWorld ComponentVersion: '1.0.0' ComponentDescription: My first Amazon IoT Greengrass component. ComponentPublisher: Amazon ComponentConfiguration: DefaultConfiguration: Message: world Manifests: - Platform: os: linux Lifecycle: run: | python3 -u {artifacts:path}/hello_world.py "{configuration:/Message}" - Platform: os: windows Lifecycle: run: | py -3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"

    此配方运行一个 Hello World Python 脚本,该脚本可能与以下示例脚本类似。

    import sys message = "Hello, %s!" % sys.argv[1] # Print the message to stdout, which Greengrass saves in a log file. print(message)
  4. 为要开发的组件版本创建文件夹。我们建议您为每个组件版本的构件使用单独的文件夹,以便可以识别每个组件版本的构件。运行以下命令。

    Linux or Unix
    mkdir -p artifacts/com.example.HelloWorld/1.0.0
    Windows Command Prompt (CMD)
    mkdir artifacts/com.example.HelloWorld/1.0.0
    PowerShell
    mkdir artifacts/com.example.HelloWorld/1.0.0
    重要

    必须使用以下格式作为构件文件夹路径。包括您在配方中指定的组件名称和版本。

    artifacts/componentName/componentVersion/
  5. 在上一步中创建的文件夹中为您的组件创建构件。构件可以包括软件、图像和组件使用的任何其他二进制文件。

    组件准备就绪后,测试您的组件