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

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

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

受管範本包含哪些內容？

每個 AWS 受管範本都包含：

在任務文件中執行命令的環境。
指定操作名稱及其參數的任務文件。例如，如果使用 Download file (下載檔案) 範本，操作名稱為 Download file 並且參數可以是：
- 您要下載至裝置的檔案URL的。這可以是網際網路資源或公有或預先簽章的 Amazon Simple Storage Service （（Amazon S3） URL。
- 裝置上用來存放下載檔案的本機檔案路徑。
如需有關任務文件及其參數的詳細資訊，請參閱受管範本遠端動作和任務文件。

必要條件

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

在裝置上安裝特定軟體

使用您自己的裝置軟體和任務處理常式，或 AWS IoT Device Client。根據您的業務案例，您也可以同時執行它們，以便它們執行不同的功能。
- 使用自有裝置軟體和任務處理常式
  
  您可以使用 AWS IoT Device SDK 及其支援遠端操作的處理常式程式庫，為裝置撰寫自己的程式碼。若要部署和執行任務，請驗證裝置代理程式程式庫是否已正確安裝，且正在裝置上執行。
  
  您也可以選擇使用自己的處理常式來支援遠端操作。如需詳細資訊，請參閱 AWS IoT Device Client GitHub 儲存庫中的範例任務處理常式。
- 使用 AWS IoT 裝置用戶端
  
  或者，您可以在裝置上安裝和執行 AWS IoT Device Client，因為它預設支援直接從主控台使用所有受管範本。
  
  裝置用戶端是以 C++ 撰寫的開放原始碼軟體，可供您在內嵌 Linux 型 IoT 裝置上編譯並安裝。裝置用戶端具有基礎用戶端和分散的用戶端功能。基礎用戶端透過 AWS IoT MQTT通訊協定建立與的連線，並可連接不同的用戶端功能。
  
  若要在裝置上執行遠端操作，請使用裝置用戶端的用戶端任務功能。此功能包含剖析器，可接收實作任務文件中指定之遠端動作的任務文件和任務處理常式。如需有關裝置用戶端及其功能的詳細資訊，請參閱 AWS IoT 裝置用戶端。
  
  在裝置上執行時，裝置用戶端會接收任務文件，並具有用於在文件中執行命令的平台特定實作。如需有關設定裝置用戶端和使用任務功能的詳細資訊，請參閱 AWS IoT 教學課程。
使用受支援的環境

針對每個受管範本，您會找到可用來執行遠端動作之環境的相關資訊。建議依照範本所述，使用支援 Linux 環境的範本。使用 AWS IoT Device Client 執行受管範本遠端動作，因為它支援常見的微處理器和 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。如需使用預先簽署URLs和授予許可的詳細資訊，請參閱預先簽章 URLs。
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

範本描述

提供的受管範本， AWS 用於執行 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。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

任務範本

使用主控台從 AWS 受管範本建立任務