使用 Amazon 用于部署常见远程操作的托管模板

Amazon 托管模板是由提供的作业模板 Amazon。这些任务模板用于频繁执行的远程操作，例如重启、下载文件或在设备上安装应用程序。这些模板具有用于每个远程操作的预定义任务文档，因此您无需创建自己的任务文档。

您可以从一组预定义的配置中进行选择，并使用这些模板创建任务，而无需编写任何其他代码使用托管模板，您可以查看部署到机群的任务文档。您可以使用这些模板创建任务，然后创建可以重复用于远程操作的自定义任务模板。

托管模板包含哪些内容？

每个 Amazon 托管模板都包含：

在任务文档中运行命令的环境。
指定操作名称及其参数的任务文档。例如，如果您使用下载文件模板，操作名称是下载文件，参数可以是：
- 要下载到设备的文件的 URL。这可以是互联网资源，也可以是公共或预签名 Amazon Simple Storage Service (Amazon S3) URL。
- 设备上用于存储下载文件的本地文件路径。
有任务文档及其参数的更多信息，请参阅托管模板远程操作和任务文档。

先决条件

要使设备运行托管模板任务文档指定的远程操作，您必须：

在设备上安装特定软件

使用您自己的设备软件和任务处理程序，或 Amazon IoT 设备客户端。根据您的业务案例，您也可以同时运行它们，以使它们执行不同的功能。
- 使用您自己的设备软件和任务处理程序
  
  您可以使用 Amazon IoT Device SDK 及其支持远程操作的处理程序库为设备编写自己的代码。要部署和运行任务，请验证设备代理库已正确安装并正在这些设备上运行。
  
  您也可以选择使用自己的支持远程操作的处理程序。有关更多信息，请参阅 Amazon IoT 设备客户端 GitHub存储库中的示例任务处理程序。
- 使用 Amazon IoT 设备客户端
  
  或者，你可以在设备上安装和运行 Amazon IoT 设备客户端，因为默认情况下，它支持直接从控制台使用所有托管模板。
  
  设备客户端是用 C++ 编写的开源软件，您可以编译并安装在嵌入式 Linux-based 物联网设备上。Device Client 有基本客户端和离散的客户端特征。基础客户端 Amazon IoT 通过 MQTT 协议与之建立连接，并且可以连接不同的客户端功能。
  
  要在设备上执行远程操作，请使用 Device Client 的客户端任务特征。此特征包含一个用于接收任务文档的解析器以及实现任务文档中指定的远程操作的任务处理程序。有关Device Client 及其特征的更多信息，请参阅 Amazon IoT Device Client。
  
  在设备上运行时，Device Client 会收到任务文档，并具有用于在文档中运行命令的特定于平台的实现。有关设置 Device Client 和使用任务特征的详细信息，请参阅 Amazon IoT 教程。
使用支持的环境

对于每个托管模板，您将找到有关可用于运行远程操作的环境信息。我们建议您将模板与模板中指定的受支持的 Linux 环境结合使用。使用 Amazon IoT 设备客户端运行托管模板远程操作，因为它支持常见的微处理器和 Linux 环境，如 Debian 和 Ubuntu。

托管模板远程操作和任务文档

下一节列出了 Amazon IoT 任务的不同 Amazon 托管模板，并描述了可以在设备上执行的远程操作。以下章节提供有关任务文档的信息以及每个远程操作的任务文档参数的描述。设备端软件使用模板名称和参数来执行远程操作。

Amazon 托管模板接受您在使用模板创建作业时为其指定值的输入参数。所有托管式模板都有以下两个共同的可选输入参数：runAsUser 和 pathToHandler。除了 AWS-Reboot 模板时，模板需要额外的输入参数，在使用模板创建任务时必须为这些参数指定值。这些所需的输入参数因您所选的模板而异。例如，如果您选择 AWS-Download-File 模板，则必须指定要安装的软件包列表以及从中下载文件的 URL。

使用 Amazon IoT 控制台或 Amazon Command Line Interface (Amazon CLI) 创建使用托管模板的任务时为输入参数指定值。使用 CLI 时，可以使用 document-parameters 对象提供这些值。有关更多信息，请参阅文档参数。

注意

仅当从 Amazon 托管式模板创建任务时，才使用 document-parameters。此参数不能与自定义任务模板一起使用，也不能从中创建作业。

