使用 AWS 受管理的範本部署常見的遠端作業 - AWS IoT Core
受管範本包含哪些內容？必要條件受管範本遠端動作和任務文件

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 AWS 受管理的範本部署常見的遠端作業

AWS 受管理的範本是由提供的工作範本 AWS。它們用於經常執行的遠端動作，例如重新啟動、下載檔案或在裝置上安裝應用程式。這些範本具有適用於每個遠端動作的預先定義任務文件，無需您建立自己的任務文件。

您可以從一組預先定義的組態中進行選擇，並使用這些範本建立任務，而無需撰寫任何其他程式碼。使用受管範本，您可以檢視部署至機群的任務文件。您可以使用這些範本來建立任務，並建立可重複使用於遠端操作的自訂任務範本。

受管範本包含哪些內容？

每個 AWS 受管理的範本包含：

  • 在任務文件中執行命令的環境。

  • 指定操作名稱及其參數的任務文件。例如，如果使用 Download file (下載檔案) 範本，操作名稱為 Download file 並且參數可以是：

    • 您要下載至裝置的檔案 URL。這可以是網際網路資源，也可以是公有或預先簽章的 Amazon Simple Storage Service (Amazon S3) URL。

    • 裝置上用來存放下載檔案的本機檔案路徑。

    如需有關任務文件及其參數的詳細資訊，請參閱 受管範本遠端動作和任務文件。

必要條件

若要讓裝置執行受管範本任務文件指定的遠端操作，必須：

  • 在裝置上安裝特定軟體

    使用您自己的裝置軟體和工作處理常式，或 AWS IoT 裝置用戶端。根據您的業務案例，您也可以同時執行它們，以便它們執行不同的功能。

    • 使用自有裝置軟體和任務處理常式

      您可以使用 AWS IoT Device SDK 及其支援遠端操作的處理常式程式庫，為裝置撰寫自己的程式碼。若要部署和執行任務，請驗證裝置代理程式程式庫是否已正確安裝，且正在裝置上執行。

      您也可以選擇使用自己的處理常式來支援遠端操作。如需詳細資訊，請參閱 AWS IoT 裝置用戶端 GitHub儲存庫中的範例工作處理常式。

    • 使用 AWS IoT 裝置用戶端

      或者，您可以在裝置上安裝並執行裝 AWS IoT 置用戶端，因為它預設支援直接從主控台使用所有受管理的範本。

      裝置用戶端是以 C++ 撰寫的開放原始碼軟體，可供您在內嵌 Linux 型 IoT 裝置上編譯並安裝。裝置用戶端具有基礎用戶端和分散的用戶端功能。基礎用戶端可建立透 AWS IoT 過 MQTT 通訊協定的連線能力，並可連接不同的用戶端功能。

      若要在裝置上執行遠端操作，請使用裝置用戶端的用戶端任務功能。此功能包含剖析器，可接收實作任務文件中指定之遠端動作的任務文件和任務處理常式。如需有關裝置用戶端及其功能的詳細資訊，請參閱 AWS IoT 裝置用戶端。

      在裝置上執行時，裝置用戶端會接收任務文件，並具有用於在文件中執行命令的平台特定實作。如需有關設定裝置用戶端和使用任務功能的詳細資訊，請參閱 AWS IoT 教學課程。

  • 使用受支援的環境

    針對每個受管範本，您會找到可用來執行遠端動作之環境的相關資訊。建議依照範本所述，使用支援 Linux 環境的範本。使用 AWS IoT 裝置用戶端來執行受管範本遠端動作，因為它支援常見的微處理器和 Linux 環境，例如 Debian 和 Ubuntu。

受管範本遠端動作和任務文件

下節列出 AWS IoT 工作的不同 AWS 受管理範本，並說明可在設備上執行的遠端動作。下節具有任務文件的相關資訊，以及每個遠端動作之任務文件參數的描述。您的裝置端軟體使用範本名稱和參數執行遠端動作。

AWS 受管理的範本會接受您在使用範本建立工作時指定值的輸入參數。所有受管範本都有兩個共同的選用輸入參數：runAsUser 和 pathToHandler。除了 AWS-Reboot 範本之外，範本需要額外的輸入參數，您必須在使用範本建立任務時為其指定值。這些所需輸入參數取決於您選擇的範本。例如，如果您選擇 AWS-Download-File 範本，您必須指定要安裝的套件清單，以及要從中下載檔案的 URL。

指定使用 AWS IoT 主控台時的輸入參數值，或指定 AWS Command Line Interface (AWS CLI) 建立使用受管理範本的工作。使用 CLI 時，請使用 document-parameters 物件提供這些值。如需詳細資訊，請參閱 documentParameters。

注意

只在從 AWS 受管範本建立任務時，才會使用 document-parameters。這個參數不能與自訂任務範本一起使用，也不能用於從自訂任務範本建立任務。

以下為常見選用輸入參數的敘述。您會在下節中看到每個受管範本所需之其他輸入參數的描述。

runAsUser

此參數指定是否以其他使用者身分執行任務處理常式。如果未在建立任務期間指定，則任務處理常式會以與裝置用戶端相同的使用者身分執行。在以其他使用者身分執行任務處理常式時，請指定不超過 256 個字元的字串值。

pathToHandler

此為在裝置上執行的任務處理常式的路徑。如果未在任務建立期間指定，則裝置用戶端會使用目前的工作目錄。

下文顯示不同的遠端動作、其任務文件及其接受的參數。這些範本都支援 Linux 環境，以便在裝置上執行遠端操作。

範本名稱

AWS–Download–File

範本描述

由下載檔案所提供 AWS 的受管理範本。

輸入參數

此範本具有下列必要參數。您也可以指定選用參數 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}"
      }
    }
  ]
}
範本名稱

AWS–Install–Application

範本描述

由安裝一或多個應用程式所提供 AWS 的受管理範本。

輸入參數

此範本具有下列必要參數 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}"
      }
    }
  ]
}
範本名稱

AWS–Reboot

範本描述

由提供的受管理範本，用 AWS 於重新啟動裝置。

輸入參數

此範本沒有必要參數。您可以指定選用參數 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}"
      }
    }
  ]
}
範本名稱

AWS–Remove–Application

範本描述

由解除安裝一或多個應用程式所提供 AWS 的受管理範本。

輸入參數

此範本具有下列必要參數 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}"
      }
    }
  ]
}
範本名稱

AWS–Restart–Application

範本描述

由提供 AWS 用於停止和重新啟動一或多個服務的受管理範本。

輸入參數

此範本具有下列必要參數 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}"
      }
    }
  ]
}
範本名稱

AWS-Start-Application

範本描述

由提供 AWS 用於啟動一或多個服務的受管理範本。

輸入參數

此範本具有下列必要參數 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}"
      }
    }
  ]
}
範本名稱

AWS–Stop–Application

範本描述

由停止一或多個服務所提供 AWS 的受管理範本。

輸入參數

此範本具有下列必要參數 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}"
      }
    }
  ]
}
範本名稱

AWS–Run–Command

範本描述

由執行 shell 命令所提供 AWS 的受管理範本。

輸入參數

此範本具有下列必要參數 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}"
      }
    }
  ]
}
主題