本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 AWS 受管範本部署常見的遠端操作 AWS 受管範本是由 提供的任務範本 AWS。它們用於經常執行的遠端動作，例如重新啟動、下載檔案或在裝置上安裝應用程式。這些範本具有適用於每個遠端動作的預先定義任務文件，無需您建立自己的任務文件。 您可以從一組預先定義的組態中進行選擇，並使用這些範本建立任務，而無需撰寫任何其他程式碼。使用受管範本，您可以檢視部署至機群的任務文件。您可以使用這些範本來建立任務，並建立可重複使用於遠端操作的自訂任務範本。 ## 受管範本包含哪些內容？ 每個 AWS 受管範本都包含： + 在任務文件中執行命令的環境。 + 指定操作名稱及其參數的任務文件。例如，如果使用 **Download file** (下載檔案) 範本，操作名稱為 *Download file* 並且參數可以是： + 您要下載至裝置的檔案 URL。這可以是網際網路資源，也可以是公有或預先簽章的 Amazon Simple Storage Service (Amazon S3) URL。 + 裝置上用來存放下載檔案的本機檔案路徑。 如需有關任務文件及其參數的詳細資訊，請參閱 [受管範本遠端動作和任務文件](#job-template-manage-actions)。 ## 先決條件 若要讓裝置執行受管範本任務文件指定的遠端操作，必須： + **在裝置上安裝特定軟體** 使用您自己的裝置軟體和任務處理常式，或 AWS IoT 裝置用戶端。根據您的業務案例，您也可以同時執行它們，以便它們執行不同的功能。 + **使用自有裝置軟體和任務處理常式** 您可以使用 AWS IoT Device SDK 及其支援遠端操作的處理常式程式庫，為裝置撰寫自己的程式碼。若要部署和執行任務，請驗證裝置代理程式程式庫是否已正確安裝，且正在裝置上執行。 您也可以選擇使用自己的處理常式來支援遠端操作。如需詳細資訊，請參閱 AWS IoT Device Client GitHub 儲存庫中的[範例任務處理常式](https://github.com/awslabs/aws-iot-device-client/tree/main/sample-job-handlers)。 + **使用 AWS IoT 裝置用戶端** 或者，您可以在裝置上安裝和執行 AWS IoT 裝置用戶端，因為它預設支援直接從主控台使用所有受管範本。 裝置用戶端是以 C\$1\$1 撰寫的開放原始碼軟體，可供您在內嵌 Linux 型 IoT 裝置上編譯並安裝。裝置用戶端具有*基礎用戶端*和分散的*用戶端功能*。基礎用戶端 AWS IoT 會透過 MQTT 通訊協定與 建立連線，並可連接不同的用戶端功能。 若要在裝置上執行遠端操作，請使用裝置用戶端的*用戶端任務功能*。此功能包含剖析器，可接收實作任務文件中指定之遠端動作的任務文件和任務處理常式。如需有關裝置用戶端及其功能的詳細資訊，請參閱 [AWS IoT 裝置用戶端](https://github.com/awslabs/aws-iot-device-client#readme)。 在裝置上執行時，裝置用戶端會接收任務文件，並具有用於在文件中執行命令的平台特定實作。如需有關設定裝置用戶端和使用任務功能的詳細資訊，請參閱 [AWS IoT 教學課程](https://docs.aws.amazon.com/iot/latest/developerguide/iot-tutorials.html)。 + **使用受支援的環境** 針對每個受管範本，您會找到可用來執行遠端動作之環境的相關資訊。建議依照範本所述，使用支援 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](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html#iot-CreateJob-request-documentParameters)。 **注意** 只在從 AWS 受管範本建立任務時，才會使用 `document-parameters`。這個參數不能與自訂任務範本一起使用，也不能用於從自訂任務範本建立任務。 以下為常見選用輸入參數的敘述。您會在下節中看到每個受管範本所需之其他輸入參數的描述。 `runAsUser` 此參數指定是否以其他使用者身分執行任務處理常式。如果未在建立任務期間指定，則任務處理常式會以與裝置用戶端相同的使用者身分執行。在以其他使用者身分執行任務處理常式時，請指定不超過 256 個字元的字串值。 `pathToHandler` 此為在裝置上執行的任務處理常式的路徑。如果未在任務建立期間指定，則裝置用戶端會使用目前的工作目錄。 下文顯示不同的遠端動作、其任務文件及其接受的參數。這些範本都支援 Linux 環境，以便在裝置上執行遠端操作。 ### AWS–Download–File **範本名稱** `AWS–Download–File` **範本描述** 提供的受管範本， AWS 用於下載檔案。 **輸入參數** 此範本具有下列必要參數。您也可以指定選用參數 `runAsUser` 和 `pathToHandler`。 `downloadUrl` 要從中下載檔案的 URL。這可以是網際網路資源、Amazon S3 中可以公開存取的物件，或者 Amazon S3 中只能由您裝置使用預先簽章 URL 存取的物件。如需有關使用預先簽章的 URL 和授予許可的詳細資訊，請參閱 [預先簽章的 URL](create-manage-jobs.md#create-manage-jobs-presigned-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–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–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–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–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-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–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–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}" } } ] } ``` **Topics** + [受管範本包含哪些內容？](#job-template-managed-contains) + [先決條件](#job-template-managed-prereq) + [受管範本遠端動作和任務文件](#job-template-manage-actions) + [使用 從 AWS 受管範本建立任務 AWS 管理主控台](job-template-manage-console-create.md) + [使用 從 AWS 受管範本建立任務 AWS CLI](job-template-manage-cli-create.md)