下面显示了常见可选输入参数的说明。您将在下一节中看到每个托管式模板所需的其它输入参数的说明。

runAsUser: 此参数指定是否以其他用户身份运行任务处理程序。如果在任务创建过程中未指定，任务处理程序将以与 Device Client 相同的用户身份运行。当您以其他用户身份运行任务处理程序时，请指定不超过 256 个字符的字符串值。

pathToHandler: 设备上运行的任务处理程序的路径。如果在创建任务时未指定它，Device Client 将使用当前工作目录。

下面显示了不同的远程操作、其任务文档以及它们接受的参数。所有这些模板都支持在设备上运行远程操作的 Linux 环境。

模板名称

Amazon–Download–File

模板描述

提供的 Amazon 用于下载文件的托管模板。

输入参数

此模板具有以下必需参数。您还可以指定可选参数 runAsUser 和 pathToHandler

downloadUrl: 从中下载文件的 URL。这可以是互联网资源、Amazon S3 中可公开访问的对象，也可以是 Amazon S3 中只能由设备使用预签名 URL 访问的对象。有关使用预签名 URL 和授予权限的详细信息，请参阅预签名 URL。
filePath: 本地文件路径，显示设备中存储下载文件的位置。

设备的行为

设备从指定位置下载文件，验证下载完成并将其存储在本地。

任务文档

下面显示了任务文档及其最新版本。模板显示了任务处理程序和 shell 脚本的路径，download-file.sh，必须运行任务处理程序才能下载文件。它还显示了必需参数 downloadUrl 和 filePath。


{
  "version": "1.0",
  "steps": [
    {
      "action": {
        "name": "Download-File",
        "type": "runHandler",
        "input": {
          "handler": "download-file.sh",
          "args": [
            "${aws:iot:parameter:downloadUrl}",
            "${aws:iot:parameter:filePath}"
          ],
          "path": "${aws:iot:parameter:pathToHandler}"
        },
        "runAsUser": "${aws:iot:parameter:runAsUser}"
      }
    }
  ]
}

模板名称

Amazon–Install–Application

模板描述

Amazon 为安装一个或多个应用程序而提供的托管模板。

输入参数

此模板具有以下必需参数，packages。您还可以指定可选参数 runAsUser 和 pathToHandler

packages

要安装的一个或多个应用程序列表，以空格分隔。

设备的行为

设备将按照任务文档中的指定安装应用程序。

任务文档

下面显示了任务文档及其最新版本。模板显示了任务处理程序和 shell 脚本的路径，install-packages.sh，必须运行任务处理程序才能下载文件。它还显示必需参数 packages。


{
  "version": "1.0",
  "steps": [
    {
      "action": {
        "name": "Install-Application",
        "type": "runHandler",
        "input": {
          "handler": "install-packages.sh",
          "args": [
            "${aws:iot:parameter:packages}"
          ],
          "path": "${aws:iot:parameter:pathToHandler}"
        },
        "runAsUser": "${aws:iot:parameter:runAsUser}"
      }
    }
  ]
}

模板名称

Amazon–Reboot

模板描述

提供的 Amazon 用于重启设备的托管模板。

输入参数

此模板没有必需参数。但是，您可以指定可选参数 runAsUser 和 pathToHandler。

设备的行为

设备已成功重新启动。

任务文档

下面显示了任务文档及其最新版本。模板显示了任务处理程序和 shell 脚本的路径，reboot.sh，必须运行任务处理程序才能重新启动设备。


{
  "version": "1.0",
  "steps": [
    {
      "action": {
        "name": "Reboot",
        "type": "runHandler",
        "input": {
          "handler": "reboot.sh",
          "path": "${aws:iot:parameter:pathToHandler}"
        },
        "runAsUser": "${aws:iot:parameter:runAsUser}"
      }
    }
  ]
}

模板名称

Amazon–Remove–Application

模板描述

Amazon 为卸载一个或多个应用程序而提供的托管模板。

输入参数

此模板具有以下必需参数，packages。您还可以指定可选参数 runAsUser 和 pathToHandler

packages

要卸载的一个或多个应用程序列表，以空格分隔。

设备的行为

设备将按照任务文档中的指定卸载应用程序。

任务文档

下面显示了任务文档及其最新版本。模板显示了任务处理程序和 shell 脚本的路径，remove-packages.sh，必须运行任务处理程序才能下载文件。它还显示必需参数 packages。


{
  "version": "1.0",
  "steps": [
    {
      "action": {
        "name": "Remove-Application",
        "type": "runHandler",
        "input": {
          "handler": "remove-packages.sh",
          "args": [
            "${aws:iot:parameter:packages}"
          ],
          "path": "${aws:iot:parameter:pathToHandler}"
        },
        "runAsUser": "${aws:iot:parameter:runAsUser}"
      }
    }
  ]
}

模板名称

Amazon–Restart–Application

模板描述

Amazon 为停止和重启一项或多项服务而提供的托管模板。

输入参数

此模板具有以下必需参数，services。您还可以指定可选参数 runAsUser 和 pathToHandler

服务

将重新启动的一个或多个应用程序列表，以空格分隔。

设备的行为

指定的应用程序停止然后在设备上重新启动。

任务文档

下面显示了任务文档及其最新版本。模板显示了任务处理程序和 shell 脚本的路径，restart-services.sh，必须运行任务处理程序才能重新启动系统服务。它还显示必需参数 services。


{
  "version": "1.0",
  "steps": [
    {
      "action": {
        "name": "Restart-Application",
        "type": "runHandler",
        "input": {
          "handler": "restart-services.sh",
          "args": [
            "${aws:iot:parameter:services}"
          ],
          "path": "${aws:iot:parameter:pathToHandler}"
        },
        "runAsUser": "${aws:iot:parameter:runAsUser}"
      }
    }
  ]
}

模板名称

Amazon-Start-Application

模板描述

Amazon 为启动一项或多项服务而提供的托管模板。

输入参数

此模板具有以下必需参数，services。您还可以指定可选参数 runAsUser 和 pathToHandler

services

将启动的一个或多个应用程序列表，以空格分隔。

设备的行为

指定的应用程序开始在设备上运行。

任务文档

下面显示了任务文档及其最新版本。模板显示了任务处理程序和 shell 脚本的路径，start-services.sh，必须运行任务处理程序才能启动系统服务。它还显示必需参数 services。


{
  "version": "1.0",
  "steps": [
    {
      "action": {
        "name": "Start-Application",
        "type": "runHandler",
        "input": {
          "handler": "start-services.sh",
          "args": [
            "${aws:iot:parameter:services}"
          ],
          "path": "${aws:iot:parameter:pathToHandler}"
        },
        "runAsUser": "${aws:iot:parameter:runAsUser}"
      }
    }
  ]
}

模板名称

Amazon–Stop–Application

模板描述

Amazon 为停止一项或多项服务而提供的托管模板。

输入参数

此模板具有以下必需参数，services。您还可以指定可选参数 runAsUser 和 pathToHandler

services

将停止的一个或多个应用程序列表，以空格分隔。

设备的行为

指定的应用程序停止在设备上运行。

任务文档

下面显示了任务文档及其最新版本。模板显示了任务处理程序和 shell 脚本的路径，stop-services.sh，必须运行任务处理程序才能停止系统服务。它还显示必需参数 services。


{
  "version": "1.0",
  "steps": [
    {
      "action": {
        "name": "Stop-Application",
        "type": "runHandler",
        "input": {
          "handler": "stop-services.sh",
          "args": [
            "${aws:iot:parameter:services}"
          ],
          "path": "${aws:iot:parameter:pathToHandler}"
        },
        "runAsUser": "${aws:iot:parameter:runAsUser}"
      }
    }
  ]
}

模板名称

Amazon–Run–Command

模板描述

Amazon 为运行 shell 命令而提供的托管模板。

输入参数

此模板具有以下必需参数，command。您还可以指定可选参数 runAsUser。

command

以逗号分隔的命令字符串。必须对命令本身中包含的任何逗号进行转义。

设备的行为

设备按照任务文档中的指定运行 shell 命令。

任务文档

下面显示了任务文档及其最新版本。此模板显示任务命令的路径，以及您提供的且设备将运行的命令。


{
  "version": "1.0",
  "steps": [
    {
      "action": {
        "name": "Run-Command",
        "type": "runCommand",
        "input": {
          "command": "${aws:iot:parameter:command}"
        },
        "runAsUser": "${aws:iot:parameter:runAsUser}"
      }
    }
  ]
}

主题

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

作业模板

使用控制台从 Amazon 托管模板创建作业