本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Image Builder 如何使用 AWS 任務協調器和執行器 應用程式來管理元件 EC2 Image Builder 使用 AWS 任務協調器和執行器 (AWS TOE) 應用程式來協調複雜的工作流程、修改系統組態，以及測試您的映像，而不需要額外的 devops 指令碼或程式碼。此應用程式會管理和執行實作其宣告文件結構描述的元件。 AWS TOE 是獨立應用程式，Image Builder 會在您建立映像時在其建置和測試執行個體上安裝。您也可以在 EC2 執行個體上手動安裝它，以建立您自己的自訂元件。它不需要任何額外的設定，也可以在內部部署上執行。 **Topics** + [AWS TOE 下載](#toe-downloads) + [支援地區](#toe-supported-regions) + [AWS TOE 命令參考](#toe-commands) + [手動設定以使用 開發自訂元件 AWS TOE](toe-get-started.md) + [使用自訂 AWS TOE 元件的元件文件架構](toe-use-documents.md) + [AWS TOE 元件管理員支援的動作模組](toe-action-modules.md) + [設定 AWS TOE 執行命令的輸入](toe-run-config-input.md) ## AWS TOE 下載 若要安裝 AWS TOE，請選擇架構和平台的下載連結。如果您連接到服務的 VPC 端點 （例如映像建置器），則必須連接自訂端點政策，其中包含 S3 儲存貯體的 AWS TOE 下載存取權。否則，您的建置和測試執行個體將無法下載引導指令碼 (`bootstrap.sh`) 並安裝 AWS TOE 應用程式。如需更多資訊，請參閱[為映像建置器建立 VPC 端點政策](vpc-interface-endpoints.md#vpc-endpoint-policy)。 **重要** AWS 正在暫停對 TLS 版本 1.0 和 1.1 的支援。若要存取 S3 儲存貯體進行 AWS TOE 下載，您的用戶端軟體必須使用 TLS 1.2 版或更新版本。如需詳細資訊，請參閱此[AWS 安全部落格文章](https://aws.amazon.com/blogs/security/tls-1-2-required-for-aws-endpoints/)。 | 架構 | 平台 | 下載連結 | 範例 | | --- | --- | --- | --- | | 386 | AL 2 和 2023 RHEL 7、8 和 9 Ubuntu 16.04、18.04、20.04、22.04 和 24.04 CentOS 7 和 8 SUSE 12 和 15 | `https://awstoe-.s3..amazonaws.com/latest/linux/386/awstoe` | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/386/awstoe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/386/awstoe) | | AMD64 | AL 2 和 2023 RHEL 7、8 和 9 Ubuntu 16.04、18.04、20.04、22.04 和 24.04 CentOS 7 和 8 CentOS Stream 8 SUSE 12 和 15 | https://awstoe-.s3..amazonaws.com/latest/linux/amd64/awstoe | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/amd64/awstoe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/amd64/awstoe) | | AMD64 | macOS 10.14.x (Mojave)、10.15.x (Catalina)、11.x (Big Sur)、12.x (Monterey) | https://awstoe-region.s3.region.amazonaws.com/latest/darwin/amd64/awstoe | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/darwin/amd64/awstoe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/darwin/amd64/awstoe) | | AMD64 | Windows Server 2012 R2、2016、2019 和 2022 | `https://awstoe-.s3..amazonaws.com/latest/windows/amd64/awstoe.exe` | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/windows/amd64/awstoe.exe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/windows/amd64/awstoe.exe) | | ARM64 | AL 2 和 2023 RHEL 7、8 和 9 Ubuntu 16.04、18.04、20.04、22.04 和 24.04 CentOS 7 和 8 CentOS Stream 8 SUSE 12 和 15 | https://awstoe-.s3..amazonaws.com/latest/linux/arm64/awstoe | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/arm64/awstoe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/arm64/awstoe) | ## 支援地區 AWS TOE 在下列 區域中支援 做為獨立應用程式。 | AWS 區域 名稱 | AWS 區域 | | --- | --- | | 美國東部 (俄亥俄) | us-east-2 | | 美國東部 (維吉尼亞北部) | us-east-1 | | AWS GovCloud （美國東部） | us-gov-east-1 | | AWS GovCloud （美國西部） | us-gov-west-1 | | 美國西部 (加利佛尼亞北部) | us-west-1 | | 美國西部 (奧勒岡) | us-west-2 | | Africa (Cape Town) | af-south-1 | | 亞太區域 (香港) | ap-east-1 | | 亞太區域 (大阪) | ap-northeast-3 | | 亞太區域 (首爾) | ap-northeast-2 | | 亞太區域 (孟買) | ap-south-1 | | 亞太區域 (海德拉巴) | ap-south-2 | | 亞太區域 (新加坡) | ap-southeast-1 | | 亞太區域 (雪梨) | ap-southeast-2 | | 亞太區域 (雅加達) | ap-southeast-3 | | 亞太區域 (東京) | ap-northeast-1 | | 加拿大 (中部) | ca-central-1 | | 歐洲 (法蘭克福) | eu-central-1 | | 歐洲 (蘇黎世) | eu-central-2 | | Europe (Stockholm) | eu-north-1 | | 歐洲 (米蘭) | eu-south-1 | | 歐洲 (西班牙) | eu-south-2 | | 歐洲 (愛爾蘭) | eu-west-1 | | 歐洲 (倫敦) | eu-west-2 | | 歐洲 (巴黎) | eu-west-3 | | 以色列 (特拉維夫) | il-central-1 | | 中東 (阿拉伯聯合大公國) | me-central-1 | | Middle East (Bahrain) | me-south-1 | | 南美洲 (聖保羅) | sa-east-1 | | 中國 (北京) | cn-north-1 | | 中國 (寧夏) | cn-northwest-1 | ## AWS TOE 命令參考 AWS TOE 是在 Amazon EC2 執行個體上執行的命令列元件管理應用程式。當 Image Builder 啟動 EC2 組建或測試執行個體時，它會在執行個體 AWS TOE 上安裝 。然後，它會在 中執行 AWS TOE 命令 AWS CLI ，以安裝或驗證映像或容器配方中指定的元件。 **注意** 有些 AWS TOE 動作模組需要更高的許可，才能在 Linux 伺服器上執行。若要使用提升的許可，請在命令語法前面加上 **sudo**，或在執行下列連結的**sudo su**命令之前，在您登入時執行一次命令。如需 AWS TOE 動作模組的詳細資訊，請參閱 [AWS TOE 元件管理員支援的動作模組](toe-action-modules.md)。 ***[run](#cmd-run)*** 使用 **run**命令來執行一或多個元件文件的 YAML 文件指令碼。 ***[validate](#cmd-validate)*** 執行 **validate**命令來驗證一或多個元件文件的 YAML 文件語法。 ### awstoe run 命令 此命令執行 YAML 元件文件指令碼的順序，會包含在 `--config` 參數指定的組態檔案中，或 `--documents` 參數指定的元件文件清單。 **注意** 您必須明確指定下列其中一個參數，絕不能同時指定兩者： --config -- 文件 #### 語法 ``` awstoe run [--config ] [--cw-ignore-failures ] [--cw-log-group ] [--cw-log-region us-west-2] [--cw-log-stream ] [--document-s3-bucket-owner ] [--documents ] [--execution-id ] [--log-directory ] [--log-s3-bucket-name ] [--log-s3-bucket-owner ] [--log-s3-key-prefix ] [--parameters name1=value1,name2=value2...] [--phases ] [--state-directory ] [--version ] [--help] [--trace] ``` #### 參數和選項 參數 **--config *`./config-example.json`*** 簡短格式：-c *`./config-example.json`* 組態檔案 *（條件式）*。此參數包含 JSON 檔案的檔案位置，其中包含此命令正在執行之元件的組態設定。如果您在組態檔案中指定**run**命令設定，則不得指定 `--documents` 參數。如需輸入組態的詳細資訊，請參閱 [設定 AWS TOE 執行命令的輸入](toe-run-config-input.md)。 有效位置包括： + 本機檔案路徑 (*`./config-example.json`*) + S3 URI (`s3://bucket/key`) **--cw-ignore-failures** 簡短格式：不適用 忽略 CloudWatch Logs 中的記錄失敗。 **--cw-log-group** 簡短格式：不適用 CloudWatch Logs `LogGroup`的名稱。 **--cw-log-region** 簡短格式：不適用 套用至 CloudWatch Logs AWS 的區域。 **--cw-log-stream** 簡短格式：不適用 CloudWatch Logs `LogStream`的名稱，會指示檔案的串流 AWS TOE 位置`console.log`。 **--document-s3-bucket-owner** 簡短格式：不適用 S3 URI 型文件儲存貯體擁有者的帳戶 ID。 **--文件、 *`./doc-1.yaml``./doc-n.yaml`*** 簡短格式：-d*`./doc-1.yaml`*、*`./doc-n`* 元件文件 *（條件式）*。此參數包含以逗號分隔的檔案位置清單，以供 YAML 元件文件執行。如果您使用 `--documents` 參數為**run**命令指定 YAML 文件，則不得指定 `--config` 參數。 有效位置包括： + 本機檔案路徑 (*./component-doc-example.yaml)。* + S3 URIs(`s3://bucket/key`)。 + Image Builder 元件建置版本 ARNs(arn：aws：imagebuilder：us-west-*2：123456789012*：component/*my-example-component*/2021.12.02/1)。 清單中的項目之間沒有空格，只有逗號。 **--execution-id** 簡短格式：-i 這是套用至目前**run**命令執行的唯一 ID。此 ID 包含在輸出和日誌檔案名稱中，以唯一識別這些檔案，並將其連結至目前的命令執行。如果沒有此設定， AWS TOE 會產生 GUID。 **--log-directory** 簡短格式：-l AWS TOE 儲存此命令執行中所有日誌檔案的目的地目錄。根據預設，此目錄位於下列父目錄內：`TOE__`。如果您未指定日誌目錄， AWS TOE 會使用目前的工作目錄 (`.`)。 **--log-s3-bucket-name** 簡短格式：-b 如果元件日誌存放在 Amazon S3 （建議） 中， 會將元件應用程式日誌 AWS TOE 上傳到此參數中名為 的 S3 儲存貯體。 **--log-s3-bucket-owner** 簡短格式：不適用 如果元件日誌存放在 Amazon S3 （建議），這是 AWS TOE 寫入日誌檔案之 儲存貯體的擁有者帳戶 ID。 **--log-s3-key-prefix** 簡短格式：-k 如果元件日誌存放在 Amazon S3 （建議），這是儲存貯體中日誌位置的 S3 物件金鑰字首。 **--parameters *name1*=*value1*，*name2*=*value2*...** 簡短格式：不適用 參數是元件文件中定義的可變變數，具有呼叫應用程式可在執行時間提供的設定。 **--階段** 簡短格式：-p 以逗號分隔的清單，指定要從 YAML 元件文件執行哪些階段。如果元件文件包含其他階段，則不會執行這些階段。 **--state-directory** 簡短格式：-s 存放狀態追蹤檔案的檔案路徑。 **--version** 簡短格式：-v 指定元件應用程式版本。選項 **--help** 簡短格式：-h 顯示使用元件管理應用程式選項的說明手冊。 **-- 追蹤** 簡短格式：-t 啟用主控台的詳細記錄。 ### awstoe validate 命令 當您執行此命令時，它會驗證 `--documents` 參數指定的每個元件文件的 YAML 文件語法。 #### 語法 ``` awstoe validate [--document-s3-bucket-owner ] --documents [--help] [--trace] ``` #### 參數和選項 參數 **--document-s3-bucket-owner** 簡短格式：不適用 提供的 S3 URI 型文件的來源帳戶 ID。 **--文件 *`./doc-1.yaml`、`./doc-n.yaml`*** 簡短格式：-d*`./doc-1.yaml`*、*`./doc-n`* 元件文件 *（必要）*。此參數包含以逗號分隔的檔案位置清單，以供 YAML 元件文件執行。有效位置包括： + 本機檔案路徑 (*./component-doc-example.yaml*) + S3 URIs(`s3://bucket/key`) + 映像建置器元件建置版本 ARNs(arn：aws：imagebuilder：us-west-*2：123456789012*：component/*my-example-component*/2021.12.02/1) 清單中的項目之間沒有空格，只有逗號。選項 **--help** 簡短格式：-h 顯示使用元件管理應用程式選項的說明手冊。 **-- 追蹤** 簡短格式：-t 啟用主控台的詳細記錄。 # 手動設定以使用 開發自訂元件 AWS TOE AWS 任務協調器和執行器 (AWS TOE) 應用程式是一種獨立的應用程式，可在元件定義架構中建立、驗證和執行命令。 AWS 服務可以使用 AWS TOE 來協調工作流程、安裝軟體、修改系統組態和測試映像組建。 請依照下列步驟手動安裝 AWS TOE 應用程式，並將其用作獨立應用程式來開發自訂元件。如果您使用 Image Builder 主控台或 AWS CLI 命令來建立自訂元件，Image Builder 會為您處理這些步驟。如需詳細資訊，請參閱[使用映像建置器建立自訂元件](create-component.md)。 # 驗證 AWS TOE 安裝下載的簽章 本節說明在 Linux、macOS 和 Windows 作業系統 AWS TOE 上驗證 的安裝下載有效性的建議程序。 **Topics** + [驗證 Linux 或 macOS 上 AWS TOE 安裝下載的簽章](#awstoe-verify-sig-linux) + [驗證 Windows 上 AWS TOE 安裝下載的簽章](#awstoe-verify-sig-win) ## 驗證 Linux 或 macOS 上 AWS TOE 安裝下載的簽章 本主題說明在 Linux 作業系統或 macOS 作業系統 AWS TOE 上驗證安裝下載有效性的建議程序。 每當您從網際網路下載應用程式時，我們建議您驗證軟體發佈者的身分。此外，請檢查應用程式自發佈以來是否遭到更改或損毀。如此可保護您，避免安裝到包含病毒或其他惡意程式碼的應用程式版本。 如果在執行本主題中的步驟後，您判斷 AWS TOE 應用程式的軟體已更改或損毀，請勿執行安裝檔案。反之，請聯絡 支援 如需支援選項的詳細資訊，請參閱 [支援](https://aws.amazon.com/premiumsupport/)。 AWS TOE Linux 型和 macOS 作業系統的檔案使用 進行簽署`GnuPG`，這是 Pretty Good Privacy (OpenPGP) 標準用於安全數位簽章的開放原始碼實作。 `GnuPG`（也稱為 `GPG`) 透過數位簽章提供身分驗證和完整性檢查。Amazon EC2 會發佈公有金鑰和簽章，您可以用來驗證下載的 Amazon EC2 CLI 工具。如需 `PGP` 和 `GnuPG` (`GPG`) 的詳細資訊，請參閱 [http://www.gnupg.org](https://www.gnupg.org/)。 第一步是與軟體發佈者建立信任。下載軟體發佈者的公開金鑰，檢查公開金鑰的擁有者是否為聲稱的擁有者，然後將公開金鑰新增至您的 *keyring*。您的 keyring 是一組已知的公開金鑰。在您建立公開金鑰的真實性之後，即可用它來驗證應用程式的簽章。 **Topics** + [安裝 GPG 工具](#awstoe-verify-signature-of-binary-download-install-tools) + [驗證和匯入公開金鑰](#awstoe-verify-signature-of-binary-download-authenticate-import-public-key) + [驗證套件的簽章](#awstoe-verify-signature-of-binary-package) ### 安裝 GPG 工具 如果您的作業系統是 Linux、Unix 或 macOS，則可能已安裝 GPG 工具。若要測試工具是否已安裝在您的系統，請在命令提示字元中輸入 **gpg**。如果 GPG 工具已安裝，您會看到 GPG 命令提示字元。如果未安裝 GPG 工具，您會看到錯誤訊息，指出找不到命令。您可以從儲存庫安裝 GnuPG 套件。 若要安裝 GPG 工具，請選取符合您執行個體的作業系統。 ------ #### [ Debian-based Linux ] 從終端機執行下列命令： ``` apt-get install gnupg ``` ------ #### [ Red Hat–based Linux ] 從終端機執行下列命令： ``` yum install gnupg ``` ------ #### [ macOS ] 從終端機執行下列命令： ``` brew install gnupg ``` ------ ### 驗證和匯入公開金鑰 程序的下一個步驟是驗證 AWS TOE 公有金鑰，並將其新增為 `GPG` keyring 中的信任金鑰。 **驗證和匯入 AWS TOE 公有金鑰** 1. 執行以下其中一項以取得我們的公有 `GPG` 建置金鑰的副本： + 從 下載金鑰 https：//awstoe-****.s3.****.amazonaws.com/assets/awstoe.gpg。例如 [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/assets/awstoe.gpg](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/assets/awstoe.gpg)。 + 從以下文字複製金鑰，然後貼到名為 `awstoe.gpg` 的檔案中。務必包含以下所有項目： ``` -----BEGIN PGP PUBLIC KEY BLOCK----- Version: GnuPG v2 mQENBF8UqwsBCACdiRF2bkZYaFSDPFC+LIkWLwFvtUCRwAHtD8KIwTJ6LVn3fHAU GhuK0ZH9mRrqRT2bq/xJjGsnF9VqTj2AJqndGJdDjz75YCZYM+ocZ+r5HSJaeW9i S5dykHj7Txti2zHe0G5+W0v7v5bPi2sPHsN7XWQ7+G2AMEPTz8PjxY//I0DvMQns Sle3l9hz6wCClz1l9LbBzTyHfSm5ucTXvNe88XX5Gmt37OCDM7vfli0Ctv8WFoLN 6jbxuA/sV71yIkPm9IYp3+GvaKeT870+sn8/JOOKE/U4sJV1ppbqmuUzDfhrZUaw 8eW8IN9A1FTIuWiZED/5L83UZuQs1S7s2PjlABEBAAG0GkFXU1RPRSA8YXdzdG9l QGFtYXpvbi5jb20+iQE5BBMBCAAjBQJfFKsLAhsDBwsJCAcDAgEGFQgCCQoLBBYC AwECHgECF4AACgkQ3r3BVvWuvFJGiwf9EVmrBR77+Qe/DUeXZJYoaFr7If/fVDZl 6V3TC6p0J0Veme7uXleRUTFOjzbh+7e5sDX19HrnPquzCnzfMiqbp4lSoeUuNdOf FcpuTCQH+M+sIEIgPno4PLl0Uj2uE1o++mxmonBl/Krk+hly8hB2L/9n/vW3L7BN OMb1Ll9PmgGPbWipcT8KRdz4SUex9TXGYzjlWb3jU3uXetdaQY1M3kVKE1siRsRN YYDtpcjmwbhjpu4xm19aFqNoAHCDctEsXJA/mkU3erwIRocPyjAZE2dnlkL9ZkFZ z9DQkcIarbCnybDM5lemBbdhXJ6hezJE/b17VA0t1fY04MoEkn6oJg== =oyze -----END PGP PUBLIC KEY BLOCK----- ``` 1. 在您儲存 **awstoe.gpg** 的目錄中的命令提示字元中，使用下列命令將 AWS TOE 公有金鑰匯入 keyring。 ``` gpg --import awstoe.gpg ``` 此命令會傳回類似以下的結果： ``` gpg: key F5AEBC52: public key "AWSTOE " imported gpg: Total number processed: 1 gpg: imported: 1 (RSA: 1) ``` 請記下金鑰值，在後續步驟您將會用到它。在前面的範例中，金鑰值為 `F5AEBC52`。 1. 執行以下命令以驗證指紋，請以三個步驟的值取代 *key-value*： ``` gpg --fingerprint key-value ``` 此命令會傳回類似以下的結果： ``` pub 2048R/F5AEBC52 2020-07-19 Key fingerprint = F6DD E01C 869F D639 15E5 5742 DEBD C156 F5AE BC52 uid [ unknown] AWSTOE ``` 此外，如以上範例所示，指紋字串應該與 `F6DD E01C 869F D639 15E5 5742 DEBD C156 F5AE BC52` 完全相同。比較傳回的金鑰指紋與此頁面發佈的金鑰指紋。它們應該相符。如果不相符，請勿安裝 AWS TOE 安裝指令碼並聯絡 支援。 ### 驗證套件的簽章 在您安裝 `GPG` 工具、驗證及匯入 AWS TOE 公有金鑰，以及驗證公有金鑰可信任之後，您就可以驗證安裝指令碼的簽章。 **驗證 安裝指令碼簽章** 1. 在命令提示字元中，執行下列命令來下載應用程式二進位檔： ``` curl -O https://awstoe-.s3..amazonaws.com/latest/linux//awstoe ``` 例如： ``` curl -O https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/amd64/awstoe ``` 支援的值**architecture**可以是 `amd64`、 `386`和 `arm64`。 1. 在命令提示字元中，執行下列命令，從相同的 S3 金鑰字首路徑下載對應應用程式二進位檔的簽章檔案： ``` curl -O https://awstoe-.s3..amazonaws.com/latest/linux//awstoe.sig ``` 例如： ``` curl -O https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/amd64/awstoe.sig ``` 支援的值**architecture**可以是 `amd64`、 `386`和 `arm64`。 1. 在儲存和 AWS TOE 安裝檔案的目錄中的命令提示字元中執行下列命令`awstoe.sig`來驗證簽章。兩個檔案都必須存在。 ``` gpg --verify ./awstoe.sig ~/awstoe ``` 輸出應類似以下所示： ``` gpg: Signature made Mon 20 Jul 2020 08:54:55 AM IST using RSA key ID F5AEBC52 gpg: Good signature from "AWSTOE awstoe@amazon.com" [unknown] gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: F6DD E01C 869F D639 15E5 5742 DEBD C156 F5AE BC52 ``` 如果輸出包含 `Good signature from "AWSTOE "` 片語，表示簽章已成功驗證，您可以繼續執行 AWS TOE 安裝指令碼。 如果輸出包含 `BAD signature` 片語，請檢查您是否已正確執行程序。如果您繼續取得此回應，請勿執行先前下載的安裝檔案，並聯絡 支援。 以下是您可能會看到的警告的詳細資訊： + **警告：此金鑰未通過信任簽章的認證！沒有指示簽章屬於擁有者。**理想情況下，您會前往 AWS 辦公室並親自收到金鑰。不過，您很可能會從網站下載。在這種情況下，網站是 AWS 網站。 + **gpg：沒有發現最終信任的金鑰。**這表示您或您信任的其他人不會「最終信任」特定金鑰。 如需詳細資訊，請參閱 [http://www.gnupg.org](http://www.gnupg.org)。 ## 驗證 Windows 上 AWS TOE 安裝下載的簽章 本主題說明在 Windows 作業系統上驗證 AWS 任務協調器和執行器 應用程式安裝檔案有效性的建議程序。 當您從網際網路下載應用程式時，建議您驗證軟體發佈者的身分，並檢查應用程式在發佈之後未遭更改或損毀。如此可保護您，避免安裝到包含病毒或其他惡意程式碼的應用程式版本。 如果在執行本主題中的步驟後，您判斷 AWS TOE 應用程式的軟體已更改或損毀，請勿執行安裝檔案。反之，請聯絡 支援。 若要在 Windows 作業系統上驗證下載的 awstoe 二進位檔的有效性，請確定其 Amazon Services LLC 簽署者憑證的指紋等於此值： **9D CA 72 17 DA FF B8 2F E4 C4 67 77 36 2F A4 AA C9 08 82 15** **注意** 在新二進位檔的推展時段期間，您的簽署者憑證可能與新的指紋不相符。如果您的簽署者憑證不相符，請確認指紋值為： **BA 81 25 EE AC 64 2E A9 F3 C5 93 CA 6D 3E B7 93 7D 68 75 74** 若要驗證這個值，請執行以下程序： 1. 在下載的 `awstoe.exe` 上按一下滑鼠右鍵，然後開啟 **Properties (屬性)** 視窗。 1. 選擇 **數位簽章** 索引標籤。 1. 從 **Signature List (簽章清單)** 中選擇 **Amazon Services LLC**，然後選擇 **Details (詳細資訊)**。 1. 選擇 **General (一般)** 索引標籤 (如果尚未選取)，然後選擇 **View Certificate (檢視憑證)**。 1. 選擇**詳細資訊**索引標籤，如果尚未選取，請在**顯示**下拉式清單中選擇**全部**。 1. 向下捲動到看見 **Thumbprint (指紋)** 欄位為止，然後選擇 **Thumbprint (指紋)**。這會在下方的視窗中顯示整個指紋值。 + 如果下方視窗中的指紋值與以下值完全相同： **9D CA 72 17 DA FF B8 2F E4 C4 67 77 36 2F A4 AA C9 08 82 15** 然後，您下載 AWS TOE 的二進位檔是真實的，可以安全地安裝。 + 如果較低詳細資訊視窗中的指紋值與先前的值不同，請勿執行 `awstoe.exe`。 **Topics** + [驗證 AWS TOE 安裝下載的簽章](awstoe-verify-sig.md) + [步驟 1：安裝 AWS TOE](#toe-start-install) + [步驟 2：設定 AWS 登入資料](#toe-start-credentials) + [步驟 3：在本機開發元件文件](#toe-start-develop) + [步驟 4：驗證 AWS TOE 元件](#toe-start-validate) + [步驟 5：執行 AWS TOE 元件](#toe-start-run) ## 步驟 1：安裝 AWS TOE 若要在本機開發元件，請下載並安裝 AWS TOE 應用程式。 1. **下載 AWS TOE 應用程式** 若要安裝 AWS TOE，請為您的架構和平台選擇適當的下載連結。如需應用程式下載連結的完整清單，請參閱 [AWS TOE 下載](toe-component-manager.md#toe-downloads) **重要** AWS 正在暫停對 TLS 1.0 和 1.1 版的支援。若要存取 S3 儲存貯體進行 AWS TOE 下載，您的用戶端軟體必須使用 TLS 1.2 版或更新版本。如需詳細資訊，請參閱此[AWS 安全部落格文章](https://aws.amazon.com/blogs/security/tls-1-2-required-for-aws-endpoints/)。 1. **驗證簽章** 驗證下載的步驟取決於您在安裝後執行 AWS TOE 應用程式的伺服器平台。若要在 Linux 伺服器上驗證您的下載，請參閱 [驗證 Linux 或 macOS 上的簽章](awstoe-verify-sig.md#awstoe-verify-sig-linux)。若要在 Windows 伺服器上驗證您的下載，請參閱 [驗證 Windows 上的簽章](awstoe-verify-sig.md#awstoe-verify-sig-win)。 **注意** AWS TOE 直接從其下載位置叫用。不需要單獨的安裝步驟。這也表示 AWS TOE 可以變更本機環境。 為了確保您在元件開發期間隔離變更，我們建議您使用 EC2 執行個體來開發和測試 AWS TOE 元件。 ## 步驟 2：設定 AWS 登入資料 AWS TOE 執行任務時， 需要 AWS 登入資料才能連線到其他 AWS 服務，例如 Amazon S3 和 Amazon CloudWatch，例如： + 從使用者提供的 Amazon S3 路徑下載 AWS TOE 文件。 + 執行 `S3Download`或 `S3Upload` 動作模組。 + 啟用時，將日誌串流至 CloudWatch。 如果您在 EC2 執行個體 AWS TOE 上執行 ，則執行 AWS TOE 會使用與連接到 EC2 執行個體的 IAM 角色相同的許可。 如需 EC2 IAM 角色的詳細資訊，請參閱 [Amazon EC2 的 IAM 角色](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)。 下列範例示範如何使用 `AWS_ACCESS_KEY_ID`和 `AWS_SECRET_ACCESS_KEY`環境變數設定 AWS 登入資料。 若要在 Linux、macOS 或 Unix 上設定這些變數，請使用 `export`。 ``` export AWS_ACCESS_KEY_ID=your_access_key_id ``` ``` export AWS_SECRET_ACCESS_KEY=your_secret_access_key ``` 若要使用 PowerShell 在 Windows 上設定這些變數，請使用 `$env`。 ``` $env:AWS_ACCESS_KEY_ID=your_access_key_id ``` ``` $env:AWS_SECRET_ACCESS_KEY=your_secret_access_key ``` 若要使用命令提示字元在 Windows 上設定這些變數，請使用 `set`。 ``` set AWS_ACCESS_KEY_ID=your_access_key_id ``` ``` set AWS_SECRET_ACCESS_KEY=your_secret_access_key ``` ## 步驟 3：在本機開發元件文件 元件是以純文字 YAML 文件撰寫。如需文件語法的詳細資訊，請參閱 [使用自訂 AWS TOE 元件的元件文件架構](toe-use-documents.md)。 以下是 *Hello World* 元件文件範例，可協助您開始使用。 ------ #### [ Linux ] 本指南中的一些 Linux 元件範例參考名為 的元件文件檔案`hello-world-linux.yml`。您可以使用下列文件來開始使用這些範例。 ``` name: Hello World description: This is hello world testing document for Linux. schemaVersion: 1.0 phases: - name: build steps: - name: HelloWorldStep action: ExecuteBash inputs: commands: - echo 'Hello World from the build phase.' - name: validate steps: - name: HelloWorldStep action: ExecuteBash inputs: commands: - echo 'Hello World from the validate phase.' - name: test steps: - name: HelloWorldStep action: ExecuteBash inputs: commands: - echo 'Hello World from the test phase.' ``` ------ #### [ Windows ] 本指南中的一些 Windows 元件範例參考名為 的元件文件檔案`hello-world-windows.yml`。您可以使用下列文件來開始使用這些範例。 ``` name: Hello World description: This is Hello World testing document for Windows. schemaVersion: 1.0 phases: - name: build steps: - name: HelloWorldStep action: ExecutePowerShell inputs: commands: - Write-Host 'Hello World from the build phase.' - name: validate steps: - name: HelloWorldStep action: ExecutePowerShell inputs: commands: - Write-Host 'Hello World from the validate phase.' - name: test steps: - name: HelloWorldStep action: ExecutePowerShell inputs: commands: - Write-Host 'Hello World from the test phase.' ``` ------ #### [ macOS ] 本指南中的一些 macOS 元件範例參考名為 的元件文件檔案`hello-world-macos.yml`。您可以使用下列文件來開始使用這些範例。 ``` name: Hello World description: This is hello world testing document for macOS. schemaVersion: 1.0 phases: - name: build steps: - name: HelloWorldStep action: ExecuteBash inputs: commands: - echo 'Hello World from the build phase.' - name: validate steps: - name: HelloWorldStep action: ExecuteBash inputs: commands: - echo 'Hello World from the validate phase.' - name: test steps: - name: HelloWorldStep action: ExecuteBash inputs: commands: - echo 'Hello World from the test phase.' ``` ------ ## 步驟 4：驗證 AWS TOE 元件 您可以使用應用程式在本機 AWS TOE 驗證 AWS TOE 元件的語法。下列範例顯示 AWS TOE 應用程式`validate`命令，在不執行元件的情況下驗證元件的語法。 **注意** AWS TOE 應用程式只能驗證目前作業系統的元件語法。例如，在 Windows `awstoe.exe` 上執行 時，您無法驗證使用 `ExecuteBash`動作模組的 Linux 文件語法。 Linux 或 macOS ``` awstoe validate --documents /home/user/hello-world.yml ``` Windows ``` awstoe.exe validate --documents C:\Users\user\Documents\hello-world.yml ``` ## 步驟 5：執行 AWS TOE 元件 AWS TOE 應用程式可以使用`--phases`命令列引數執行指定文件的一或多個階段。支援的值`--phases`為 `build`、 `validate`和 `test`。多個階段值可以輸入為逗號分隔值。 當您提供階段清單時， AWS TOE 應用程式會依序執行每個文件的指定階段。例如， AWS TOE 執行 的 `build`和 `validate`階段`document1.yaml`，後面接著 的 `build`和 `validate`階段`document2.yaml`。 為了確保日誌安全儲存並保留以進行故障診斷，建議您在 Amazon S3 中設定日誌儲存。在映像建置器中，用於發佈日誌的 Amazon S3 位置是在基礎設施組態中指定。如需基礎設施組態的詳細資訊，請參閱 [管理映像建置器基礎設施組態](manage-infra-config.md) 如果未提供階段清單， AWS TOE 應用程式會依 YAML 文件所列的順序執行所有階段。 若要在單一或多個文件中執行特定階段，請使用下列命令。 單一階段 ``` awstoe run --documents hello-world.yml --phases build ``` 多個階段 ``` awstoe run --documents hello-world.yml --phases build,test ``` **文件執行** 在單一文件中執行所有階段 ``` awstoe run --documents documentName.yaml ``` 在多個文件中執行所有階段 ``` awstoe run --documents documentName1.yaml,documentName2.yaml ``` 輸入 Amazon S3 資訊以從使用者定義的本機路徑上傳 AWS TOE 日誌 （建議） ``` awstoe run --documents documentName.yaml --log-s3-bucket-name amzn-s3-demo-destination-bucket --log-s3-key-prefix S3KeyPrefix --log-s3-bucket-owner S3BucketOwner --log-directory local_path ``` 在單一文件中執行所有階段，並在主控台上顯示所有日誌 ``` awstoe run --documents documentName.yaml --trace ``` 範例 命令 ``` awstoe run --documents s3://bucket/key/doc.yaml --phases build,validate ``` 執行具有唯一 ID 的文件 ``` awstoe run --documents documentName.yaml --execution-id user-provided-id --phases build,test ``` 取得 的協助 AWS TOE ``` awstoe --help ``` # 使用自訂 AWS TOE 元件的元件文件架構 若要使用 AWS 任務協調器和執行器 (AWS TOE) 元件架構建置元件，您必須提供 YAML 型文件，代表適用於您建立之元件的階段和步驟。當元件建立新的 Amazon Machine Image (AMI) 或容器映像時 AWS 服務 ，請使用您的元件。 **Topics** + [元件文件工作流程](#component-doc-workflow) + [元件記錄](#component-logging) + [輸入和輸出鏈結](#document-chaining) + [文件結構描述和定義](#document-schema) + [文件範例](#document-example) + [在自訂元件文件中使用變數](toe-user-defined-variables.md) + [在 中使用條件式建構 AWS TOE](toe-conditional-constructs.md) + [在 AWS TOE 元件文件中使用比較運算子](toe-comparison-operators.md) + [在 AWS TOE 元件文件中使用邏輯運算子](toe-logical-operators.md) + [在 中使用迴圈建構 AWS TOE](toe-looping-constructs.md) ## 元件文件工作流程 AWS TOE 元件文件使用階段和步驟來分組相關任務，並將這些任務組織到元件的邏輯工作流程中。 **提示** 使用 元件建置映像的服務可能會實作有關要用於其建置程序的階段，以及允許執行這些階段的規則。當您設計元件時，請務必考量這一點。 **階段** 階段代表工作流程在映像建置過程中的進展。例如，Image Builder 服務會在其產生的映像的*建置階段*使用 `build`和 `validate`階段。它在其*測試階段*使用 `test`和 `container-host-test`階段，以確保在建立最終 AMI 或分發容器映像之前，映像快照或容器映像會產生預期的結果。 當元件執行時，每個階段的相關聯命令會按照元件文件中顯示的順序套用。 **階段的規則** + 每個階段名稱在文件中必須是唯一的。 + 您可以在文件中定義多個階段。 + 您必須在文件中至少包含下列其中一個階段： + **build** – 對於映像建置器，此階段通常會在*建置階段*期間使用。 + **validate** – 對於映像建置器，此階段通常會在*建置階段*期間使用。 + **測試** – 對於映像建置器，此階段通常會在*測試階段*期間使用。 + 階段一律會按照文件中定義的順序執行。在 中 AWS CLI 為 AWS TOE 命令指定的順序沒有效果。 **步驟** 步驟是個別的工作單位，可定義每個階段內的工作流程。步驟會循序執行。不過，一個步驟的輸入或輸出也可以做為輸入饋送至後續步驟。這稱為「鏈結」。 **步驟的規則** + 步驟名稱對於 階段必須是唯一的。 + 步驟必須使用傳回結束代碼的支援動作 （動作模組）。 如需支援的動作模組的完整清單、運作方式、輸入/輸出值和範例，請參閱 [AWS TOE 元件管理員支援的動作模組](toe-action-modules.md)。 ## 元件記錄 AWS TOE 會在 EC2 執行個體上建立新的日誌資料夾，用於在每次元件執行時建置和測試新映像。對於容器映像，日誌資料夾會存放在容器中。 為了協助在映像建立過程中發生錯誤時進行故障診斷，在執行元件時 AWS TOE 建立的輸入文件和所有輸出檔案都會存放在日誌資料夾中。 日誌資料夾名稱包含下列部分： 1. **日誌目錄** – 當服務執行 AWS TOE 元件時，它會在日誌目錄中傳遞，以及命令的其他設定。針對下列範例，我們會顯示 Image Builder 使用的日誌檔案格式。 + **Linux 和 macOS**： `/var/lib/amazon/toe/` + **Windows**: `$env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\` 1. **檔案字首** – 這是用於所有元件的標準字首："`TOE_`"。 1. **執行時間** – 這是 YYYY-MM-DD\$1HH-MM-SS\$1UTC-0 格式的時間戳記。 1. **執行 ID** – 這是 AWS TOE 執行一或多個元件時指派的 GUID。 範例：`/var/lib/amazon/toe/TOE_2021-07-01_12-34-56_UTC-0_a1bcd2e3-45f6-789a-bcde-0fa1b2c3def4` AWS TOE 會將下列核心檔案存放在日誌資料夾中： **輸入檔案** + **document.yaml** – 用作命令輸入的文件。元件執行後，此檔案會儲存為成品。 **輸出檔案** + **application.log** – 應用程式日誌包含來自 的時間戳記偵錯層級資訊， AWS TOE 了解元件執行時的情況。 + **detailedoutput.json** – 此 JSON 檔案提供有關執行狀態、輸入、輸出和故障的詳細資訊，適用於元件執行時的所有文件、階段和步驟。 + **console.log** – 主控台日誌包含元件執行時 AWS TOE 寫入主控台的所有標準輸出 (stdout) 和標準錯誤 (stderr) 資訊。 + **chaining.json** – 此 JSON 檔案代表 AWS TOE 適用於解析鏈結表達式的最佳化。 **注意** 日誌資料夾也可能包含此處未涵蓋的其他暫存檔案。 ## 輸入和輸出鏈結 AWS TOE 組態管理應用程式以下列格式撰寫參考，提供鏈結輸入和輸出的功能： `{{ phase_name.step_name.inputs/outputs.variable }}` 或 `{{ phase_name.step_name.inputs/outputs[index].variable }}` 鏈結功能可讓您回收程式碼並改善文件的可維護性。 **鏈結規則** + 鏈結表達式只能在每個步驟的輸入區段中使用。 + 具有鏈結表達式的陳述式必須以引號括住。例如： + **無效的表達式**： `echo {{ phase.step.inputs.variable }}` + **有效表達式**： `"echo {{ phase.step.inputs.variable }}"` + **有效表達式**： `'echo {{ phase.step.inputs.variable }}'` + 鏈結表達式可以參考相同文件中其他步驟和階段的變數。不過，呼叫服務可能有規則，需要鏈結表達式才能僅在單一階段的內容中操作。例如，Image Builder 不支援從*建置階段*鏈結至*測試階段*，因為它會獨立執行每個階段。 + 鏈結表達式中的索引遵循以零為基礎的索引。索引以零 (0) 開頭，以參考第一個元素。 **範例** 若要參考下列範例步驟第二個項目中的來源變數，鏈結模式為 `{{ build.SampleS3Download.inputs[1].source }}`。 ``` phases: - name: 'build' steps: - name: SampleS3Download action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://sample-bucket/sample1.ps1' destination: 'C:\sample1.ps1' - source: 's3://sample-bucket/sample2.ps1' destination: 'C:\sample2.ps1' ``` 若要參考下列範例步驟的輸出變數 （等於 "Hello")，鏈結模式為 `{{ build.SamplePowerShellStep.outputs.stdout }}`。 ``` phases: - name: 'build' steps: - name: SamplePowerShellStep action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: commands: - 'Write-Host "Hello"' ``` ## 文件結構描述和定義 以下是文件的 YAML 結構描述。 ``` name: (optional) description: (optional) schemaVersion: "string" phases: - name: "string" steps: - name: "string" action: "string" timeoutSeconds: integer onFailure: "Abort|Continue|Ignore" maxAttempts: integer inputs: ``` 文件的結構描述定義如下。 | 欄位 | 說明 | Type | 必要 | | --- | --- | --- | --- | | name | 文件的名稱。 | String | 否 | | description | 文件的描述。 | String | 否 | | schemaVersion | 文件的結構描述版本，目前為 1.0。 | String | 是 | | 階段 | 階段清單及其步驟。 | 清單 | 是 | 階段的結構描述定義如下所示。 | 欄位 | 說明 | Type | 必要 | | --- | --- | --- | --- | | name | 階段的名稱。 | String | 是 | | steps | 階段中的步驟清單。 | 清單 | 是 | 步驟的結構描述定義如下所示。 | 欄位 | 說明 | Type | 必要 | 預設值 | | --- | --- | --- | --- | --- | | name | 步驟的使用者定義名稱。 | String | | | | 動作 | 與執行 步驟之模組相關的關鍵字。 | String | | | | timeoutSeconds | 步驟在失敗或重試前執行的秒數。 此外， 支援 -1 值，表示無限逾時。不允許 0 和其他負值。 | Integer | 否 | 7，200 秒 (120 分鐘） | | onFailure | 指定步驟在失敗時應執行的動作。有效值如下： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/toe-use-documents.html) | String | 否 | 中止 | | maxAttempts | 在步驟失敗之前允許的嘗試次數上限。 | Integer | 否 | 1 | | inputs | 包含動作模組執行步驟所需的參數。 | 口述 | 是 | | ## 文件範例 下列範例顯示為目標作業系統執行任務的 AWSTOE 元件文件。 ------ #### [ Linux ] **範例 1：執行自訂二進位檔案** 以下是在 Linux 執行個體上下載並執行自訂二進位檔案的範例文件。 ``` name: LinuxBin description: Download and run a custom Linux binary file. schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://amzn-s3-demo-source-bucket/myapplication destination: /tmp/myapplication - name: Enable action: ExecuteBash onFailure: Continue inputs: commands: - 'chmod u+x {{ build.Download.inputs[0].destination }}' - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '--install' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` ------ #### [ Windows ] **範例 1：安裝 Windows 更新** 以下是安裝所有可用 Windows 更新、執行組態指令碼、在建立 AMI 之前驗證變更，以及在建立 AMI 之後測試變更的範例文件。 ``` name: RunConfig_UpdateWindows description: 'This document will install all available Windows updates and run a config script. It will then validate the changes before an AMI is created. Then after AMI creation, it will test all the changes.' schemaVersion: 1.0 phases: - name: build steps: - name: DownloadConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/config.ps1' destination: 'C:\config.ps1' - name: RunConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{build.DownloadConfigScript.inputs[0].destination}}' - name: Cleanup action: DeleteFile onFailure: Abort maxAttempts: 3 inputs: - path: '{{build.DownloadConfigScript.inputs[0].destination}}' - name: RebootAfterConfigApplied action: Reboot inputs: delaySeconds: 60 - name: InstallWindowsUpdates action: UpdateOS - name: validate steps: - name: DownloadTestConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/testConfig.ps1' destination: 'C:\testConfig.ps1' - name: ValidateConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{validate.DownloadTestConfigScript.inputs[0].destination}}' - name: Cleanup action: DeleteFile onFailure: Abort maxAttempts: 3 inputs: - path: '{{validate.DownloadTestConfigScript.inputs[0].destination}}' - name: test steps: - name: DownloadTestConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/testConfig.ps1' destination: 'C:\testConfig.ps1' - name: ValidateConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{test.DownloadTestConfigScript.inputs[0].destination}}' ``` **範例 2：在 Windows 執行個體 AWS CLI 上安裝** 以下是使用 安裝檔案在 Windows 執行個體 AWS CLI 上安裝 的範例文件。 ``` name: InstallCLISetUp description: Install &CLI; using the setup file schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://aws-cli/AWSCLISetup.exe destination: C:\Windows\temp\AWSCLISetup.exe - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '/install' - '/quiet' - '/norestart' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` **範例 3： AWS CLI 使用 MSI 安裝程式安裝** 以下是 AWS CLI 使用 MSI 安裝程式安裝 的範例文件。 ``` name: InstallCLIMSI description: Install &CLI; using the MSI installer schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://aws-cli/AWSCLI64PY3.msi destination: C:\Windows\temp\AWSCLI64PY3.msi - name: Install action: ExecuteBinary onFailure: Continue inputs: path: 'C:\Windows\System32\msiexec.exe' arguments: - '/i' - '{{ build.Download.inputs[0].destination }}' - '/quiet' - '/norestart' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` ------ #### [ macOS ] **範例 1：執行自訂 macOS 二進位檔案** 以下是在 macOS 執行個體上下載並執行自訂二進位檔案的範例文件。 ``` name: macOSBin description: Download and run a binary file on macOS. schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://amzn-s3-demo-source-bucket/myapplication destination: /tmp/myapplication - name: Enable action: ExecuteBash onFailure: Continue inputs: commands: - 'chmod u+x {{ build.Download.inputs[0].destination }}' - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '--install' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` ------ # 在自訂元件文件中使用變數 變數提供一種方法，以有意義的名稱標記資料，可用於整個應用程式。您可以為複雜工作流程定義具有簡單且可讀取格式的自訂變數，並在 AWS TOE 元件的 YAML 應用程式元件文件中參考它們。 本節提供的資訊可協助您在 YAML 應用程式 AWS TOE 元件文件中定義元件的變數，包括語法、名稱限制條件和範例。 ## 常數 常數是不可變的變數，一旦定義就無法修改或覆寫。您可以使用 AWS TOE 文件 `constants`區段中的值來定義常數。 **常數名稱的規則** + 名稱長度必須介於 3 到 128 個字元之間。 + 名稱只能包含英數字元 (a-z、A-Z、0-9)、破折號 (-) 或底線 (\$1)。 + 名稱在文件中必須是唯一的。 + 名稱必須指定為 YAML 字串。 **語法** ``` constants: - : type: value: ``` | 金鑰名稱 | 必要 | 描述 | | --- | --- | --- | | `name` | 是 | 常數的名稱。文件必須是唯一的 （不得與任何其他參數名稱或常數相同）。 | | `value` | 是 | 常數的值。 | | `type` | 是 | 常數的類型。支援的類型為 string。 | **參考文件中的常數值** 您可以在 YAML 文件內的步驟或迴圈輸入中參考常數，如下所示： + 常數參考區分大小寫，名稱必須完全相符。 + 名稱必須括在雙大括號 `{{` *MyConstant* 內`}}`。 + 大括號內允許空格，且會自動修剪。例如，下列所有參考都是有效的： `{{ MyConstant }}`, `{{ MyConstant}}`, `{{MyConstant }}`, `{{MyConstant}}` + YAML 文件中的參考必須指定為字串 （以單引號或雙引號括住）。 例如： `- {{ MyConstant }}` 無效，因為它未被識別為字串。 不過，下列參考皆有效： `- '{{ MyConstant }}'`和 `- "{{ MyConstant }}"`。 **範例** 步驟輸入中參考的常數 ``` name: Download AWS CLI version 2 schemaVersion: 1.0 constants: - Source: type: string value: https://awscli.amazonaws.com/AWSCLIV2.msi phases: - name: build steps: - name: Download action: WebDownload inputs: - source: '{{ Source }}' destination: 'C:\Windows\Temp\AWSCLIV2.msi' ``` 迴圈輸入中參考的常數 ``` name: PingHosts schemaVersion: 1.0 constants: - Hosts: type: string value: 127.0.0.1,amazon.com phases: - name: build steps: - name: Ping action: ExecuteBash loop: forEach: list: '{{ Hosts }}' delimiter: ',' inputs: commands: - ping -c 4 {{ loop.value }} ``` ## Parameters 參數是可變變數，具有呼叫應用程式可在執行時間提供的設定。您可以在 YAML 文件的 `Parameters`區段中定義參數。 **參數名稱的規則** + 名稱長度必須介於 3 到 128 個字元之間。 + 名稱只能包含英數字元 (a-z、A-Z、0-9)、破折號 (-) 或底線 (\$1)。 + 名稱在文件中必須是唯一的。 + 名稱必須指定為 YAML 字串。 ### 語法 ``` parameters: - : type: default: description: ``` | 金鑰名稱 | 必要 | 描述 | | --- | --- | --- | | `name` | 是 | 參數名稱。文件必須是唯一的 （不得與任何其他參數名稱或常數相同）。 | | `type` | 是 | 參數的資料類型。支援的類型包括：`string`。 | | `default` | 否 | 參數的預設值。 | | `description` | 否 | 描述 參數。 | ### 參考文件中的參數值 您可以在 YAML 文件內的步驟或迴圈輸入中參考參數，如下所示： + 參數參考區分大小寫，且名稱必須完全相符。 + 名稱必須括在雙大括號 `{{` *MyParameter* 內`}}`。 + 大括號內允許空格，且會自動修剪。例如，下列所有參考都是有效的： `{{ MyParameter }}`, `{{ MyParameter}}`, `{{MyParameter }}`, `{{MyParameter}}` + YAML 文件中的參考必須指定為字串 （以單引號或雙引號括住）。 例如： `- {{ MyParameter }}` 無效，因為它未被識別為字串。 不過，下列參考都有效： `- '{{ MyParameter }}'`和 `- "{{ MyParameter }}"`。 **範例** 下列範例示範如何在 YAML 文件中使用參數： + 請參閱步驟輸入中的參數： ``` name: Download AWS CLI version 2 schemaVersion: 1.0 parameters: - Source: type: string default: 'https://awscli.amazonaws.com/AWSCLIV2.msi' description: The AWS CLI installer source URL. phases: - name: build steps: - name: Download action: WebDownload inputs: - source: '{{ Source }}' destination: 'C:\Windows\Temp\AWSCLIV2.msi' ``` + 請參閱迴圈輸入中的參數： ``` name: PingHosts schemaVersion: 1.0 parameters: - Hosts: type: string default: 127.0.0.1,amazon.com description: A comma separated list of hosts to ping. phases: - name: build steps: - name: Ping action: ExecuteBash loop: forEach: list: '{{ Hosts }}' delimiter: ',' inputs: commands: - ping -c 4 {{ loop.value }} ``` ### 在執行時間覆寫參數 您可以從 AWS CLI 搭配索引鍵/值對使用 `--parameters`選項，在執行時間設定參數值。 + 將參數鍵/值對指定為名稱和值，並以等號 (=) 分隔。 + 多個參數必須以逗號分隔。 + 在 YAML 元件文件中找不到的參數名稱會被忽略。 + 參數名稱和值都是必要的。 **重要** 元件參數是純文字值，並會登入 AWS CloudTrail。建議您使用 AWS Secrets Manager 或 AWS Systems Manager 參數存放區來存放秘密。如需 Secrets Manager 的詳細資訊，請參閱*AWS Secrets Manager 《 使用者指南*》中的[什麼是 Secrets Manager？](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。如需 AWS Systems Manager 參數存放區的詳細資訊，請參閱*AWS Systems Manager 《 使用者指南*》中的[AWS Systems Manager 參數存放區](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)。 #### 語法 ``` --parameters name1=value1,name2=value2... ``` | CLI 選項 | 必要 | Description | | --- | --- | --- | | --parameters *name*=*value*，... | 否 | 此選項會取得索引鍵/值對的清單，並將參數名稱做為索引鍵。 | **範例** 下列範例示範如何在 YAML 文件中使用參數： + `--parameter` 此選項中指定的參數鍵/值對無效： ``` --parameters ntp-server= ``` + 使用 中的 `--parameter`選項設定一個參數鍵/值對 AWS CLI： ``` --parameters ntp-server=ntp-server-windows-qe.us-east1.amazon.com ``` + 使用 中的 `--parameter`選項設定多個參數鍵值對 AWS CLI： ``` --parameters ntp-server=ntp-server.amazon.com,http-url=https://internal-us-east1.amazon.com ``` ## 使用 Systems Manager 參數存放區參數 您可以在元件文件中參考 AWS Systems Manager 參數存放區參數 (SSM 參數），方法是使用 為變數加上字首`aws:ssm`。例如 `{{ aws:ssm:/my/param }}` 解析為 SSM 參數 的值`/my/param`。 此功能支援下列 SSM 參數類型： + 字串 – 對應至 AWS TOE 字串類型。 + StringList – 映射至 AWS TOE `stringList`類型。 + SecureString – 對應至 AWS TOE 字串類型。 如需參數存放區的詳細資訊，請參閱*AWS Systems Manager 《 使用者指南*》中的[AWS Systems Manager 參數存放](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)區。 您也可以使用 SSM 參數 來參考 AWS Secrets Manager 秘密`SecureString`。例如：`{{ aws:ssm:/aws/reference/secretsmanager/test/test-secret }}`。如需詳細資訊，請參閱[參考 AWS Secrets Manager 參數存放區參數中的秘密](https://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html)。 **重要** Image Builder 從其日誌中排除`SecureString`參數解析。不過，您也必須負責確保不會透過元件文件中發出的命令記錄敏感資訊。例如，如果您使用 `echo`命令搭配安全字串，命令會將純文字值寫入日誌。 ### 所需的 IAM 許可 若要在元件中使用 Systems Manager 參數，您的執行個體角色必須具有參數資源 ARN 的`ssm:GetParameter`許可。例如： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "ssm:GetParameter", "Resource": "arn:aws:ssm:*:111122223333:parameter/ImageBuilder-*" } ] } ``` ------ 若要存取加密的值，您也需要下列許可： + `kms:Decrypt` 針對使用客戶受管加密的`SecureString`參數或 AWS Secrets Manager 值新增 AWS KMS key。 + `secretsmanager:GetSecretValue` 如果您參考 Secrets Manager 秘密，請新增 。 ### 參考元件文件中的 SSM 參數 下列範例示範如何在元件中參考 Systems Manager 參數的 Systems Manager 參數存放區參數： ``` name: UseSSMParameterVariable description: This is a sample component document that prints out the value of an SSM Parameter. Never do this for a SecureString parameter. schemaVersion: 1.0 phases: - name: verify steps: - name: EchoParameterValue action: ExecuteBash inputs: commands: - echo "Log SSM parameter name: /my/test/param, value {{ aws:ssm:/my/test/param }}." ``` ### SSM 參數的動態執行期變數解析 AWSTOE 提供下列內建函數，您可以在變數參考內操作或轉換執行時間的值。 #### 解析函數 `resolve` 函數會在另一個變數參考內解析變數參考，允許動態變數名稱參考。這在使用 SSM 參數時非常有用，其中部分參數路徑可能是可變的，並以文件參數的形式傳入。 `resolve` 函數僅支援 SSM 參數名稱部分的動態解析。 ##### 語法 `dynamic_variable` 下列範例中的 代表 SSM 參數的名稱，且必須是下列其中一項： + SSM 參數參考 （例如 `aws:ssm:/my/param`) + 元件文件參數參考 （例如 `parameter-name`) ``` {{ aws:ssm:resolve(dynamic_variable) }} ``` ##### 範例：在執行時間解析 SSM 參數 下列範例示範如何在 YAML 元件文件中使用 `resolve`函數： ``` name: SsmParameterTest description: This component verifies an SSM parameter variable reference with the echo command. schemaVersion: 1.0 parameters: - parameter-name: type: string description: "test" phases: - name: validate steps: - name: PrintDynamicVariable action: ExecuteBash inputs: commands: - echo "{{ aws:ssm:resolve(parameter-name) }}" ``` # 在 中使用條件式建構 AWS TOE 條件式建構會根據指定的條件式表達式評估為 `true`或 ，在元件文件中執行不同的動作`false`。您可以使用 `if` 建構來控制元件文件中的執行流程。 ## 如果建構 您可以使用 `if` 建構來評估步驟是否應該執行。根據預設，當`if`條件式表達式評估為 `true`、 AWS TOE 執行 步驟，以及當條件評估為 時`false`， 會 AWS TOE 略過 步驟。如果略過步驟，則當 評估階段和文件是否成功執行時 AWS TOE ，會將其視為成功步驟。 **注意** 即使步驟觸發重新啟動， `if`陳述式只會評估一次。如果步驟重新啟動，則會辨識該`if`陳述式已進行評估，並繼續離開的位置。 ### 語法 ``` if: - : [then: ] [else: ] ``` | 金鑰名稱 | 必要 | Description | | --- | --- | --- | | 條件式表達式 | 是 | 條件式表達式在最上層可以包含以下其中一種類型的運算子。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/toe-conditional-constructs.html) 如果您的表達式必須符合多個條件，請使用邏輯運算子來指定您的條件。 | | then | 否 | 定義條件式表達式評估為 時要採取的動作`true`。 | | else | 否 | 定義條件式表達式評估為 時要採取的動作`false`。 | | 步驟動作 | 有條件 | 使用 `then`或 時`else`，您必須指定下列其中一個步驟動作： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/toe-conditional-constructs.html) | **範例 1：安裝套件** AWS TOE 元件文件中的下列範例步驟使用邏輯運算子來測試參數值，並在套件解壓縮時執行適當的套件管理員命令來安裝應用程式。 ``` - name: InstallUnzipAptGet action: ExecuteBash if: and: - binaryExists: 'apt-get' - not: binaryExists: 'unzip' inputs: commands: - sudo apt-get update - sudo apt-get install -y unzip - name: InstallUnzipYum action: ExecuteBash if: and: - binaryExists: 'yum' - not: binaryExists: 'unzip' inputs: commands: - sudo yum install -y unzip - name: InstallUnzipZypper action: ExecuteBash if: and: - binaryExists: 'zypper' - not: binaryExists: 'unzip' inputs: commands: - sudo zypper refresh - sudo zypper install -y unzip ``` **範例 2：略過步驟** 下列範例顯示略過步驟的兩種方式。一個使用邏輯運算子，另一個使用具有`Skip`步驟動作的比較運算子。 ``` # Creates a file if it does not exist using not - name: CreateMyConfigFile-1 action: ExecuteBash if: not: fileExists: '/etc/my_config' inputs: commands: - echo "Hello world" > '/etc/my_config' # Creates a file if it does not exist using then and else - name: CreateMyConfigFile-2 action: ExecuteBash if: fileExists: '/etc/my_config' then: Skip else: Execute inputs: commands: - echo "Hello world" > '/etc/my_config' ``` # 在 AWS TOE 元件文件中使用比較運算子 您可以搭配 **[聲明](toe-action-modules.md#action-modules-assertion)**動作模組和使用 的條件式表達式使用下列比較運算子[如果建構語法](toe-conditional-constructs.md#toe-conditional-if)。比較運算子可以在單一值上操作，例如 `stringIsEmpty`，也可以比較基準值與第二個值 （變數值），以判斷條件式表達式是否評估為 `true`或 `false`。 如果比較操作於兩個值，則第二個值可以是鏈結變數。 比較不同類型的值時，下列值轉換可能會在比較之前發生： + 對於數值比較，如果變數值是字串， 會在評估之前將字串 AWS TOE 轉換為數字。如果無法轉換，比較會傳回 `false`。例如，如果變數值為 `"1.0"`，則轉換會運作，但如果變數值為轉換`"a10"`會失敗。 + 對於字串比較，如果變數值是數字， 會在評估之前將其 AWS TOE 轉換為字串。 ## 比較字串 下列比較運算子使用字串來比較值、測試空格或空字串，或比較輸入值與規則運算式模式。字串比較不區分大小寫，而且不會從字串輸入的開頭或結尾修剪空格。 **字串比較運算子** + [stringIsEmpty](#stringIsEmpty) + [stringIsWhitespace](#stringIsWhitespace) + [stringEquals](#stringEquals) + [stringLessThan](#stringLessThan) + [stringLessThanEquals](#stringLessThanEquals) + [stringGreaterThan](#stringGreaterThan) + [stringGreaterThanEquals](#stringGreaterThanEquals) + [patternMatches](#patternMatches) **stringIsEmpty** `true` 如果指定的字串不包含任何字元，運算`stringIsEmpty`子會傳回 。例如： ``` # Evaluates to true stringIsEmpty: "" # Evaluates to false stringIsEmpty: " " # Evaluates to false stringIsEmpty: "Hello." ``` **stringIsWhitespace** 測試 指定的字串是否只`stringIsWhitespace`包含空格。例如： ``` # Evaluates to true stringIsWhitespace: " " # Evaluates to false stringIsWhitespace: "" # Evaluates to false stringIsWhitespace: " Hello?" ``` **stringEquals** 測試 指定的字串`stringEquals`是否與 `value` 參數中指定的字串完全相符。例如： ``` # Evaluates to true stringEquals: 'Testing, testing...' value: 'Testing, testing...' # Evaluates to false stringEquals: 'Testing, testing...' value: 'Hello again.' # Evaluates to false stringEquals: 'Testing, testing...' value: 'TESTING, TESTING....' # Evaluates to false stringEquals: 'Testing, testing...' value: ' Testing, testing...' # Evaluates to false stringEquals: 'Testing, testing...' value: 'Testing, testing... ' ``` **stringLessThan** 測試 指定的字串是否`stringLessThan`小於 `value` 參數中指定的字串。例如： ``` # Evaluates to true # This comparison operator isn't case sensitive stringlessThan: 'A' value: 'a' # Evaluates to true - 'a' is less than 'b' stringlessThan: 'b' value: 'a' # Evaluates to true # Numeric strings compare as less than alphabetic strings stringlessThan: 'a' value: '0' # Evaluates to false stringlessThan: '0' value: 'a' ``` **stringLessThanEquals** 測試為 指定的字串是否`stringLessThanEquals`小於或等於 `value` 參數中指定的字串。例如： ``` # Evaluates to true - 'a' is equal to 'a' stringLessThanEquals: 'a' value: 'a' # Evaluates to true - since the comparison isn't case sensitive, 'a' is equal to 'A' stringLessThanEquals: 'A' value: 'a' # Evaluates to true - 'a' is less than 'b' stringLessThanEquals: 'b' value: 'a' # Evaluates to true - '0' is less than 'a' stringLessThanEquals: 'a' value: '0' # Evaluates to false - 'a' is greater than '0' stringLessThanEquals: '0' value: 'a' ``` **stringGreaterThan** 測試 指定的字串是否`stringGreaterThan`大於 `value` 參數中指定的字串。例如： ``` # Evaluates to false - since the comparison isn't case sensitive, 'A' is equal to 'a' stringGreaterThan: 'a' value: 'A' # Evaluates to true - 'b' is greater than 'a' stringGreaterThan: 'a' value: 'b' # Evaluates to true - 'a' is greater than '0' stringGreaterThan: '0' value: 'a' # Evaluates to false - '0' is less than 'a' stringGreaterThan: 'a' value: '0' ``` **stringGreaterThanEquals** 測試為 指定的字串是否`stringGreaterThanEquals`大於或等於 `value` 參數中指定的字串。例如： ``` # Evaluates to true - 'a' is equal to 'A' stringGreaterThanEquals: 'A' value: 'a' # Evaluates to true - 'b' is greater than 'a' stringGreaterThanEquals: 'a' value: 'b' # Evaluates to true - 'a' is greater than '0' stringGreaterThanEquals: '0' value: 'a' # Evaluates to false - '0' is less than 'a' stringGreaterThanEquals: 'a' value: '0' ``` **patternMatches** 測試 `value` 參數中指定的字串是否符合為 指定的 regex 模式`patternMatches`。比較使用符合 RE2 語法的 [Golang regexp 套件](https://pkg.go.dev/regexp)。如需 RE2 規則的詳細資訊，請參閱 *GitHub* [中的 Google/re2](https://github.com/google/re2/wiki/Syntax) 儲存庫。 下列範例顯示傳回 的模式比對`true`： ``` patternMatches: '^[a-z]+$' value: 'ThisIsValue' ``` ## 比較數字 下列比較運算子使用數字。根據 YAML 規格，這些運算子提供的值必須是下列其中一種類型。對數值比較的支援使用 golang 大型套件比較運算子，例如：[func (\$1Float) Cmp](https://pkg.go.dev/math/big#Float.Cmp)。 + Integer + 浮點數 （以 float64 為基礎，支援從 -1.7e\$1308 到 \$11.7e\$1308 的數字） + 符合下列 regex 模式的字串： `^[-+]?([0-9]+[.])?[0-9]+$` **數字比較運算子** + [numberEquals](#numberEquals) + [numberLessThan](#numberLessThan) + [numberLessThanEquals](#numberLessThanEquals) + [numberGreaterThan](#numberGreaterThan) + [numberGreaterThanEquals](#numberGreaterThanEquals) **numberEquals** 測試 指定的數字是否`numberEquals`等於 `value` 參數中指定的數字。下列所有範例比較都會傳回 `true`： ``` # Values provided as a positive number numberEquals: 1 value: 1 # Comparison value provided as a string numberEquals: '1' value: 1 # Value provided as a string numberEquals: 1 value: '1' # Values provided as floats numberEquals: 5.0 value: 5.0 # Values provided as a negative number numberEquals: -1 value: -1 ``` **numberLessThan** 測試 指定的數字是否`numberLessThan`小於 `value` 參數中指定的數字。例如： ``` # Evaluates to true numberLessThan: 2 value: 1 # Evaluates to true numberLessThan: 2 value: 1.9 # Evaluates to false numberLessThan: 2 value: '2' ``` **numberLessThanEquals** 測試 指定的數字是否`numberLessThanEquals`小於或等於 `value` 參數中指定的數字。例如： ``` # Evaluates to true numberLessThanEquals: 2 value: 1 # Evaluates to true numberLessThanEquals: 2 value: 1.9 # Evaluates to true numberLessThanEquals: 2 value: '2' # Evaluates to false numberLessThanEquals: 2 value: 2.1 ``` **numberGreaterThan** 測試 指定的數字是否`numberGreaterThan`大於 `value` 參數中指定的數字。例如： ``` # Evaluates to true numberGreaterThan: 1 value: 2 # Evaluates to true numberGreaterThan: 1 value: 1.1 # Evaluates to false numberGreaterThan: 1 value: '1' ``` **numberGreaterThanEquals** 測試 指定的數字是否`numberGreaterThanEquals`大於或等於 `value` 參數中指定的數字。例如： ``` # Evaluates to true numberGreaterThanEquals: 1 value: 2 # Evaluates to true numberGreaterThanEquals: 1 value: 1.1 # Evaluates to true numberGreaterThanEquals: 1 value: '1' # Evaluates to false numberGreaterThanEquals: 1 value: 0.8 ``` ## 檢查檔案 下列比較運算子會檢查檔案雜湊，或檢查檔案或資料夾是否存在。 **檔案和資料夾運算子** + [binaryExists](#binaryExists) + [fileExists](#fileExists) + [folderExists](#folderExists) + [fileMD5Equals](#fileMD5Equals) + [fileSHA1Equals](#fileSHA1Equals) + [fileSHA256Equals](#fileSHA256Equals) + [fileSHA512Equals](#fileSHA512Equals) **binaryExists** 測試應用程式是否可在目前路徑中使用。例如： ``` binaryExists: 'foo' ``` 在 Linux 和 macOS 系統上，對於名為 *foo* 的應用程式，其運作方式與下列 bash 命令相同：**type *foo* >/dev/null 2>&1**，其中 **\$1? == 0**表示成功比較。 在 Windows 系統上，對於名為 *foo* 的應用程式，這的運作方式與 PowerShell 命令相同**& C:\$1Windows\$1System32\$1where.exe /Q *foo***，其中 **\$1LASTEXITCODE = 0**表示成功比較。 **fileExists** 測試檔案是否存在於指定的路徑。您可以提供絕對或相對路徑。如果您指定的位置存在且為 檔案，則比較會評估為 `true`。例如： ``` fileExists: '/path/to/file' ``` 在 Linux 和 macOS 系統上，這的運作方式與下列 bash 命令相同：**-d */path/to/file***，其中 **\$1? == 0**表示成功比較。 在 Windows 系統上，這的運作方式與 PowerShell 命令 相同**Test-Path -Path '*C:\$1path\$1to\$1file*' -PathType 'Leaf'**。 **folderExists** 測試資料夾是否存在於指定的路徑。您可以提供絕對或相對路徑。如果您指定的位置存在且 是資料夾，則比較會評估為 `true`。例如： ``` folderExists: '/path/to/folder' ``` 在 Linux 和 macOS 系統上，這的運作方式與下列 bash 命令相同：**-d */path/to/folder***，其中 **\$1? == 0**表示成功比較。 在 Windows 系統上，這的運作方式與 PowerShell 命令 相同**Test-Path -Path '*C:\$1path\$1to\$1folder*' -PathType 'Container'**。 **fileMD5Equals** 測試檔案的 MD5 雜湊是否等於指定的值。例如： ``` fileMD5Equals: '' path: '/path/to/file' ``` **fileSHA1Equals** 測試檔案的 SHA1 雜湊是否等於指定的值。例如： ``` fileSHA1Equals: '' path: '/path/to/file' ``` **fileSHA256Equals** 測試檔案的 SHA256 雜湊是否等於指定的值。例如： ``` fileSHA256Equals: '' path: '/path/to/file' ``` **fileSHA512Equals** 測試檔案的 SHA512 雜湊是否等於指定的值。例如： ``` fileSHA512Equals: '' path: '/path/to/file' ``` # 在 AWS TOE 元件文件中使用邏輯運算子 您可以使用下列邏輯運算子來新增或修改元件文件中的條件式表達式。 會依條件的指定順序 AWS TOE 評估條件式表達式。如需元件文件比較運算子的詳細資訊，請參閱 [在 AWS TOE 元件文件中使用比較運算子](toe-comparison-operators.md)。 **而且** 使用 `and`運算子，您可以將兩個或多個比較評估為單一表達式。當清單中的所有條件都是 true `true`時，表達式會評估為 。否則，表達式會評估為 `false`。 **範例：** 下列範例會執行兩個比較：字串和數字。這兩個比較都是 true，因此表達式會評估為 true。 ``` and: - stringEquals: 'test_string' value: 'test_string' - numberEquals: 1 value: 1 ``` 下列範例也會執行兩個比較。第一個比較是 false，此時評估會停止並略過第二個比較。表達式會評估為 `false`。 ``` and: - stringEquals: 'test_string' value: 'Hello world!' - numberEquals: 1 value: 1 ``` **或** 使用 `or`運算子，您可以將兩個或多個比較評估為單一表達式。當其中一個指定的比較為 true `true`時，表達式會評估為 。如果沒有指定的比較評估為 `true`，則表達式評估為 `false`。 **範例：** 下列範例會執行兩個比較：字串和數字。第一個比較是 true，因此表達式會評估為 `true`，並略過第二個比較。 ``` or: - stringEquals: 'test_string' value: 'test_string' - numberEquals: 1 value: 3 ``` 下列範例也會執行兩個比較。第一個比較是 false，評估會繼續進行。第二個比較是 true，因此表達式會評估為 `true`。 ``` or: - stringEquals: 'test_string' value: 'Hello world!' - numberEquals: 1 value: 1 ``` 在最後一個範例中，兩個比較都是 false，因此表達式會評估為 `false`。 ``` or: - stringEquals: 'test_string' value: 'Hello world!' - numberEquals: 1 value: 3 ``` **不是** 使用 `not`運算子，您可以否定單一比較。如果比較為 false`true`，表達式會評估為 。如果比較為 true，則表達式會評估為 `false`。 **範例：** 下列範例會執行字串比較。比較為 false，因此表達式會評估為 `true`。 ``` not: - stringEquals: 'test_string' value: 'Hello world!' ``` 下列範例也會執行字串比較。比較是 true，因此表達式會評估為 `false`。 ``` not: - stringEquals: 'test_string' value: 'test_string' ``` # 在 中使用迴圈建構 AWS TOE 本節提供的資訊可協助您在 中建立迴圈建構 AWS TOE。循環建構定義一系列重複的指示。您可以在 中使用下列類型的循環建構 AWS TOE： + `for` 建構 – 反覆運算整數的邊界序列。 + `forEach` 建構 + `forEach` 具有輸入清單的迴圈 – 反覆運算字串的有限集合。 + `forEach` 使用分隔清單的迴圈 – 反覆運算由分隔符號聯結的有限字串集合。 **注意** 迴圈建構模組僅支援字串資料類型。 **Topics** + [參考反覆運算變數](#toe-loop-iteration-variables) + [迴圈建構的類型](#toe-loop-types) + [步驟欄位](#toe-loop-step-fields) + [步驟和反覆運算輸出](#toe-loop-step-output) ## 參考反覆運算變數 若要參考目前反覆運算變數的索引和值，`{{ loop.* }}`必須在包含循環建構的步驟輸入內使用參考表達式。此表達式無法用來參考另一個步驟的迴圈建構的反覆運算變數。 參考表達式包含下列成員： + `{{ loop.index }}` – 目前反覆運算的順序位置，其索引為 `0`。 + `{{ loop.value }}` – 與目前反覆運算變數相關聯的值。 ### 迴圈名稱 所有循環建構都有用於識別的選用名稱欄位。如果提供迴圈名稱，則可用來參考步驟輸入內文中的反覆運算變數。若要參考具名迴圈的反覆運算索引和值，請在步驟的輸入內文`{{ loop.* }}`中使用 `{{ .* }}` 搭配 。此表達式無法用來參考另一個步驟的具名迴圈建構。 參考表達式包含下列成員： + `{{ .index }}` – 具名迴圈目前反覆運算的順序位置，其索引為 `0`。 + `{{ .value }}` – 與具名迴圈的目前反覆運算變數相關聯的值。 ### 解決參考表達式 會 AWS TOE 解析參考表達式，如下所示： + `{{ .* }}` –使用以下邏輯 AWS TOE 解決此表達式： + 如果目前執行步驟的迴圈符合 ``值，則參考表達式會解析為目前執行步驟的迴圈建構。 + `` 如果在目前執行的步驟中出現， 會解析為具名迴圈建構。 + `{{ loop.* }}` –使用目前執行步驟中定義的迴圈建構來 AWS TOE 解析表達式。 如果在不包含迴圈的步驟中使用參考表達式，則 AWS TOE 不會解析表達式，並且它們會出現在步驟中，而不會替換。 **注意** 參考表達式必須以雙引號括住，以便 YAML 編譯器正確解譯。 ## 迴圈建構的類型 本節提供有關迴圈可在 中使用的建構類型的資訊和範例 AWS TOE。 **Topics** + [`for` 迴圈](#toe-loop-types-for) + [`forEach` 具有輸入清單的迴圈](#toe-loop-types-foreach) + [`forEach` 具有分隔清單的迴圈](#toe-loop-types-foreach-delimited) ### `for` 迴圈 `for` 迴圈會在變數開始和結束所概述的邊界內指定的整數範圍上反覆運算。反覆運算值位於集合中`[start, end]`，並包含邊界值。 AWS TOE 驗證 `start`、 `end`和 `updateBy`值，以確保組合不會造成無限迴圈。 `for` 迴圈結構描述 ``` - name: "StepName" action: "ActionModule" loop: name: "string" for: start: int end: int updateBy: int inputs: ... ``` **`for` 迴圈輸入** | 欄位 | 說明 | Type | 必要 | 預設 | | --- | --- | --- | --- | --- | | `name` | 迴圈的唯一名稱。與相同階段中的其他迴圈名稱相比，它必須是唯一的。 | String | 否 | "" | | `start` | 反覆運算的起始值。不接受鏈結表達式。 | Integer | 是 | N/A | | `end` | 反覆運算的結束值。不接受鏈結表達式。 | Integer | 是 | N/A | | `updateBy` | 透過新增更新反覆運算值的差異。它必須是負值或非零值。不接受鏈結表達式。 | Integer | 是 | N/A | `for` 迴圈輸入範例 ``` - name: "CalculateFileUploadLatencies" action: "ExecutePowerShell" loop: for: start: 100000 end: 1000000 updateBy: 100000 inputs: commands: - | $f = new-object System.IO.FileStream c:\temp\test{{ loop.index }}.txt, Create, ReadWrite $f.SetLength({{ loop.value }}MB) $f.Close() - c:\users\administrator\downloads\latencyTest.exe --file c:\temp\test{{ loop.index }}.txt - AWS s3 cp c:\users\administrator\downloads\latencyMetrics.json s3://bucket/latencyMetrics.json - | Remove-Item -Path c:\temp\test{{ loop.index }}.txt Remove-Item -Path c:\users\administrator\downloads\latencyMetrics.json ``` ### `forEach` 具有輸入清單的迴圈 `forEach` 迴圈會在明確值清單上反覆運算，可以是字串和鏈結表達式。 `forEach` 具有輸入清單結構描述的迴圈 ``` - name: "StepName" action: "ActionModule" loop: name: "string" forEach: - "string" inputs: ... ``` **`forEach` 具有輸入清單輸入的迴圈** | 欄位 | 說明 | Type | 必要 | 預設 | | --- | --- | --- | --- | --- | | `name` | 迴圈的唯一名稱。與相同階段中的其他迴圈名稱相比，它必須是唯一的。 | String | 否 | "" | | `forEach` 迴圈字串清單 | 反覆運算的字串清單。接受鏈結表達式做為清單中的字串。鏈結表達式必須以雙引號括住，YAML 編譯器才能正確解譯。 | 字串清單 | 是 | N/A | `forEach` 具有輸入清單的迴圈範例 1 ``` - name: "ExecuteCustomScripts" action: "ExecuteBash" loop: name: BatchExecLoop forEach: - /tmp/script1.sh - /tmp/script2.sh - /tmp/script3.sh inputs: commands: - echo "Count {{ BatchExecLoop.index }}" - sh "{{ loop.value }}" - | retVal=$? if [ $retVal -ne 0 ]; then echo "Failed" else echo "Passed" fi ``` `forEach` 具有輸入清單的迴圈範例 2 ``` - name: "RunMSIWithDifferentArgs" action: "ExecuteBinary" loop: name: MultiArgLoop forEach: - "ARG1=C:\Users ARG2=1" - "ARG1=C:\Users" - "ARG1=C:\Users ARG3=C:\Users\Administrator\Documents\f1.txt" inputs: commands: path: "c:\users\administrator\downloads\runner.exe" args: - "{{ MultiArgLoop.value }}" ``` `forEach` 具有輸入清單的迴圈範例 3 ``` - name: "DownloadAllBinaries" action: "S3Download" loop: name: MultiArgLoop forEach: - "bin1.exe" - "bin10.exe" - "bin5.exe" inputs: - source: "s3://bucket/{{ loop.value }}" destination: "c:\temp\{{ loop.value }}" ``` ### `forEach` 具有分隔清單的迴圈 迴圈會反覆運算字串，其中包含以分隔符號分隔的值。若要反覆運算字串的元件， AWS TOE 請使用分隔符號將字串分割為適合反覆運算的陣列。 `forEach` 具有分隔清單結構描述的迴圈 ``` - name: "StepName" action: "ActionModule" loop: name: "string" forEach: list: "string" delimiter: ".,;:\n\t -_" inputs: ... ``` **`forEach` 具有分隔清單輸入的迴圈** | 欄位 | 說明 | Type | 必要 | 預設 | | --- | --- | --- | --- | --- | | `name` | 提供給迴圈的唯一名稱。與相同階段中的其他迴圈名稱相比，它應該是唯一的。 | String | 否 | "" | | `list` | 由共同分隔符號字元聯結的組成字串組成的字串。也接受鏈結表達式。如果是鏈結表達式，請確保以雙引號括住這些表達式，以便 YAML 編譯器正確解譯。 | String | 是 | N/A | | `delimiter` | 用來分隔區塊中字串的字元。預設為逗號字元。指定清單中只允許一個分隔符號字元：[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/toe-looping-constructs.html) 無法使用鏈結表達式。 | String | 否 | 逗號： "," | **注意** 的值`list`視為不可變字串。如果在執行時間`list`變更 的來源，則不會在執行期間反映。 `forEach` 使用分隔清單的迴圈範例 1 此範例使用下列鏈結表達式模式來參考另一個步驟的輸出：`..[inputs | outputs].`。 ``` - name: "RunMSIs" action: "ExecuteBinary" loop: forEach: list: "{{ build.GetAllMSIPathsForInstallation.outputs.stdout }}" delimiter: "\n" inputs: commands: path: "{{ loop.value }}" ``` `forEach` 使用分隔清單的迴圈範例 2 ``` - name: "UploadMetricFiles" action: "S3Upload" loop: forEach: list: "/tmp/m1.txt,/tmp/m2.txt,/tmp/m3.txt,..." inputs: commands: - source: "{{ loop.value }}" destination: "s3://bucket/key/{{ loop.value }}" ``` ## 步驟欄位 迴圈是步驟的一部分。任何與執行步驟相關的欄位都不會套用至個別反覆運算。步驟欄位僅適用於步驟層級，如下所示： + *timeoutSeconds* – 迴圈的所有反覆運算必須在此欄位指定的期間內執行。如果迴圈執行逾時，則 會 AWS TOE 執行步驟的重試政策，並重設每次新嘗試的逾時參數。如果迴圈執行在達到重試次數上限後超過逾時值，步驟的失敗訊息會指出迴圈執行已逾時。 + *onFailure* – 失敗處理會套用至步驟，如下所示： + 如果 *onFailure* 設定為 `Abort`，則會 AWS TOE 退出迴圈，並根據重試政策重試步驟。在重試嘗試次數上限之後， 會將目前步驟 AWS TOE 標記為失敗，並停止執行程序。 AWS TOE 會將父階段的狀態碼和文件設定為 `Failed`。 **注意** 在失敗的步驟之後，不會執行任何進一步的步驟。 + 如果 *onFailure* 設定為 `Continue`， AWS TOE 會結束迴圈，並根據重試政策重試步驟。在重試嘗試次數上限之後， 會將目前步驟 AWS TOE 標記為失敗，並繼續執行下一個步驟。 AWS TOE 會將父階段的狀態碼和文件設定為 `Failed`。 + 如果 *onFailure* 設定為 `Ignore`， AWS TOE 會結束迴圈，並根據重試政策重試步驟。在重試嘗試次數上限之後， 會將目前步驟 AWS TOE 標記為 `IgnoredFailure`，並繼續執行下一個步驟。 AWS TOE 會將父階段的狀態碼和文件設定為 `SuccessWithIgnoredFailure`。 **注意** 這仍然被視為成功執行，但包含的資訊會讓您知道一或多個步驟失敗並被忽略。 + *maxAttempts * – 每次重試時，整個步驟和所有反覆運算都會從頭開始執行。 + *狀態* – 步驟執行的整體狀態。`status` 不代表個別反覆運算的狀態。具有迴圈之步驟的狀態決定如下： + 如果單一反覆運算無法執行，步驟的狀態會指向失敗。 + 如果所有反覆運算都成功，步驟的狀態會指向成功。 + *startTime * – 步驟執行的整體開始時間。不代表個別反覆運算的開始時間。 + *endTime * – 步驟執行的整體結束時間。不代表個別反覆運算的結束時間。 + *failureMessage * – 包含非逾時錯誤時失敗的反覆運算索引。如果發生逾時錯誤，訊息會指出迴圈執行失敗。不會針對每個反覆運算提供個別錯誤訊息，以將失敗訊息的大小降至最低。 ## 步驟和反覆運算輸出 每次反覆運算都包含輸出。在迴圈執行結束時， 會 AWS TOE 整合 中所有成功的反覆運算輸出`detailedOutput.json`。合併輸出是屬於動作模組輸出結構描述中定義之對應輸出索引鍵的值定序。下列範例顯示輸出的合併方式： **適用於反覆運算 1 `ExecuteBash`的 輸出** ``` { "stdout":"Hello" } ``` **適用於反覆運算 2 `ExecuteBash`的 輸出** ``` { "stdout":"World" } ``` **`ExecuteBash`適用於步驟的 輸出** ``` { "stdout":"Hello\nWorld" } ``` 例如，`ExecuteBash`、 `ExecutePowerShell`和 `ExecuteBinary`是`STDOUT`作為動作模組輸出傳回的動作模組。`STDOUT`訊息會加入新的行字元，以在 中產生步驟的整體輸出`detailedOutput.json`。 AWS TOE 不會合併失敗反覆運算的輸出。 # AWS TOE 元件管理員支援的動作模組 映像建置服務，例如 EC2 Image Builder，使用 AWS TOE 動作模組來協助設定用於建置和測試自訂機器映像的 EC2 執行個體。本節說明常用 AWS TOE 動作模組的功能，以及如何設定這些功能，包括範例。 元件是以純文字 YAML 文件撰寫。如需文件語法的詳細資訊，請參閱 [使用自訂 AWS TOE 元件的元件文件架構](toe-use-documents.md)。 **注意** 所有動作模組在執行時使用與 Systems Manager 代理程式相同的帳戶，即 `root` Linux 和 Windows `NT Authority\SYSTEM`上的 。 下列交叉參考會根據動作模組執行的動作類型來分類動作模組。   **一般執行** + [Assert (Linux、Windows、macOS)](#action-modules-assertion) + [ExecuteBash (Linux、macOS)](#action-modules-executebash) + [ExecuteBinary (Linux、Windows、macOS)](#action-modules-executebinary) + [ExecuteDocument (Linux、Windows、macOS)](#action-modules-executedocument) + [ExecutePowerShell (Windows)](#action-modules-executepowershell)   **檔案下載和上傳** + [S3Download (Linux、Windows、macOS)](#action-modules-s3download) + [S3Upload (Linux、Windows、macOS)](#action-modules-s3upload) + [WebDownload (Linux、Windows、macOS)](#action-modules-webdownload)   **檔案系統操作** + [AppendFile (Linux、Windows、macOS)](#action-modules-appendfile) + [CopyFile (Linux、Windows、macOS)](#action-modules-copyfile) + [CopyFolder (Linux、Windows、macOS)](#action-modules-copyfolder) + [CreateFile (Linux、Windows、macOS)](#action-modules-createfile) + [CreateFolder (Linux、Windows、macOS)](#action-modules-createfolder) + [CreateSymlink (Linux、Windows、macOS)](#action-modules-createsymlink) + [DeleteFile (Linux、Windows、macOS)](#action-modules-deletefile) + [DeleteFolder (Linux、Windows、macOS)](#action-modules-deletefolder) + [ListFiles (Linux、Windows、macOS)](#action-modules-listfiles) + [MoveFile (Linux、Windows、macOS)](#action-modules-movefile) + [MoveFolder (Linux、Windows、macOS)](#action-modules-movefolder) + [ReadFile (Linux、Windows、macOS)](#action-modules-readfile) + [SetFileEncoding (Linux、Windows、macOS)](#action-modules-setfileencoding) + [SetFileOwner (Linux、Windows、macOS)](#action-modules-setfileowner) + [SetFolderOwner (Linux、Windows、macOS)](#action-modules-setfolderowner) + [SetFilePermissions (Linux、Windows、macOS)](#action-modules-setfilepermissions) + [SetFolderPermissions (Linux、Windows、macOS)](#action-modules-setfolderpermissions)   **軟體安裝動作** + [InstallMSI (Windows)](#action-modules-install-msi) + [UninstallMSI (Windows)](#action-modules-uninstall-msi)   **系統動作** + [重新啟動 (Linux、Windows)](#action-modules-reboot) + [SetRegistry (Windows)](#action-modules-setregistry) + [UpdateOS (Linux、Windows)](#action-modules-updateos) ## 一般執行模組 下一節包含執行命令和控制執行工作流程之動作模組的詳細資訊。 **Topics** + [Assert (Linux、Windows、macOS)](#action-modules-assertion) + [ExecuteBash (Linux、macOS)](#action-modules-executebash) + [ExecuteBinary (Linux、Windows、macOS)](#action-modules-executebinary) + [ExecuteDocument (Linux、Windows、macOS)](#action-modules-executedocument) + [ExecutePowerShell (Windows)](#action-modules-executepowershell) ### Assert (Linux、Windows、macOS) **Assert** 動作模組會使用 [比較運算子](toe-comparison-operators.md)或 [邏輯運算子](toe-logical-operators.md)做為輸入來執行值比較。運算子表達式的結果 (true 或 false) 表示步驟的整體成功或失敗狀態。 如果比較或邏輯運算子表達式評估為 `true`，則步驟會標記為 `Success`。否則，步驟會標示為 `Failed`。如果步驟失敗， `onFailure` 參數會決定步驟的結果。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | | --- | --- | --- | --- | | input | 包含單一比較或邏輯運算子。請注意，邏輯運算子可以包含多個比較運算子。 | 這是變數，取決於運算子 | 是 | **輸入範例：使用比較運算子的簡單`stringEquals`比較** 此範例評估為 `true`。 ``` - name: StringComparison action: Assert inputs: stringEquals: '2.1.1' value: '{{ validate.ApplicationVersion.outputs.stdout }}' ``` **輸入範例：使用比較運算子進行 Regex `patternMatches`比較** 這些範例都會評估為 `true`。 ``` - name: Letters only action: Assert inputs: patternMatches: '^[a-zA-Z]+$' value: 'ThisIsOnlyLetters' - name: Letters and spaces only action: Assert inputs: patternMatches: '^[a-zA-Z\s]+$' value: 'This text contains spaces' - name: Numbers only action: Assert inputs: patternMatches: '^[0-9]+$' value: '1234567890' ``` **輸入範例：與邏輯運算子和鏈結變數的巢狀比較** 下列範例示範與邏輯運算子的巢狀比較，這些運算子使用鏈結變數的比較。`true` 如果下列任一項為 true，則 會`Assert`評估為 ： + `ApplicationVersion` 大於 `2.0`且 `CPUArchitecture`等於 `arm64`。 + `CPUArchitecture` 等於 `x86_64`。 ``` - name: NestedComparisons action: Assert inputs: or: # <- first level deep - and: # <- second level deep - numberGreaterThan: 2.0 # <- third level deep value: '{{ validate.ApplicationVersion.outputs.stdout }}' - stringEquals: 'arm64' value: '{{ validate.CPUArchitecture.outputs.stdout }}' - stringEquals: 'x86_64' value: '{{ validate.CPUArchitecture.outputs.stdout }}' ``` **輸出：** 的輸出`Assert`是步驟的成功或失敗。 ### ExecuteBash (Linux、macOS) **ExecuteBash** 動作模組可讓您使用內嵌 shell 程式碼/命令執行 bash 指令碼。此模組支援 Linux。 您在命令區塊中指定的所有命令和指示都會轉換為檔案 （例如 `input.sh`)，並使用 bash shell 執行。執行 shell 檔案的結果是 步驟的結束碼。 如果指令碼以 的結束代碼結束，則 **ExecuteBash** 模組會處理系統重新啟動`194`。啟動時，應用程式會執行下列其中一個動作： + 如果由 Systems Manager Agent 執行，應用程式會將結束碼交給發起人。Systems Manager 代理程式會處理系統重新啟動，並執行啟動重新啟動的相同步驟，如[從指令碼重新啟動受管執行個體](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html)中所述。 + 應用程式會儲存目前的 `executionstate`、設定重新啟動觸發以重新執行應用程式，以及重新啟動系統。 系統重新啟動後，應用程式會執行與啟動重新啟動相同的步驟。如果您需要此功能，您必須撰寫等冪指令碼，以處理相同 shell 命令的多個調用。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | | --- | --- | --- | --- | | commands | 包含根據 bash 語法執行的指示或命令清單。允許多行 YAML。 | 清單 | 是 | **輸入範例：重新啟動之前和之後** ``` name: ExitCode194Example description: This shows how the exit code can be used to restart a system with ExecuteBash schemaVersion: 1.0 phases: - name: build steps: - name: RestartTrigger action: ExecuteBash inputs: commands: - | REBOOT_INDICATOR=/var/tmp/reboot-indicator if [ -f "${REBOOT_INDICATOR}" ]; then echo 'The reboot file exists. Deleting it and exiting with success.' rm "${REBOOT_INDICATOR}" exit 0 fi echo 'The reboot file does not exist. Creating it and triggering a restart.' touch "${REBOOT_INDICATOR}" exit 194 ``` **Output** | 欄位 | 說明 | Type | | --- | --- | --- | | stdout | 命令執行的標準輸出。 | string | 如果您啟動重新啟動並傳回結束程式碼`194`做為動作模組的一部分，建置將在啟動重新啟動的相同動作模組步驟繼續。如果您在沒有結束碼的情況下啟動重新啟動，建置程序可能會失敗。 **輸出範例：重新啟動之前 （第一次通過文件）** ``` { “stdout”: “The reboot file does not exist. Creating it and triggering a restart." } ``` **輸出範例：重新啟動後， （文件的第二次）** ``` { “stdout”: “The reboot file exists. Deleting it and exiting with success." } ``` ### ExecuteBinary (Linux、Windows、macOS) **ExecuteBinary** 動作模組可讓您使用命令列引數清單執行二進位檔案。 如果二進位檔案以 `194`(Linux) 或 (`3010`Windows) 的結束碼結束，則 **ExecuteBinary** 模組會處理系統重新啟動。發生這種情況時，應用程式會執行下列其中一個動作： + 如果由 Systems Manager Agent 執行，應用程式會將結束碼交給發起人。Systems Manager 代理程式會處理重新啟動系統，並執行啟動重新啟動的相同步驟，如[從指令碼重新啟動受管執行個體](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html)中所述。 + 應用程式會儲存目前的 `executionstate`、設定重新啟動觸發以重新執行應用程式，以及重新啟動系統。 系統重新啟動後，應用程式會執行與啟動重新啟動相同的步驟。如果您需要此功能，您必須撰寫等冪指令碼，以處理相同 shell 命令的多個調用。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | | --- | --- | --- | --- | | path | 二進位檔案的執行路徑。 | String | 是 | | arguments | 包含執行二進位檔時要使用的命令列引數清單。 | 字串清單 | 否 | **輸入範例：安裝 .NET** ``` - name: "InstallDotnet" action: ExecuteBinary inputs: path: C:\PathTo\dotnet_installer.exe arguments: - /qb - /norestart ``` **Output** | 欄位 | 說明 | Type | | --- | --- | --- | | stdout | 命令執行的標準輸出。 | string | **輸出範例** ``` { "stdout": "success" } ``` ### ExecuteDocument (Linux、Windows、macOS) **ExecuteDocument** 動作模組新增了對巢狀元件文件的支援，從一個文件中執行多個元件文件。 會在執行時間 AWS TOE 驗證在輸入參數中傳遞的文件。 **限制** + 此動作模組執行一次，不允許重試，也不允許設定逾時限制的選項。**ExecuteDocument** 會設定下列預設值，並在您嘗試變更時傳回錯誤。 + `timeoutSeconds`：-1 + `maxAttempts`：1 **注意** 您可以將這些值保留空白，並使用 AWS TOE 預設值。 + 允許文件巢狀化，最多三個層級深度，但不超過此層級。三種巢狀層級會轉換為四個文件層級，因為頂層不會巢狀化。在此案例中，最低層級的文件不得呼叫任何其他文件。 + 不允許重複執行元件文件。在迴圈建構模組之外呼叫自己，或呼叫目前執行鏈中較高之其他文件的任何文件，都會啟動一個週期，進而產生無限迴圈。當 AWS TOE 偵測到循環執行時，它會停止執行並記錄失敗。 ![\[ExecuteDocument 動作模組的巢狀層級限制。\]](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/images/toe-component-document-nesting.png) 如果元件文件嘗試自行執行，或執行目前執行鏈中更高的任何元件文件，則執行會失敗。 **輸入** | 金鑰名稱 | 說明 | Type | 必要 | | --- | --- | --- | --- | | document | 元件文件的路徑。有效的選項包含： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/toe-action-modules.html) | String | 是 | | document-s3-bucket-owner | 存放元件文件之 S3 儲存貯體的 S3 儲存貯體擁有者的帳戶 ID。*（如果您在元件文件中使用 S3 URIs則建議使用。)* | String | 否 | | phases | 在元件文件中執行的階段，以逗號分隔清單表示。如果未指定階段，則所有階段都會執行。 | String | 否 | | parameters | 在執行時間傳入元件文件的輸入參數，做為索引鍵值對。 | 參數映射清單 | 否 | **參數映射輸入** | 金鑰名稱 | 說明 | Type | 必要 | | --- | --- | --- | --- | | name | 要傳遞至 **ExecuteDocument** 動作模組正在執行之元件文件的輸入參數名稱。 | String | 是 | | value | 輸入參數的值。 | String | 是 | **輸入範例** 以下範例顯示元件文件的輸入變化，取決於您的安裝路徑。 **輸入範例：本機文件路徑** ``` # main.yaml schemaVersion: 1.0 phases: - name: build steps: - name: ExecuteNestedDocument action: ExecuteDocument inputs: document: Sample-1.yaml phases: build parameters: - name: parameter-1 value: value-1 - name: parameter-2 value: value-2 ``` **輸入範例：做為文件路徑的 S3 URI** ``` # main.yaml schemaVersion: 1.0 phases: - name: build steps: - name: ExecuteNestedDocument action: ExecuteDocument inputs: document: s3://my-bucket/Sample-1.yaml document-s3-bucket-owner: 123456789012 phases: build,validate parameters: - name: parameter-1 value: value-1 - name: parameter-2 value: value-2 ``` **輸入範例：EC2 Image Builder 元件 ARN 做為文件路徑** ``` # main.yaml schemaVersion: 1.0 phases: - name: build steps: - name: ExecuteNestedDocument action: ExecuteDocument inputs: document: arn:aws:imagebuilder:us-west-2:aws:component/Sample-Test/1.0.0 phases: test parameters: - name: parameter-1 value: value-1 - name: parameter-2 value: value-2 ``` **使用 ForEach 迴圈來執行文件** ``` # main.yaml schemaVersion: 1.0 phases: - name: build steps: - name: ExecuteNestedDocument action: ExecuteDocument loop: name: 'myForEachLoop' forEach: - Sample-1.yaml - Sample-2.yaml inputs: document: "{{myForEachLoop.value}}" phases: test parameters: - name: parameter-1 value: value-1 - name: parameter-2 value: value-2 ``` **使用 For 迴圈來執行文件** ``` # main.yaml schemaVersion: 1.0 phases: - name: build steps: - name: ExecuteNestedDocument action: ExecuteDocument loop: name: 'myForLoop' for: start: 1 end: 2 updateBy: 1 inputs: document: "Sample-{{myForLoop.value}}.yaml" phases: test parameters: - name: parameter-1 value: value-1 - name: parameter-2 value: value-2 ``` **Output** AWS TOE 會在每次執行`detailedoutput.json`時建立名為 的輸出檔案。檔案包含執行時叫用之每個元件文件的每個階段和步驟的詳細資訊。對於 **ExecuteDocument** 動作模組，您可以在 欄位中找到簡短的執行時間摘要`outputs`，以及其在 中執行之階段、步驟和文件的詳細資訊`detailedOutput`。 ``` { \"executedStepCount\":1,\"executionId\":\"97054e22-06cc-11ec-9b14-acde48001122\",\"failedStepCount\":0,\"failureMessage\":\"\",\"ignoredFailedStepCount\":0,\"logUrl\":\"\",\"status\":\"success\" }", ``` 每個元件文件的輸出摘要物件都包含下列詳細資訊，如下所示，其中包含範例值： + executedStepCount"：1 + "executionId"："12345a67-89bc-01de-2f34-abcd56789012" + "failedStepCount"：0 + "failureMessage"："" + "ignoredFailedStepCount"：0 + "logUrl"："" + "狀態"："成功" **輸出範例** 下列範例顯示巢狀執行發生時，**ExecuteDocument** 動作模組的輸出。在此範例中，`main.yaml`元件文件成功執行`Sample-1.yaml`元件文件。 ``` { "executionId": "12345a67-89bc-01de-2f34-abcd56789012", "status": "success", "startTime": "2021-08-26T17:20:31-07:00", "endTime": "2021-08-26T17:20:31-07:00", "failureMessage": "", "documents": [ { "name": "", "filePath": "main.yaml", "status": "success", "description": "", "startTime": "2021-08-26T17:20:31-07:00", "endTime": "2021-08-26T17:20:31-07:00", "failureMessage": "", "phases": [ { "name": "build", "status": "success", "startTime": "2021-08-26T17:20:31-07:00", "endTime": "2021-08-26T17:20:31-07:00", "failureMessage": "", "steps": [ { "name": "ExecuteNestedDocument", "status": "success", "failureMessage": "", "timeoutSeconds": -1, "onFailure": "Abort", "maxAttempts": 1, "action": "ExecuteDocument", "startTime": "2021-08-26T17:20:31-07:00", "endTime": "2021-08-26T17:20:31-07:00", "inputs": "[{\"document\":\"Sample-1.yaml\",\"document-s3-bucket-owner\":\"\",\"phases\":\"\",\"parameters\":null}]", "outputs": "[{\"executedStepCount\":1,\"executionId\":\"98765f43-21ed-09cb-8a76-fedc54321098\",\"failedStepCount\":0,\"failureMessage\":\"\",\"ignoredFailedStepCount\":0,\"logUrl\":\"\",\"status\":\"success\"}]", "loop": null, "detailedOutput": [ { "executionId": "98765f43-21ed-09cb-8a76-fedc54321098", "status": "success", "startTime": "2021-08-26T17:20:31-07:00", "endTime": "2021-08-26T17:20:31-07:00", "failureMessage": "", "documents": [ { "name": "", "filePath": "Sample-1.yaml", "status": "success", "description": "", "startTime": "2021-08-26T17:20:31-07:00", "endTime": "2021-08-26T17:20:31-07:00", "failureMessage": "", "phases": [ { "name": "build", "status": "success", "startTime": "2021-08-26T17:20:31-07:00", "endTime": "2021-08-26T17:20:31-07:00", "failureMessage": "", "steps": [ { "name": "ExecuteBashStep", "status": "success", "failureMessage": "", "timeoutSeconds": 7200, "onFailure": "Abort", "maxAttempts": 1, "action": "ExecuteBash", "startTime": "2021-08-26T17:20:31-07:00", "endTime": "2021-08-26T17:20:31-07:00", "inputs": "[{\"commands\":[\"echo \\\"Hello World!\\\"\"]}]", "outputs": "[{\"stdout\":\"Hello World!\"}]", "loop": null, "detailedOutput": null }] }] }] }] }] }] }] } ``` ### ExecutePowerShell (Windows) **ExecutePowerShell** 動作模組可讓您使用內嵌 shell 程式碼/命令執行 PowerShell 指令碼。此模組支援 Windows 平台和 Windows PowerShell。 命令區塊中指定的所有命令/指示都會轉換為指令碼檔案 （例如 `input.ps1`)，並使用 Windows PowerShell 執行。執行 shell 檔案的結果是結束程式碼。 如果 shell 命令以 的結束代碼結束，則 **ExecutePowerShell** 模組會處理系統重新啟動`3010`。啟動時，應用程式會執行下列其中一個動作： + 如果由 Systems Manager Agent 執行，則將結束碼交給發起人。Systems Manager 代理程式會處理系統重新啟動，並執行啟動重新啟動的相同步驟，如[從指令碼重新啟動受管執行個體](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html)中所述。 + 儲存目前的 `executionstate`、設定重新啟動觸發以重新執行應用程式，以及重新啟動系統。 系統重新啟動後，應用程式會執行與啟動重新啟動相同的步驟。如果您需要此功能，則必須撰寫等冪指令碼，以處理相同 shell 命令的多個調用。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | | --- | --- | --- | --- | | commands | 包含根據 PowerShell 語法執行的指示或命令清單。允許多行 YAML。 | 字串清單 | 是。必須指定 `commands`或 `file`，而非兩者。 | | file | 包含 PowerShell 指令碼檔案的路徑。PowerShell 將使用-file命令列引數對此檔案執行。路徑必須指向.ps1檔案。 | String | 是。必須指定 `commands`或 `file`，而非兩者。 | **輸入範例：重新啟動之前和之後** ``` name: ExitCode3010Example description: This shows how the exit code can be used to restart a system with ExecutePowerShell schemaVersion: 1.0 phases: - name: build steps: - name: RestartTrigger action: ExecutePowerShell inputs: commands: - | $rebootIndicator = Join-Path -Path $env:SystemDrive -ChildPath 'reboot-indicator' if (Test-Path -Path $rebootIndicator) { Write-Host 'The reboot file exists. Deleting it and exiting with success.' Remove-Item -Path $rebootIndicator -Force | Out-Null [System.Environment]::Exit(0) } Write-Host 'The reboot file does not exist. Creating it and triggering a restart.' New-Item -Path $rebootIndicator -ItemType File | Out-Null [System.Environment]::Exit(3010) ``` **Output** | 欄位 | 說明 | Type | | --- | --- | --- | | stdout | 命令執行的標準輸出。 | string | 如果您執行重新啟動並傳回結束程式碼`3010`做為動作模組的一部分，則組建將在啟動重新啟動的相同動作模組步驟繼續。如果您在沒有結束碼的情況下執行重新啟動，建置程序可能會失敗。 **輸出範例：重新啟動之前 （第一次通過文件）** ``` { “stdout”: “The reboot file does not exist. Creating it and triggering a restart." } ``` **輸出範例：重新啟動後， （文件的第二次）** ``` { “stdout”: “The reboot file exists. Deleting it and exiting with success." } ``` ## 檔案下載和上傳模組 下一節包含上傳或下載檔案的動作模組詳細資訊。 **Topics** + [S3Download (Linux、Windows、macOS)](#action-modules-s3download) + [S3Upload (Linux、Windows、macOS)](#action-modules-s3upload) + [WebDownload (Linux、Windows、macOS)](#action-modules-webdownload) ### S3Download (Linux、Windows、macOS) 使用 `S3Download`動作模組，您可以將 Amazon S3 物件或一組物件下載到您使用 `destination` 路徑指定的本機檔案或資料夾。如果指定位置已存在任何檔案，且 `overwrite`旗標設為 true，則 會`S3Download`覆寫檔案。 您的`source`位置可以指向 Amazon S3 中的特定物件，或者您可以使用帶有星號萬用字元 (`*`) 的金鑰字首來下載一組符合金鑰字首路徑的物件。當您在`source`位置中指定金鑰字首時，`S3Download`動作模組會下載符合字首的所有項目 （包含檔案和資料夾）。請確定金鑰字首結尾是正斜線，後面接著星號 (`/*`)，以便您下載符合字首的所有項目。例如：`s3://my-bucket/my-folder/*`。 如果在下載期間指定金鑰字首`S3Download`的動作失敗，則在失敗之前，資料夾內容不會復原至其狀態。目的地資料夾會維持在失敗時的原狀。 **支援的使用案例** `S3Download` 動作模組支援下列使用案例： + Amazon S3 物件會下載至本機資料夾，如下載路徑中所指定。 + Amazon S3 物件 （在 Amazon S3 檔案路徑中具有金鑰字首） 會下載至指定的本機資料夾，以遞迴方式將符合金鑰字首的所有 Amazon S3 物件複製到本機資料夾。 **IAM 要求** 您與您的執行個體描述檔建立關聯的 IAM 角色必須具有執行 `S3Download`動作模組的許可。下列 IAM 政策必須連接到與執行個體描述檔相關聯的 IAM 角色： + **單一檔案**：`s3:GetObject`針對儲存貯體/物件 （例如，`arn:aws:s3:::BucketName/*`)。 + **多個檔案**：`s3:ListBucket`針對儲存貯體/物件 （例如 `arn:aws:s3:::BucketName`) 和`s3:GetObject`針對儲存貯體/物件 （例如 `arn:aws:s3:::BucketName/*`)。 **Input** | 金錀 | 說明 | Type | 必要 | 預設 | | --- | --- | --- | --- | --- | | `source` | 下載來源的 Amazon S3 儲存貯體。您可以指定特定物件的路徑，或使用以正斜線結尾的金鑰字首，後面接著星號萬用字元 (`/*`)，以下載一組符合金鑰字首的物件。 | String | 是 | N/A | | `destination` | 下載 Amazon S3 物件的本機路徑。若要下載單一檔案，您必須指定檔案名稱做為路徑的一部分。例如 `/myfolder/package.zip`。 | String | 是 | N/A | | `expectedBucketOwner` | `source` 路徑中提供的儲存貯體的預期擁有者帳戶 ID。我們建議您驗證來源中指定之 Amazon S3 儲存貯體的擁有權。 | String | 否 | N/A | | `overwrite` | 設為 true 時，如果指定本機路徑的目的地資料夾中已存在同名的檔案，則下載檔案會覆寫本機檔案。設定為 false 時，本機系統上現有的檔案會受到保護，不會遭到覆寫，而且動作模組會失敗並出現下載錯誤。 例如 `Error: S3Download: File already exists and "overwrite" property for "destination" file is set to false. Cannot download.` | Boolean | 否 | true | **注意** 對於下列範例，Windows 資料夾路徑可以替換為 Linux 路徑。例如， `C:\myfolder\package.zip` 可以取代為 `/myfolder/package.zip`。 **輸入範例：將 Amazon S3 物件複製到本機檔案** 下列範例示範如何將 Amazon S3 物件複製到本機檔案。 ``` - name: DownloadMyFile action: S3Download inputs: - source: s3://amzn-s3-demo-source-bucket/path/to/package.zip destination: C:\myfolder\package.zip expectedBucketOwner: 123456789022 overwrite: false - source: s3://amzn-s3-demo-source-bucket/path/to/package.zip destination: C:\myfolder\package.zip expectedBucketOwner: 123456789022 overwrite: true - source: s3://amzn-s3-demo-source-bucket/path/to/package.zip destination: C:\myfolder\package.zip expectedBucketOwner: 123456789022 ``` **輸入範例：將 Amazon S3 儲存貯體中具有金鑰字首的所有 Amazon S3 物件複製到本機資料夾** 下列範例示範如何將 Amazon S3 儲存貯體中具有金鑰字首的所有 Amazon S3 物件複製到本機資料夾。Amazon S3 沒有資料夾的概念，因此會複製符合金鑰字首的所有物件。可下載的物件數量上限為 1000。 ``` - name: MyS3DownloadKeyprefix action: S3Download maxAttempts: 3 inputs: - source: s3://amzn-s3-demo-source-bucket/path/to/* destination: C:\myfolder\ expectedBucketOwner: 123456789022 overwrite: false - source: s3://amzn-s3-demo-source-bucket/path/to/* destination: C:\myfolder\ expectedBucketOwner: 123456789022 overwrite: true - source: s3://amzn-s3-demo-source-bucket/path/to/* destination: C:\myfolder\ expectedBucketOwner: 123456789022 ``` **Output** 無。 ### S3Upload (Linux、Windows、macOS) 使用 **S3Upload** 動作模組，您可以將檔案從來源檔案或資料夾上傳至 Amazon S3 位置。您可以在為來源位置指定的路徑中使用萬用字元 (`*`)，上傳路徑符合萬用字元模式的所有檔案。 如果遞迴 **S3Upload** 動作失敗，任何已上傳的檔案都會保留在目的地 Amazon S3 儲存貯體中。 **支援的使用案例** + Amazon S3 物件的本機檔案。 + 資料夾中的本機檔案 （使用萬用字元） 到 Amazon S3 金鑰字首。 + 將本機資料夾 （必須`recurse`設定為 `true`) 複製到 Amazon S3 金鑰字首。 **IAM 要求** 您與您的執行個體描述檔建立關聯的 IAM 角色必須具有執行`S3Upload`動作模組的許可。下列 IAM 政策必須連接到與執行個體描述檔相關聯的 IAM 角色。政策必須授予目標 Amazon S3 儲存貯體的`s3:PutObject`許可。例如，`arn:aws:s3:::BucketName/*`)。 **Input** | 金錀 | 說明 | Type | 必要 | 預設 | | --- | --- | --- | --- | --- | | `source` | 來源檔案/資料夾來源的本機路徑。`source` 支援星號萬用字元 (`*`)。 | String | 是 | N/A | | `destination` | 上傳來源檔案/資料夾的目的地 Amazon S3 儲存貯體路徑。 | String | 是 | N/A | | `recurse` | 設定為 時`true`， 會遞迴執行 **S3Upload**。 | String | 否 | `false` | | `expectedBucketOwner` | 目的地路徑中指定之 Amazon S3 儲存貯體的預期擁有者帳戶 ID。我們建議您驗證目的地中指定的 Amazon S3 儲存貯體擁有權。 | String | 否 | N/A | **輸入範例：將本機檔案複製到 Amazon S3 物件** 下列範例示範如何將本機檔案複製到 Amazon S3 物件。 ``` - name: MyS3UploadFile action: S3Upload onFailure: Abort maxAttempts: 3 inputs: - source: C:\myfolder\package.zip destination: s3://amzn-s3-demo-destination-bucket/path/to/package.zip expectedBucketOwner: 123456789022 ``` **輸入範例：將本機資料夾中的所有檔案複製到具有金鑰字首的 Amazon S3 儲存貯體** 下列範例顯示如何將本機資料夾中的所有檔案複製到具有金鑰字首的 Amazon S3 儲存貯體。此範例不會複製子資料夾或其內容，因為 `recurse` 未指定，且預設為 `false`。 ``` - name: MyS3UploadMultipleFiles action: S3Upload onFailure: Abort maxAttempts: 3 inputs: - source: C:\myfolder\* destination: s3://amzn-s3-demo-destination-bucket/path/to/ expectedBucketOwner: 123456789022 ``` **輸入範例：將所有檔案和資料夾從本機資料夾遞迴複製到 Amazon S3 儲存貯體** 下列範例顯示如何以遞迴方式將所有檔案和資料夾從本機資料夾複製到具有金鑰字首的 Amazon S3 儲存貯體。 ``` - name: MyS3UploadFolder action: S3Upload onFailure: Abort maxAttempts: 3 inputs: - source: C:\myfolder\* destination: s3://amzn-s3-demo-destination-bucket/path/to/ recurse: true expectedBucketOwner: 123456789022 ``` **Output** 無。 ### WebDownload (Linux、Windows、macOS) **WebDownload** 動作模組可讓您透過 HTTP/HTTPS 通訊協定從遠端位置下載檔案和資源 (*建議使用 HTTPS*)。下載的數量或大小沒有限制。此模組會處理重試和指數退避邏輯。 根據使用者輸入，每個下載操作最多分配 5 次嘗試成功。這些嘗試與文件 `maxAttempts`欄位中指定的嘗試不同`steps`，這些嘗試與動作模組失敗相關。 此動作模組隱含地處理重新導向。除了 之外，所有 HTTP 狀態碼`200`都會導致錯誤。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設 | | --- | --- | --- | --- | --- | | source | 有效的 HTTP/HTTPS URL (建議使用 HTTPS)，其遵循 RFC 3986 標準。允許鏈結表達式。 | String | 是 | N/A | | destination | 本機系統上的絕對或相對檔案或資料夾路徑。資料夾路徑必須以 結尾/。如果它們不是以 結尾/，則會被視為檔案路徑。模組會建立成功下載所需的任何檔案或資料夾。允許鏈結表達式。 | String | 是 | N/A | | overwrite | 啟用時， 會使用下載的檔案或資源覆寫本機系統上的任何現有檔案。未啟用時，不會覆寫本機系統上的任何現有檔案，且動作模組會失敗並顯示錯誤。啟用覆寫並指定檢查總和和和演算法時，只有在檢查總和和和任何預先存在檔案的雜湊不相符時，動作模組才會下載檔案。 | Boolean | 否 | true | | checksum | 當您指定檢查總和時，會針對使用提供的演算法產生的下載檔案雜湊進行檢查。若要啟用檔案驗證，必須提供檢查總和和和演算法。允許鏈結表達式。 | String | 否 | N/A | | algorithm | 用來計算檢查總和的演算法。選項包括 MD5, SHA1, SHA256和 SHA512。若要啟用檔案驗證，必須提供檢查總和和和演算法。允許鏈結表達式。 | String | 否 | N/A | | ignoreCertificateErrors | 啟用時，會忽略 SSL 憑證驗證。 | Boolean | 否 | false | **Output** | 金鑰名稱 | 說明 | Type | | --- | --- | --- | | destination | 以字元分隔的新行字串，指定存放下載檔案或資源的目的地路徑。 | String | **輸入範例：將遠端檔案下載至本機目的地** ``` - name: DownloadRemoteFile action: WebDownload maxAttempts: 3 inputs: - source: https://testdomain/path/to/java14.zip destination: C:\testfolder\package.zip ``` **輸出：** ``` { "destination": "C:\\testfolder\\package.zip" } ``` **輸入範例：將多個遠端檔案下載到多個本機目的地 ** ``` - name: DownloadRemoteFiles action: WebDownload maxAttempts: 3 inputs: - source: https://testdomain/path/to/java14.zip destination: /tmp/java14_renamed.zip - source: https://testdomain/path/to/java14.zip destination: /tmp/create_new_folder_and_add_java14_as_zip/ ``` **輸出：** ``` { "destination": "/tmp/create_new_folder/java14_renamed.zip\n/tmp/create_new_folder_and_add_java14_as_zip/java14.zip" } ``` **輸入範例：下載一個遠端檔案而不覆寫本機目的地，並使用檔案驗證下載另一個遠端檔案** ``` - name: DownloadRemoteMultipleProperties action: WebDownload maxAttempts: 3 inputs: - source: https://testdomain/path/to/java14.zip destination: C:\create_new_folder\java14_renamed.zip overwrite: false - source: https://testdomain/path/to/java14.zip destination: C:\create_new_folder_and_add_java14_as_zip\ checksum: ac68bbf921d953d1cfab916cb6120864 algorithm: MD5 overwrite: true ``` **輸出：** ``` { "destination": "C:\\create_new_folder\\java14_renamed.zip\nC:\\create_new_folder_and_add_java14_as_zip\\java14.zip" } ``` **輸入範例：下載遠端檔案並忽略 SSL 憑證驗證** ``` - name: DownloadRemoteIgnoreValidation action: WebDownload maxAttempts: 3 inputs: - source: https://www.bad-ssl.com/resource destination: /tmp/downloads/ ignoreCertificateErrors: true ``` **輸出：** ``` { "destination": "/tmp/downloads/resource" } ``` ## 檔案系統操作模組 下一節包含執行檔案系統操作之動作模組的詳細資訊。 **Topics** + [AppendFile (Linux、Windows、macOS)](#action-modules-appendfile) + [CopyFile (Linux、Windows、macOS)](#action-modules-copyfile) + [CopyFolder (Linux、Windows、macOS)](#action-modules-copyfolder) + [CreateFile (Linux、Windows、macOS)](#action-modules-createfile) + [CreateFolder (Linux、Windows、macOS)](#action-modules-createfolder) + [CreateSymlink (Linux、Windows、macOS)](#action-modules-createsymlink) + [DeleteFile (Linux、Windows、macOS)](#action-modules-deletefile) + [DeleteFolder (Linux、Windows、macOS)](#action-modules-deletefolder) + [ListFiles (Linux、Windows、macOS)](#action-modules-listfiles) + [MoveFile (Linux、Windows、macOS)](#action-modules-movefile) + [MoveFolder (Linux、Windows、macOS)](#action-modules-movefolder) + [ReadFile (Linux、Windows、macOS)](#action-modules-readfile) + [SetFileEncoding (Linux、Windows、macOS)](#action-modules-setfileencoding) + [SetFileOwner (Linux、Windows、macOS)](#action-modules-setfileowner) + [SetFolderOwner (Linux、Windows、macOS)](#action-modules-setfolderowner) + [SetFilePermissions (Linux、Windows、macOS)](#action-modules-setfilepermissions) + [SetFolderPermissions (Linux、Windows、macOS)](#action-modules-setfolderpermissions) ### AppendFile (Linux、Windows、macOS) **AppendFile** 動作模組會將指定的內容新增至檔案的預先存在內容。 如果檔案編碼值與預設編碼 (`utf-8`) 值不同，您可以使用 `encoding`選項指定檔案編碼值。根據預設， `utf-16`和 `utf-32` 會假設使用小端點編碼。 發生下列情況時，動作模組會傳回錯誤： + 指定的檔案在執行時間不存在。 + 您沒有修改檔案內容的寫入許可。 + 模組在檔案操作期間遇到錯誤。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設值 | 可接受值 | 在所有平台上支援 | | --- | --- | --- | --- | --- | --- | --- | | path | 檔案路徑。 | String | 是 | N/A | N/A | 是 | | content | 要附加至 檔案的內容。 | String | 否 | 空字串 | N/A | 是 | | encoding | 編碼標準。 | String | 否 | utf8 | utf8、utf-8、utf16、utf-16、utf16-LEutf-16-LEutf16-BE、、utf-16-BE、utf32、utf-32、utf32-LEutf-32-LE、 utf32-BE和 utf-32-BE。編碼選項的值不區分大小寫。 | 是 | **輸入範例：附加不含編碼的檔案 (Linux)** ``` - name: AppendingFileWithOutEncodingLinux action: AppendFile inputs: - path: ./Sample.txt content: "The string to be appended to the file" ``` **輸入範例：附加不含編碼的檔案 (Windows)** ``` - name: AppendingFileWithOutEncodingWindows action: AppendFile inputs: - path: C:\MyFolder\MyFile.txt content: "The string to be appended to the file" ``` **輸入範例：使用編碼附加檔案 (Linux)** ``` - name: AppendingFileWithEncodingLinux action: AppendFile inputs: - path: /FolderName/SampleFile.txt content: "The string to be appended to the file" encoding: UTF-32 ``` **輸入範例：使用編碼附加檔案 (Windows)** ``` - name: AppendingFileWithEncodingWindows action: AppendFile inputs: - path: C:\MyFolderName\SampleFile.txt content: "The string to be appended to the file" encoding: UTF-32 ``` **輸入範例：附加具有空字串的檔案 (Linux)** ``` - name: AppendingEmptyStringLinux action: AppendFile inputs: - path: /FolderName/SampleFile.txt ``` **輸入範例：附加具有空字串的檔案 (Windows)** ``` - name: AppendingEmptyStringWindows action: AppendFile inputs: - path: C:\MyFolderName\SampleFile.txt ``` **Output** 無。 ### CopyFile (Linux、Windows、macOS) **CopyFile** 動作模組會將檔案從指定的來源複製到指定的目的地。根據預設，如果在執行時間不存在，模組會遞迴建立目的地資料夾。 如果指定名稱的檔案已存在於指定的資料夾中，動作模組預設會覆寫現有的檔案。您可以將覆寫選項設定為 來覆寫此預設行為`false`。當覆寫選項設定為 `false`，且指定位置中已有具有指定名稱的檔案時，動作模組會傳回錯誤。此選項的運作方式與 Linux 中的 `cp`命令相同，預設會覆寫該命令。 來源檔案名稱可以包含萬用字元 (`*`)。只有在最後一個檔案路徑分隔符號 (`/` 或 `\`) 之後，才會接受萬用字元。如果來源檔案名稱中包含萬用字元，則符合萬用字元的所有檔案都會複製到目的地資料夾。如果您想要使用萬用字元移動多個檔案， `destination`選項的輸入必須以檔案路徑分隔符號 (`/` 或 `\`) 結尾，這表示目的地輸入是資料夾。 如果目的地檔案名稱與來源檔案名稱不同，您可以使用 `destination`選項指定目的地檔案名稱。如果您未指定目的地檔案名稱，則會使用來源檔案名稱來建立目的地檔案。遵循最後一個檔案路徑分隔符號 (`/` 或 `\`) 的任何文字都會視為檔案名稱。如果您想要使用與來源檔案相同的檔案名稱，則 `destination`選項的輸入必須以檔案路徑分隔符號 (`/` 或 ) 結尾`\`。 發生下列情況時，動作模組會傳回錯誤： + 您沒有在指定資料夾中建立檔案的許可。 + 來源檔案在執行時間不存在。 + 已有具有指定檔案名稱的資料夾，且 `overwrite`選項設定為 `false`。 + 動作模組在執行操作時遇到錯誤。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設值 | 可接受值 | 在所有平台上支援 | | --- | --- | --- | --- | --- | --- | --- | | source | 來源檔案路徑。 | String | 是 | N/A | N/A | 是 | | destination | 目的地檔案路徑。 | String | 是 | N/A | N/A | 是 | | overwrite | 設定為 false 時，如果指定位置中已有具有指定名稱的檔案，則不會取代目的地檔案。 | Boolean | 否 | true | N/A | 是 | **輸入範例：複製檔案 (Linux)** ``` - name: CopyingAFileLinux action: CopyFile inputs: - source: /Sample/MyFolder/Sample.txt destination: /MyFolder/destinationFile.txt ``` **輸入範例：複製檔案 (Windows)** ``` - name: CopyingAFileWindows action: CopyFile inputs: - source: C:\MyFolder\Sample.txt destination: C:\MyFolder\destinationFile.txt ``` **輸入範例：使用來源檔案名稱 (Linux) 複製檔案** ``` - name: CopyingFileWithSourceFileNameLinux action: CopyFile inputs: - source: /Sample/MyFolder/Sample.txt destination: /MyFolder/ ``` **輸入範例：使用來源檔案名稱 (Windows) 複製檔案** ``` - name: CopyingFileWithSourceFileNameWindows action: CopyFile inputs: - source: C:\Sample\MyFolder\Sample.txt destination: C:\MyFolder\ ``` **輸入範例：使用萬用字元 (Linux) 複製檔案** ``` - name: CopyingFilesWithWildCardLinux action: CopyFile inputs: - source: /Sample/MyFolder/Sample* destination: /MyFolder/ ``` **輸入範例：使用萬用字元複製檔案 (Windows)** ``` - name: CopyingFilesWithWildCardWindows action: CopyFile inputs: - source: C:\Sample\MyFolder\Sample* destination: C:\MyFolder\ ``` **輸入範例：複製檔案而不覆寫 (Linux)** ``` - name: CopyingFilesWithoutOverwriteLinux action: CopyFile inputs: - source: /Sample/MyFolder/Sample.txt destination: /MyFolder/destinationFile.txt overwrite: false ``` **輸入範例：複製檔案而不覆寫 (Windows)** ``` - name: CopyingFilesWithoutOverwriteWindows action: CopyFile inputs: - source: C:\Sample\MyFolder\Sample.txt destination: C:\MyFolder\destinationFile.txt overwrite: false ``` **Output** 無。 ### CopyFolder (Linux、Windows、macOS) **CopyFolder** 動作模組會將資料夾從指定的來源複製到指定的目的地。`source` 選項的輸入是要複製的資料夾，`destination`而選項的輸入是複製來源資料夾內容的資料夾。根據預設，如果在執行時間不存在，模組會遞迴建立目的地資料夾。 如果指定名稱的資料夾已存在於指定的資料夾中，則動作模組預設會覆寫現有的資料夾。您可以將覆寫選項設定為 來覆寫此預設行為`false`。當覆寫選項設定為 `false`，且指定位置中已有具有指定名稱的資料夾時，動作模組將傳回錯誤。 來源資料夾名稱可以包含萬用字元 (`*`)。只有在最後一個檔案路徑分隔符號 (`/` 或 `\`) 之後，才會接受萬用字元。如果來源資料夾名稱中包含萬用字元，則符合萬用字元的所有資料夾都會複製到目的地資料夾。如果您想要使用萬用字元複製多個資料夾， `destination`選項的輸入必須以檔案路徑分隔符號 (`/` 或 `\`) 結尾，這表示目的地輸入是資料夾。 如果目的地資料夾名稱與來源資料夾名稱不同，您可以使用 `destination`選項指定目的地資料夾名稱。如果您未指定目的地資料夾名稱，則會使用來源資料夾的名稱來建立目的地資料夾。最後一個檔案路徑分隔符號 (`/` 或 `\`) 之後的任何文字都會視為資料夾名稱。如果您想要使用與來源資料夾相同的資料夾名稱，則 `destination`選項的輸入必須以檔案路徑分隔符號 (`/` 或 ) 結尾`\`。 發生下列情況時，動作模組會傳回錯誤： + 您沒有在指定資料夾中建立資料夾的許可。 + 來源資料夾在執行時間不存在。 + 已有具有指定資料夾名稱的資料夾，且 `overwrite`選項設定為 `false`。 + 動作模組在執行操作時遇到錯誤。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設值 | 可接受值 | 在所有平台上支援 | | --- | --- | --- | --- | --- | --- | --- | | source | 來源資料夾路徑。 | String | 是 | N/A | N/A | 是 | | destination | 目的地資料夾路徑。 | String | 是 | N/A | N/A | 是 | | overwrite | 設定為 false 時，如果指定位置中已有具有指定名稱的資料夾，則不會取代目的地資料夾。 | Boolean | 否 | true | N/A | 是 | **輸入範例：複製資料夾 (Linux)** ``` - name: CopyingAFolderLinux action: CopyFolder inputs: - source: /Sample/MyFolder/SampleFolder destination: /MyFolder/destinationFolder ``` **輸入範例：複製資料夾 (Windows)** ``` - name: CopyingAFolderWindows action: CopyFolder inputs: - source: C:\Sample\MyFolder\SampleFolder destination: C:\MyFolder\destinationFolder ``` **輸入範例：使用來源資料夾名稱 (Linux) 複製資料夾** ``` - name: CopyingFolderSourceFolderNameLinux action: CopyFolder inputs: - source: /Sample/MyFolder/SourceFolder destination: /MyFolder/ ``` **輸入範例：使用來源資料夾名稱 (Windows) 複製資料夾** ``` - name: CopyingFolderSourceFolderNameWindows action: CopyFolder inputs: - source: C:\Sample\MyFolder\SampleFolder destination: C:\MyFolder\ ``` **輸入範例：使用萬用字元 (Linux) 複製資料夾** ``` - name: CopyingFoldersWithWildCardLinux action: CopyFolder inputs: - source: /Sample/MyFolder/Sample* destination: /MyFolder/ ``` **輸入範例：使用萬用字元複製資料夾 (Windows)** ``` - name: CopyingFoldersWithWildCardWindows action: CopyFolder inputs: - source: C:\Sample\MyFolder\Sample* destination: C:\MyFolder\ ``` **輸入範例：複製資料夾而不覆寫 (Linux)** ``` - name: CopyingFoldersWithoutOverwriteLinux action: CopyFolder inputs: - source: /Sample/MyFolder/SourceFolder destination: /MyFolder/destinationFolder overwrite: false ``` **輸入範例：複製資料夾而不覆寫 (Windows)** ``` - name: CopyingFoldersWithoutOverwrite action: CopyFolder inputs: - source: C:\Sample\MyFolder\SourceFolder destination: C:\MyFolder\destinationFolder overwrite: false ``` **Output** 無。 ### CreateFile (Linux、Windows、macOS) **CreateFile** 動作模組會在指定的位置建立檔案。根據預設，如果需要，模組也會以遞迴方式建立父資料夾。 如果檔案已存在於指定的資料夾中，動作模組預設會截斷或覆寫現有的檔案。您可以將覆寫選項設定為 來覆寫此預設行為`false`。當覆寫選項設定為 `false`，且指定位置中已有具有指定名稱的檔案時，動作模組會傳回錯誤。 如果檔案編碼值與預設編碼 (`utf-8`) 值不同，您可以使用 `encoding`選項指定檔案編碼值。根據預設， `utf-16`和 `utf-32` 會假設使用小端點編碼。 `owner`、 `group`和 `permissions`是選用的輸入。的輸入`permissions`必須是字串值。若未提供，則會使用預設值建立檔案。Windows 平台不支援這些選項。如果 Windows 平台上使用 `owner`、 和 `permissions`選項`group`，此動作模組會驗證並傳回錯誤。 此動作模組可以建立具有作業系統`umask`預設值所定義許可的檔案 。如果您想要覆寫預設值，則必須設定 `umask` 值。 發生下列情況時，動作模組會傳回錯誤： + 您沒有在指定的父資料夾中建立檔案或資料夾的許可。 + 動作模組在執行操作時遇到錯誤。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設值 | 可接受值 | 在所有平台上支援 | | --- | --- | --- | --- | --- | --- | --- | | path | 檔案路徑。 | String | 是 | N/A | N/A | 是 | | content | 檔案的文字內容。 | String | 否 | N/A | N/A | 是 | | encoding | 編碼標準。 | String | 否 | utf8 | utf8、utf-8、utf16、utf-16、utf16-LEutf-16-LEutf16-BE、、utf-16-BE、utf32、utf-32、utf32-LEutf-32-LE、 utf32-BE和 utf-32-BE。編碼選項的值不區分大小寫。 | 是 | | owner | 使用者名稱或 ID。 | String | 否 | N/A | N/A | Windows 不支援。 | | group | 群組名稱或 ID。 | String | 否 | 目前的使用者。 | N/A | Windows 不支援。 | | permissions | 檔案許可。 | String | 否 | 0666 | N/A | Windows 不支援。 | | overwrite | 如果指定的檔案名稱已存在，請將此值設定為false防止預設截斷或覆寫檔案。 | Boolean | 否 | true | N/A | 是 | **輸入範例：建立檔案而不覆寫 (Linux)** ``` - name: CreatingFileWithoutOverwriteLinux action: CreateFile inputs: - path: /home/UserName/Sample.txt content: The text content of the sample file. overwrite: false ``` **輸入範例：建立檔案而不覆寫 (Windows)** ``` - name: CreatingFileWithoutOverwriteWindows action: CreateFile inputs: - path: C:\Temp\Sample.txt content: The text content of the sample file. overwrite: false ``` **輸入範例：建立具有檔案屬性的檔案** ``` - name: CreatingFileWithFileProperties action: CreateFile inputs: - path: SampleFolder/Sample.txt content: The text content of the sample file. encoding: UTF-16 owner: Ubuntu group: UbuntuGroup permissions: 0777 - path: SampleFolder/SampleFile.txt permissions: 755 - path: SampleFolder/TextFile.txt encoding: UTF-16 owner: root group: rootUserGroup ``` **輸入範例：建立不含檔案屬性的檔案** ``` - name: CreatingFileWithoutFileProperties action: CreateFile inputs: - path: ./Sample.txt - path: Sample1.txt ``` **輸入範例：建立空白檔案以略過 Linux 清除指令碼中的區段** ``` - name: CreateSkipCleanupfile action: CreateFile inputs: - path: ``` 如需詳細資訊，請參閱[覆寫 Linux 清除指令碼](security-best-practices.md#override-linux-cleanup-script) **Output** 無。 ### CreateFolder (Linux、Windows、macOS) **CreateFolder** 動作模組會在指定位置建立資料夾。根據預設，如果需要，模組也會以遞迴方式建立父資料夾。 如果資料夾已存在於指定的資料夾中，動作模組預設會截斷或覆寫現有的資料夾。您可以將覆寫選項設定為 來覆寫此預設行為`false`。當覆寫選項設定為 `false`，且指定位置中已有具有指定名稱的資料夾時，動作模組將傳回錯誤。 `owner`、 `group`和 `permissions`是選用的輸入。的輸入`permissions`必須是字串值。Windows 平台不支援這些選項。如果 Windows 平台上使用 `owner`、 和 `permissions`選項`group`，此動作模組會驗證並傳回錯誤。 此動作模組可以建立具有作業系統`umask`預設值所定義許可的 資料夾。如果您想要覆寫預設值，則必須設定 `umask` 值。 發生下列情況時，動作模組會傳回錯誤： + 您沒有在指定位置建立資料夾的許可。 + 動作模組在執行操作時遇到錯誤。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設值 | 可接受值 | 在所有平台上支援 | | --- | --- | --- | --- | --- | --- | --- | | path | 資料夾路徑。 | String | 是 | N/A | N/A | 是 | | owner | 使用者名稱或 ID。 | String | 否 | 目前的使用者。 | N/A | Windows 不支援。 | | group | 群組名稱或 ID。 | String | 否 | 目前使用者的群組。 | N/A | Windows 不支援。 | | permissions | 資料夾許可。 | String | 否 | 0777 | N/A | Windows 不支援。 | | overwrite | 如果指定的檔案名稱已存在，請將此值設定為false防止預設截斷或覆寫檔案。 | Boolean | 否 | true | N/A | 是 | **輸入範例：建立資料夾 (Linux)** ``` - name: CreatingFolderLinux action: CreateFolder inputs: - path: /Sample/MyFolder/ ``` **輸入範例：建立資料夾 (Windows)** ``` - name: CreatingFolderWindows action: CreateFolder inputs: - path: C:\MyFolder ``` **輸入範例：建立指定資料夾屬性的資料夾** ``` - name: CreatingFolderWithFolderProperties action: CreateFolder inputs: - path: /Sample/MyFolder/Sample/ owner: SampleOwnerName group: SampleGroupName permissions: 0777 - path: /Sample/MyFolder/SampleFoler/ permissions: 777 ``` **輸入範例：如果有，請建立覆寫現有資料夾的資料夾。** ``` - name: CreatingFolderWithOverwrite action: CreateFolder inputs: - path: /Sample/MyFolder/Sample/ overwrite: true ``` **Output** 無。 ### CreateSymlink (Linux、Windows、macOS) **CreateSymlink** 動作模組會建立符號連結，或包含另一個檔案參考的檔案。Windows 平台不支援此模組。 `path` 和 `target`選項的輸入可以是絕對或相對路徑。如果 `path`選項的輸入是相對路徑，則會在建立連結時將其取代為絕對路徑。 根據預設，當具有指定名稱的連結已存在於指定的資料夾中時，動作模組會傳回錯誤。您可以將 `force`選項設定為 ，以覆寫此預設行為`true`。當 `force`選項設定為 時`true`，模組會覆寫現有的連結。 如果父資料夾不存在，動作模組預設會以遞迴方式建立資料夾。 發生下列情況時，動作模組會傳回錯誤： + 目標檔案在執行時間不存在。 + 具有指定名稱的非符號連結檔案已存在。 + 動作模組在執行操作時遇到錯誤。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設值 | 可接受值 | 在所有平台上支援 | | --- | --- | --- | --- | --- | --- | --- | | path | 檔案路徑。 | String | 是 | N/A | N/A | Windows 不支援。 | | target | 符號連結指向的目標檔案路徑。 | String | 是 | N/A | N/A | Windows 不支援。 | | force | 當具有相同名稱的連結已存在時，強制建立連結。 | Boolean | 否 | false | N/A | Windows 不支援。 | **輸入範例：建立符號連結，強制建立連結** ``` - name: CreatingSymbolicLinkWithForce action: CreateSymlink inputs: - path: /Folder2/Symboliclink.txt target: /Folder/Sample.txt force: true ``` **輸入範例：建立不會強制建立連結的符號連結** ``` - name: CreatingSymbolicLinkWithOutForce action: CreateSymlink inputs: - path: Symboliclink.txt target: /Folder/Sample.txt ``` **Output** 無。 ### DeleteFile (Linux、Windows、macOS) **DeleteFile** 動作模組會刪除指定位置中的檔案。 的輸入`path`應該是有效的檔案路徑，或檔案名稱中包含萬用字元 (`*`) 的檔案路徑。在檔案名稱中指定萬用字元時，將刪除相同資料夾中與萬用字元相符的所有檔案。 發生下列情況時，動作模組會傳回錯誤： + 您沒有執行刪除操作的許可。 + 動作模組在執行操作時遇到錯誤。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設值 | 可接受值 | 在所有平台上支援 | | --- | --- | --- | --- | --- | --- | --- | | path | 檔案路徑。 | String | 是 | N/A | N/A | 是 | **輸入範例：刪除單一檔案 (Linux)** ``` - name: DeletingSingleFileLinux action: DeleteFile inputs: - path: /SampleFolder/MyFolder/Sample.txt ``` **輸入範例：刪除單一檔案 (Windows)** ``` - name: DeletingSingleFileWindows action: DeleteFile inputs: - path: C:\SampleFolder\MyFolder\Sample.txt ``` **輸入範例：刪除結尾為 "log" (Linux) 的檔案** ``` - name: DeletingFileEndingWithLogLinux action: DeleteFile inputs: - path: /SampleFolder/MyFolder/*log ``` **輸入範例：刪除結尾為 "log" (Windows) 的檔案** ``` - name: DeletingFileEndingWithLogWindows action: DeleteFile inputs: - path: C:\SampleFolder\MyFolder\*log ``` **輸入範例：刪除指定資料夾中的所有檔案 (Linux)** ``` - name: DeletingAllFilesInAFolderLinux action: DeleteFile inputs: - path: /SampleFolder/MyFolder/* ``` **輸入範例：刪除指定資料夾中的所有檔案 (Windows)** ``` - name: DeletingAllFilesInAFolderWindows action: DeleteFile inputs: - path: C:\SampleFolder\MyFolder\* ``` **Output** 無。 ### DeleteFolder (Linux、Windows、macOS) **DeleteFolder** 動作模組會刪除資料夾。 如果資料夾不是空的，您必須將 `force`選項設定為 ，`true`以移除資料夾及其內容。如果您未將 `force`選項設定為 `true`，且您嘗試刪除的資料夾不是空的，動作模組會傳回錯誤。`force` 選項的預設值為 `false`。 發生下列情況時，動作模組會傳回錯誤： + 您沒有執行刪除操作的許可。 + 動作模組在執行操作時遇到錯誤。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設值 | 可接受值 | 在所有平台上支援 | | --- | --- | --- | --- | --- | --- | --- | | path | 資料夾路徑。 | String | 是 | N/A | N/A | 是 | | force | 無論資料夾是否為空，都會移除資料夾。 | Boolean | 否 | false | N/A | 是 | **輸入範例：使用 `force`選項 (Linux) 刪除非空白的資料夾** ``` - name: DeletingFolderWithForceOptionLinux action: DeleteFolder inputs: - path: /Sample/MyFolder/Sample/ force: true ``` **輸入範例：使用 `force`選項 (Windows) 刪除非空白的資料夾** ``` - name: DeletingFolderWithForceOptionWindows action: DeleteFolder inputs: - path: C:\Sample\MyFolder\Sample\ force: true ``` **輸入範例：刪除資料夾 (Linux)** ``` - name: DeletingFolderWithOutForceLinux action: DeleteFolder inputs: - path: /Sample/MyFolder/Sample/ ``` **輸入範例：刪除資料夾 (Windows)** ``` - name: DeletingFolderWithOutForce action: DeleteFolder inputs: - path: C:\Sample\MyFolder\Sample\ ``` **Output** 無。 ### ListFiles (Linux、Windows、macOS) **ListFiles** 動作模組會列出指定資料夾中的檔案。當遞迴選項設定為 時`true`，它會列出子資料夾中的檔案。根據預設，此模組不會列出子資料夾中的檔案。 若要列出名稱符合指定模式的所有檔案，請使用 `fileNamePattern`選項來提供模式。`fileNamePattern` 選項接受萬用字元 (`*`) 值。提供 `fileNamePattern` 時，會傳回符合指定檔案名稱格式的所有檔案。 發生下列情況時，動作模組會傳回錯誤： + 指定的資料夾在執行時間不存在。 + 您沒有在指定的父資料夾中建立檔案或資料夾的許可。 + 動作模組在執行操作時遇到錯誤。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設值 | 可接受值 | 在所有平台上支援 | | --- | --- | --- | --- | --- | --- | --- | | path | 資料夾路徑。 | String | 是 | N/A | N/A | 是 | | fileNamePattern | 要比對的模式，以列出名稱符合模式的所有檔案。 | String | 否 | N/A | N/A | 是 | | recursive | 以遞迴方式列出資料夾中的檔案。 | Boolean | 否 | false | N/A | 是 | **輸入範例：列出指定資料夾中的檔案 (Linux)** ``` - name: ListingFilesInSampleFolderLinux action: ListFiles inputs: - path: /Sample/MyFolder/Sample ``` **輸入範例：列出指定資料夾中的檔案 (Windows)** ``` - name: ListingFilesInSampleFolderWindows action: ListFiles inputs: - path: C:\Sample\MyFolder\Sample ``` **輸入範例：列出結尾為 "log" (Linux) 的檔案** ``` - name: ListingFilesWithEndingWithLogLinux action: ListFiles inputs: - path: /Sample/MyFolder/ fileNamePattern: *log ``` **輸入範例：列出結尾為 "log" (Windows) 的檔案** ``` - name: ListingFilesWithEndingWithLogWindows action: ListFiles inputs: - path: C:\Sample\MyFolder\ fileNamePattern: *log ``` **輸入範例：遞迴列出檔案** ``` - name: ListingFilesRecursively action: ListFiles inputs: - path: /Sample/MyFolder/ recursive: true ``` **Output** | 金鑰名稱 | 說明 | Type | | --- | --- | --- | | files | 檔案的清單。 | String | **輸出範例** ``` { "files": "/sample1.txt,/sample2.txt,/sample3.txt" } ``` ### MoveFile (Linux、Windows、macOS) **MoveFile** 動作模組會將檔案從指定的來源移至指定的目的地。 如果檔案已存在於指定的資料夾中，動作模組預設會覆寫現有的檔案。您可以將覆寫選項設定為 來覆寫此預設行為`false`。當覆寫選項設定為 `false`，且指定位置中已有具有指定名稱的檔案時，動作模組會傳回錯誤。此選項的運作方式與 Linux 中的 `mv`命令相同，預設會覆寫該命令。 來源檔案名稱可以包含萬用字元 (`*`)。只有在最後一個檔案路徑分隔符號 (`/` 或 `\`) 之後，才會接受萬用字元。如果來源檔案名稱中包含萬用字元，則符合萬用字元的所有檔案都會複製到目的地資料夾。如果您想要使用萬用字元移動多個檔案， `destination`選項的輸入必須以檔案路徑分隔符號 (`/` 或 `\`) 結尾，這表示目的地輸入是資料夾。 如果目的地檔案名稱與來源檔案名稱不同，您可以使用 `destination`選項指定目的地檔案名稱。如果您未指定目的地檔案名稱，則會使用來源檔案名稱來建立目的地檔案。遵循最後一個檔案路徑分隔符號 (`/` 或 `\`) 的任何文字都會視為檔案名稱。如果您想要使用與來源檔案相同的檔案名稱，則 `destination`選項的輸入必須以檔案路徑分隔符號 (`/` 或 ) 結尾`\`。 發生下列情況時，動作模組會傳回錯誤： + 您沒有在指定資料夾中建立檔案的許可。 + 來源檔案在執行時間不存在。 + 已有具有指定檔案名稱的資料夾，且 `overwrite`選項設定為 `false`。 + 動作模組在執行操作時遇到錯誤。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設值 | 可接受值 | 在所有平台上支援 | | --- | --- | --- | --- | --- | --- | --- | | source | 來源檔案路徑。 | String | 是 | N/A | N/A | 是 | | destination | 目的地檔案路徑。 | String | 是 | N/A | N/A | 是 | | overwrite | 設定為 false 時，如果指定位置中已有具有指定名稱的檔案，則不會取代目的地檔案。 | Boolean | 否 | true | N/A | 是 | **輸入範例：移動檔案 (Linux)** ``` - name: MovingAFileLinux action: MoveFile inputs: - source: /Sample/MyFolder/Sample.txt destination: /MyFolder/destinationFile.txt ``` **輸入範例：移動檔案 (Windows)** ``` - name: MovingAFileWindows action: MoveFile inputs: - source: C:\Sample\MyFolder\Sample.txt destination: C:\MyFolder\destinationFile.txt ``` **輸入範例：使用來源檔案名稱 (Linux) 移動檔案** ``` - name: MovingFileWithSourceFileNameLinux action: MoveFile inputs: - source: /Sample/MyFolder/Sample.txt destination: /MyFolder/ ``` **輸入範例：使用來源檔案名稱 (Windows) 移動檔案** ``` - name: MovingFileWithSourceFileNameWindows action: MoveFile inputs: - source: C:\Sample\MyFolder\Sample.txt destination: C:\MyFolder ``` **輸入範例：使用萬用字元 (Linux) 移動檔案** ``` - name: MovingFilesWithWildCardLinux action: MoveFile inputs: - source: /Sample/MyFolder/Sample* destination: /MyFolder/ ``` **輸入範例：使用萬用字元 (Windows) 移動檔案** ``` - name: MovingFilesWithWildCardWindows action: MoveFile inputs: - source: C:\Sample\MyFolder\Sample* destination: C:\MyFolder ``` **輸入範例：在不覆寫的情況下移動檔案 (Linux)** ``` - name: MovingFilesWithoutOverwriteLinux action: MoveFile inputs: - source: /Sample/MyFolder/Sample.txt destination: /MyFolder/destinationFile.txt overwrite: false ``` **輸入範例：在不覆寫的情況下移動檔案 (Windows)** ``` - name: MovingFilesWithoutOverwrite action: MoveFile inputs: - source: C:\Sample\MyFolder\Sample.txt destination: C:\MyFolder\destinationFile.txt overwrite: false ``` **Output** 無。 ### MoveFolder (Linux、Windows、macOS) **MoveFolder** 動作模組會將資料夾從指定的來源移至指定的目的地。`source` 選項的輸入是要移動的資料夾，`destination`而選項的輸入是來源資料夾內容被移動的資料夾。 如果目的地父資料夾或 `destination`選項的輸入在執行時間不存在，則模組的預設行為是在指定的目的地以遞迴方式建立資料夾。 如果與來源資料夾相同的資料夾已存在於目的地資料夾中，則動作模組預設會覆寫現有的資料夾。您可以將覆寫選項設定為 來覆寫此預設行為`false`。當覆寫選項設定為 `false`，且指定位置中已有具有指定名稱的資料夾時，動作模組將傳回錯誤。 來源資料夾名稱可以包含萬用字元 (`*`)。只有在最後一個檔案路徑分隔符號 (`/` 或 `\`) 之後，才會接受萬用字元。如果來源資料夾名稱中包含萬用字元，則符合萬用字元的所有資料夾都會複製到目的地資料夾。如果您想要使用萬用字元移動多個資料夾， `destination`選項的輸入必須以檔案路徑分隔符號 (`/` 或 `\`) 結尾，這表示目的地輸入是資料夾。 如果目的地資料夾名稱與來源資料夾名稱不同，您可以使用 `destination`選項指定目的地資料夾名稱。如果您未指定目的地資料夾名稱，則會使用來源資料夾的名稱來建立目的地資料夾。最後一個檔案路徑分隔符號 (`/` 或 `\`) 之後的任何文字都會視為資料夾名稱。如果您想要使用與來源資料夾相同的資料夾名稱，則 `destination`選項的輸入必須以檔案路徑分隔符號 (`/` 或 ) 結尾`\`。 發生下列情況時，動作模組會傳回錯誤： + 您沒有在目的地資料夾中建立資料夾的許可。 + 來源資料夾在執行時間不存在。 + 已有具有指定名稱的資料夾，且 `overwrite`選項設定為 `false`。 + 動作模組在執行操作時遇到錯誤。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設值 | 可接受值 | 在所有平台上支援 | | --- | --- | --- | --- | --- | --- | --- | | source | 來源資料夾路徑。 | String | 是 | N/A | N/A | 是 | | destination | 目的地資料夾路徑。 | String | 是 | N/A | N/A | 是 | | overwrite | 設定為 false 時，如果指定位置中已有具有指定名稱的資料夾，則不會取代目的地資料夾。 | Boolean | 否 | true | N/A | 是 | **輸入範例：移動資料夾 (Linux)** ``` - name: MovingAFolderLinux action: MoveFolder inputs: - source: /Sample/MyFolder/SourceFolder destination: /MyFolder/destinationFolder ``` **輸入範例：移動資料夾 (Windows)** ``` - name: MovingAFolderWindows action: MoveFolder inputs: - source: C:\Sample\MyFolder\SourceFolder destination: C:\MyFolder\destinationFolder ``` **輸入範例：使用來源資料夾名稱 (Linux) 移動資料夾** ``` - name: MovingFolderWithSourceFolderNameLinux action: MoveFolder inputs: - source: /Sample/MyFolder/SampleFolder destination: /MyFolder/ ``` **輸入範例：使用來源資料夾名稱 (Windows) 移動資料夾** ``` - name: MovingFolderWithSourceFolderNameWindows action: MoveFolder inputs: - source: C:\Sample\MyFolder\SampleFolder destination: C:\MyFolder\ ``` **輸入範例：使用萬用字元 (Linux) 移動資料夾** ``` - name: MovingFoldersWithWildCardLinux action: MoveFolder inputs: - source: /Sample/MyFolder/Sample* destination: /MyFolder/ ``` **輸入範例：使用萬用字元 (Windows) 移動資料夾** ``` - name: MovingFoldersWithWildCardWindows action: MoveFolder inputs: - source: C:\Sample\MyFolder\Sample* destination: C:\MyFolder\ ``` **輸入範例：在不覆寫的情況下移動資料夾 (Linux)** ``` - name: MovingFoldersWithoutOverwriteLinux action: MoveFolder inputs: - source: /Sample/MyFolder/SampleFolder destination: /MyFolder/destinationFolder overwrite: false ``` **輸入範例：在不覆寫的情況下移動資料夾 (Windows)** ``` - name: MovingFoldersWithoutOverwriteWindows action: MoveFolder inputs: - source: C:\Sample\MyFolder\SampleFolder destination: C:\MyFolder\destinationFolder overwrite: false ``` **Output** 無。 ### ReadFile (Linux、Windows、macOS) **ReadFile** 動作模組會讀取類型字串的文字檔案內容。此模組可用來讀取檔案的內容，以便透過鏈結或將資料讀取至`console.log`檔案的後續步驟中使用。如果指定的路徑是符號連結，則此模組會傳回目標檔案的內容。此模組僅支援文字檔案。 如果檔案編碼值與預設編碼 (`utf-8`) 值不同，您可以使用 `encoding`選項指定檔案編碼值。根據預設， `utf-16`和 `utf-32` 會假設使用小端點編碼。 根據預設，此模組無法將檔案內容列印至 `console.log` 檔案。您可以將 `printFileContent` 屬性設定為 來覆寫此設定`true`。 此模組只能傳回檔案的內容。它無法剖析檔案，例如 Excel 或 JSON 檔案。 發生下列情況時，動作模組會傳回錯誤： + 檔案在執行時間不存在。 + 動作模組在執行操作時遇到錯誤。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設值 | 可接受值 | 在所有平台上支援 | | --- | --- | --- | --- | --- | --- | --- | | path | 檔案路徑。 | String | 是 | N/A | N/A | 是 | | encoding | 編碼標準。 | String | 否 | utf8 | utf8、utf-8、utf16、utf-16、utf16-LEutf-16-LEutf16-BE、、utf-16-BE、utf32、utf-32、utf32-LEutf-32-LE、 utf32-BE和 utf-32-BE。編碼選項的值不區分大小寫。 | 是 | | printFileContent | 將檔案內容列印至 console.log 檔案。 | Boolean | 否 | false | N/A | 是。 | **輸入範例：讀取檔案 (Linux)** ``` - name: ReadingFileLinux action: ReadFile inputs: - path: /home/UserName/SampleFile.txt ``` **輸入範例：讀取檔案 (Windows)** ``` - name: ReadingFileWindows action: ReadFile inputs: - path: C:\Windows\WindowsUpdate.log ``` **輸入範例：讀取檔案並指定編碼標準** ``` - name: ReadingFileWithFileEncoding action: ReadFile inputs: - path: /FolderName/SampleFile.txt encoding: UTF-32 ``` **輸入範例：讀取檔案並列印至`console.log`檔案** ``` - name: ReadingFileToConsole action: ReadFile inputs: - path: /home/UserName/SampleFile.txt printFileContent: true ``` **Output** | 欄位 | 說明 | Type | | --- | --- | --- | | content | 檔案內容。 | string | **輸出範例** ``` { "content" : "The file content" } ``` ### SetFileEncoding (Linux、Windows、macOS) **SetFileEncoding** 動作模組會修改現有檔案的編碼屬性。此模組可以將檔案編碼從 `utf-8` 轉換為指定的編碼標準。根據預設， `utf-16`和 `utf-32` 假設為小端點編碼。 發生下列情況時，動作模組會傳回錯誤： + 您沒有執行指定修改的許可。 + 檔案在執行時間不存在。 + 動作模組在執行操作時遇到錯誤。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設值 | 可接受值 | 在所有平台上支援 | | --- | --- | --- | --- | --- | --- | --- | | path | 檔案路徑。 | String | 是 | N/A | N/A | 是 | | encoding | 編碼標準。 | String | 否 | utf8 | utf8、utf-8、utf16、utf-16、utf16-LEutf-16-LEutf16-BE、、utf-16-BE、utf32、utf-32、utf32-LEutf-32-LE、 utf32-BE和 utf-32-BE。編碼選項的值不區分大小寫。 | 是 | **輸入範例：設定檔案編碼屬性** ``` - name: SettingFileEncodingProperty action: SetFileEncoding inputs: - path: /home/UserName/SampleFile.txt encoding: UTF-16 ``` **Output** 無。 ### SetFileOwner (Linux、Windows、macOS) **SetFileOwner** 動作模組會修改現有檔案的 `owner`和`group`擁有者屬性。如果指定的檔案是符號連結，模組會修改來源檔案的 `owner` 屬性。Windows 平台不支援此模組。 此模組接受使用者和群組名稱做為輸入。如果未提供群組名稱，模組會將檔案的群組擁有者指派給使用者所屬的群組。 發生下列情況時，動作模組會傳回錯誤： + 您沒有執行指定修改的許可。 + 指定的使用者或群組名稱在執行時間不存在。 + 檔案在執行時間不存在。 + 動作模組在執行操作時遇到錯誤。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設值 | 可接受值 | 在所有平台上支援 | | --- | --- | --- | --- | --- | --- | --- | | path | 檔案路徑。 | String | 是 | N/A | N/A | Windows 不支援。 | | owner | 使用者名稱。 | string | 是 | N/A | N/A | Windows 不支援。 | | group | 使用者群組的名稱。 | String | 否 | 使用者所屬的群組名稱。 | N/A | Windows 不支援。 | **輸入範例：設定檔案擁有者屬性，而不指定使用者群組的名稱** ``` - name: SettingFileOwnerPropertyNoGroup action: SetFileOwner inputs: - path: /home/UserName/SampleText.txt owner: LinuxUser ``` **輸入範例：透過指定擁有者和使用者群組來設定檔案擁有者屬性** ``` - name: SettingFileOwnerProperty action: SetFileOwner inputs: - path: /home/UserName/SampleText.txt owner: LinuxUser group: LinuxUserGroup ``` **Output** 無。 ### SetFolderOwner (Linux、Windows、macOS) **SetFolderOwner** 動作模組會遞迴修改現有資料夾的 `owner`和`group`擁有者屬性。根據預設，模組可以修改資料夾中所有內容的擁有權。您可以將 `recursive`選項設定為 `false`以覆寫此行為。Windows 平台不支援此模組。 此模組接受使用者和群組名稱做為輸入。如果未提供群組名稱，模組會將檔案的群組擁有者指派給使用者所屬的群組。 發生下列情況時，動作模組會傳回錯誤： + 您沒有執行指定修改的許可。 + 指定的使用者或群組名稱在執行時間不存在。 + 資料夾在執行時間不存在。 + 動作模組在執行操作時遇到錯誤。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設值 | 可接受值 | 在所有平台上支援 | | --- | --- | --- | --- | --- | --- | --- | | path | 資料夾路徑。 | String | 是 | N/A | N/A | Windows 不支援。 | | owner | 使用者名稱。 | string | 是 | N/A | N/A | Windows 不支援。 | | group | 使用者群組的名稱。 | String | 否 | 使用者所屬的群組名稱。 | N/A | Windows 不支援。 | | recursive | 設定為 時，覆寫修改資料夾所有內容之擁有權的預設行為false。 | Boolean | 否 | true | N/A | Windows 不支援。 | **輸入範例：設定資料夾擁有者屬性，而不指定使用者群組的名稱** ``` - name: SettingFolderPropertyWithOutGroup action: SetFolderOwner inputs: - path: /SampleFolder/ owner: LinuxUser ``` **輸入範例：設定資料夾擁有者屬性，而不覆寫資料夾中所有內容的擁有權 ** ``` - name: SettingFolderPropertyWithOutRecursively action: SetFolderOwner inputs: - path: /SampleFolder/ owner: LinuxUser recursive: false ``` **輸入範例：透過指定使用者群組的名稱來設定檔案擁有權屬性** ``` - name: SettingFolderPropertyWithGroup action: SetFolderOwner inputs: - path: /SampleFolder/ owner: LinuxUser group: LinuxUserGroup ``` **Output** 無。 ### SetFilePermissions (Linux、Windows、macOS) **SetFilePermissions** 動作模組會修改現有檔案`permissions`的 。Windows 平台不支援此模組。 的輸入`permissions`必須是字串值。 此動作模組可以建立具有作業系統預設 umask 值所定義許可的檔案 。如果您想要覆寫預設值，則必須設定 `umask` 值。 發生下列情況時，動作模組會傳回錯誤： + 您沒有執行指定修改的許可。 + 檔案在執行時間不存在。 + 動作模組在執行操作時遇到錯誤。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設值 | 可接受值 | 在所有平台上支援 | | --- | --- | --- | --- | --- | --- | --- | | path | 檔案路徑。 | String | 是 | N/A | N/A | Windows 不支援。 | | permissions | 檔案許可。 | String | 是 | N/A | N/A | Windows 不支援。 | **輸入範例：修改檔案許可** ``` - name: ModifyingFilePermissions action: SetFilePermissions inputs: - path: /home/UserName/SampleFile.txt permissions: 766 ``` **Output** 無。 ### SetFolderPermissions (Linux、Windows、macOS) **SetFolderPermissions** 動作模組會遞迴修改現有資料夾及其所有子檔案和子資料夾`permissions`的 。根據預設，此模組可以修改指定資料夾之所有內容的許可。您可以將 `recursive`選項設定為 `false`以覆寫此行為。Windows 平台不支援此模組。 的輸入`permissions`必須是字串值。 此動作模組可根據作業系統的預設 umask 值修改許可。如果您想要覆寫預設值，則必須設定 `umask` 值。 發生下列情況時，動作模組會傳回錯誤： + 您沒有執行指定修改的許可。 + 資料夾在執行時間不存在。 + 動作模組在執行操作時遇到錯誤。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設值 | 可接受值 | 在所有平台上支援 | | --- | --- | --- | --- | --- | --- | --- | | path | 資料夾路徑。 | String | 是 | N/A | N/A | Windows 不支援。 | | permissions | 資料夾許可。 | String | 是 | N/A | N/A | Windows 不支援。 | | recursive | 設為 時，覆寫修改資料夾所有內容許可的預設行為false。 | Boolean | 否 | true | N/A | Windows 不支援。 | **輸入範例：設定資料夾許可** ``` - name: SettingFolderPermissions action: SetFolderPermissions inputs: - path: SampleFolder/ permissions: 0777 ``` **輸入範例：設定資料夾許可，而不修改資料夾所有內容的許可** ``` - name: SettingFolderPermissionsNoRecursive action: SetFolderPermissions inputs: - path: /home/UserName/SampleFolder/ permissions: 777 recursive: false ``` **Output** 無。 ## 軟體安裝動作 下一節說明安裝或解除安裝軟體的動作模組。 **IAM 要求** 如果您的安裝下載路徑是 S3 URI，則與執行個體描述檔相關聯的 IAM 角色必須具有執行`S3Download`動作模組的許可。若要授予必要的許可，請將 `S3:GetObject` IAM 政策連接至與您執行個體描述檔相關聯的 IAM 角色，並指定儲存貯體的路徑。例如，`arn:aws:s3:::BucketName/*`)。 **複雜的 MSI 輸入** 如果您的輸入字串包含雙引號字元 (`"`)，您必須使用下列其中一種方法來確保正確解譯： + 您可以在字串外部使用單引號 (') 來包含它，並在字串內部使用雙引號 (")，如下列範例所示。 ``` properties: COMPANYNAME: '"Acme ""Widgets"" and ""Gizmos."""' ``` 在這種情況下，如果您需要在字串內使用撇號，則必須將其逸出。這表示在撇號之前使用另一個單引號 (')。 + 您可以在字串外部使用雙引號 (") 來包含它。您也可以使用反斜線字元 (`\`) 逸出字串內的任何雙引號，如下列範例所示。 ``` properties: COMPANYNAME: "\"Acme \"\"Widgets\"\" and \"\"Gizmos.\"\"\"" ``` 這兩種方法都會將 值傳遞`COMPANYNAME="Acme ""Widgets"" and ""Gizmos."""`至 **msiexec**命令。 **Topics** + [InstallMSI (Windows)](#action-modules-install-msi) + [UninstallMSI (Windows)](#action-modules-uninstall-msi) ### InstallMSI (Windows) `InstallMSI` 動作模組會使用 MSI 檔案安裝 Windows 應用程式。您可以使用本機路徑、S3 物件 URI 或 Web URL 指定 MSI 檔案。重新啟動選項會設定系統的重新啟動行為。 AWS TOE 根據動作模組的輸入參數產生 **msiexec**命令。`path` (MSI 檔案位置） 和 `logFile`（日誌檔案位置） 輸入參數的值必須以引號 (") 括住。 下列 MSI 結束代碼視為成功： + 0 （成功） + 1614 (ERROR\$1PRODUCT\$1UNINSTALLED) + 1641 （重新啟動啟動） + 3010 （需要重新啟動） **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設值 | 可接受值 | | --- | --- | --- | --- | --- | --- | | path | 使用下列其中一項指定 MSI 檔案位置： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/toe-action-modules.html) 允許鏈結表達式。 | String | 是 | N/A | N/A | | reboot | 設定成功執行動作模組之後的系統重新啟動行為。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/toe-action-modules.html) | String | 否 | Allow | Allow, Force, Skip | | logOptions | 指定用於 MSI 安裝記錄的選項。指定的旗標會與`/L`命令列參數一起傳遞至 MSI 安裝程式以啟用記錄。如果未指定旗標， AWS TOE 會使用預設值。 如需 MSI 日誌選項的詳細資訊，請參閱 Microsoft *Windows Installer* 產品文件中的[命令列選項](https://learn.microsoft.com/en-us/windows/win32/msi/command-line-options)。 | String | 否 | \$1VX | i,w,e,a,r,u,c,m,o,p,v,x,\$1,\$1,\$1 | | logFile | 日誌檔案位置的絕對或相對路徑。如果日誌檔案路徑不存在，則會建立。如果未提供日誌檔案路徑， AWS TOE 不會存放 MSI 安裝日誌。 | String | 否 | N/A | N/A | | properties | MSI 記錄屬性索引鍵/值對 ，例如： `TARGETDIR: "C:\target\location"`   注意：不允許修改下列屬性： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/toe-action-modules.html) | Map【String】字串 | 否 | N/A | N/A | | ignoreAuthenticodeSignatureErrors | 針對路徑中指定的安裝程式，忽略 Authenticode 簽章驗證錯誤的旗標。**Get-AuthenticodeSignature** 命令用於驗證安裝程式。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/toe-action-modules.html) | Boolean | 否 | false | true, false | | allowUnsignedInstaller | 允許執行路徑中指定之未簽署安裝程式的旗標。**Get-AuthenticodeSignature** 命令用於驗證安裝程式。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/toe-action-modules.html) | Boolean | 否 | false | true, false | **範例** 下列範例顯示元件文件的輸入區段變化，視您的安裝路徑而定。 **輸入範例：本機文件路徑安裝** ``` - name: local-path-install steps: - name: LocalPathInstaller action: InstallMSI inputs: path: C:\sample.msi logFile: C:\msilogs\local-path-install.log logOptions: '*VX' reboot: Allow properties: COMPANYNAME: '"Amazon Web Services"' ignoreAuthenticodeSignatureErrors: true allowUnsignedInstaller: true ``` **輸入範例：Amazon S3 路徑安裝** ``` - name: s3-path-install steps: - name: S3PathInstaller action: InstallMSI inputs: path: s3:///sample.msi logFile: s3-path-install.log reboot: Force ignoreAuthenticodeSignatureErrors: false allowUnsignedInstaller: true ``` **輸入範例：Web 路徑安裝** ``` - name: web-path-install steps: - name: WebPathInstaller action: InstallMSI inputs: path: https:///sample.msi logFile: web-path-install.log reboot: Skip ignoreAuthenticodeSignatureErrors: true allowUnsignedInstaller: false ``` **Output** 以下是動作`InstallMSI`模組輸出的範例。 ``` { "logFile": "web-path-install.log", "msiExitCode": 0, "stdout": "" } ``` ### UninstallMSI (Windows) `UninstallMSI` 動作模組可讓您使用 MSI 檔案移除 Windows 應用程式。您可以使用本機檔案路徑、S3 物件 URI 或 Web URL 指定 MSI 檔案位置。重新啟動選項會設定系統的重新啟動行為。 AWS TOE 根據動作模組的輸入參數產生 **msiexec**命令。產生**msiexec**命令時，MSI 檔案位置 (`path`) 和日誌檔案位置 (`logFile`) 會以雙引號 (") 明確括住。 下列 MSI 結束代碼視為成功： + 0 （成功） + 1605 (ERROR\$1UNKNOWN\$1PRODUCT) + 1614 (ERROR\$1PRODUCT\$1UNINSTALLED) + 1641 （重新啟動啟動） + 3010 （需要重新啟動） **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設值 | 可接受值 | | --- | --- | --- | --- | --- | --- | | path | 使用下列其中一項指定 MSI 檔案位置： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/toe-action-modules.html) 允許鏈結表達式。 | String | 是 | N/A | N/A | | reboot | 設定成功執行動作模組之後的系統重新啟動行為。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/toe-action-modules.html) | String | 否 | Allow | Allow, Force, Skip | | logOptions | 指定用於 MSI 安裝記錄的選項。指定的旗標會與`/L`命令列參數一起傳遞至 MSI 安裝程式以啟用記錄。如果未指定旗標， AWS TOE 會使用預設值。 如需 MSI 日誌選項的詳細資訊，請參閱 Microsoft *Windows Installer* 產品文件中的[命令列選項](https://docs.microsoft.com/en-us/windows/win32/msi/command-line-options)。 | String | 否 | \$1VX | i,w,e,a,r,u,c,m,o,p,v,x,\$1,\$1,\$1 | | logFile | 日誌檔案位置的絕對或相對路徑。如果日誌檔案路徑不存在，則會建立。如果未提供日誌檔案路徑， AWS TOE 不會存放 MSI 安裝日誌。 | String | 否 | N/A | N/A | | properties | MSI 記錄屬性索引鍵/值對 ，例如： `TARGETDIR: "C:\target\location"`   注意：不允許修改下列屬性： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/toe-action-modules.html) | Map【String】字串 | 否 | N/A | N/A | | ignoreAuthenticodeSignatureErrors | 針對路徑中指定的安裝程式，忽略 Authenticode 簽章驗證錯誤的旗標。**Get-AuthenticodeSignature** 命令用於驗證安裝程式。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/toe-action-modules.html) | Boolean | 否 | false | true, false | | allowUnsignedInstaller | 允許執行路徑中指定之未簽署安裝程式的旗標。**Get-AuthenticodeSignature** 命令用於驗證安裝程式。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/toe-action-modules.html) | Boolean | 否 | false | true, false | **範例** 下列範例顯示元件文件的輸入區段變化，視您的安裝路徑而定。 **輸入範例：移除本機文件路徑安裝** ``` - name: local-path-uninstall steps: - name: LocalPathUninstaller action: UninstallMSI inputs: path: C:\sample.msi logFile: C:\msilogs\local-path-uninstall.log logOptions: '*VX' reboot: Allow properties: COMPANYNAME: '"Amazon Web Services"' ignoreAuthenticodeSignatureErrors: true allowUnsignedInstaller: true ``` **輸入範例：移除 Amazon S3 路徑安裝** ``` - name: s3-path-uninstall steps: - name: S3PathUninstaller action: UninstallMSI inputs: path: s3:///sample.msi logFile: s3-path-uninstall.log reboot: Force ignoreAuthenticodeSignatureErrors: false allowUnsignedInstaller: true ``` **輸入範例：移除 Web 路徑安裝** ``` - name: web-path-uninstall steps: - name: WebPathUninstaller action: UninstallMSI inputs: path: https:///sample.msi logFile: web-path-uninstall.log reboot: Skip ignoreAuthenticodeSignatureErrors: true allowUnsignedInstaller: false ``` **Output** 以下是動作`UninstallMSI`模組輸出的範例。 ``` { "logFile": "web-path-uninstall.log", "msiExitCode": 0, "stdout": "" } ``` ## 系統動作模組 下一節說明執行系統動作或更新系統設定的動作模組。 **Topics** + [重新啟動 (Linux、Windows)](#action-modules-reboot) + [SetRegistry (Windows)](#action-modules-setregistry) + [UpdateOS (Linux、Windows)](#action-modules-updateos) ### 重新啟動 (Linux、Windows) **重新啟動**動作模組會重新啟動執行個體。它具有可設定的選項，可延遲重新啟動的開始。根據預設， `delaySeconds` 會設定為 `0`，這表示沒有延遲。重新啟動動作模組不支援步驟逾時，因為它在執行個體重新啟動時不適用。 如果 Systems Manager 代理程式叫用應用程式，則會將結束碼 (`3010`適用於 Windows，`194`適用於 Linux) 交給 Systems Manager 代理程式。Systems Manager 代理程式會處理系統重新啟動，如[從指令碼重新啟動受管執行個體](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html)中所述。 如果在主機上調用應用程式做為獨立程序，它會儲存目前的執行狀態、設定重新啟動後自動執行觸發程序，以在重新啟動後重新執行應用程式，然後重新啟動系統。 **重新啟動後自動執行觸發：** + **Windows**。 會使用在 自動執行的觸發條件來 AWS TOE 建立 Windows 任務排程器項目 `SystemStartup` + **Linux**。 在 crontab 中 AWS TOE 新增任務，該任務會在系統重新啟動後自動執行。 ``` @reboot /download/path/awstoe run --document s3://bucket/key/doc.yaml ``` 此觸發會在應用程式啟動時清除。 **重試** 根據預設，重試次數上限會設定為 Systems Manager `CommandRetryLimit`。如果重新啟動次數超過重試限制，則自動化會失敗。您可以編輯 Systems Manager 代理程式組態檔案 () 來變更限制`Mds.CommandRetryLimit`。請參閱 Systems Manager 代理程式開放原始碼中的[執行期組態](https://github.com/aws/amazon-ssm-agent/blob/mainline/README.md#runtime-configuration)。 若要使用**重新啟動**動作模組，對於包含重新啟動的步驟 `exitcode`（例如，`3010`)，您必須以 執行應用程式二進位檔`sudo user`。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | 預設 | | --- | --- | --- | --- | --- | | delaySeconds | 在開始重新啟動之前延遲特定的時間量。 | Integer | 否 | `0` | **輸入範例：重新啟動步驟** ``` - name: RebootStep action: Reboot onFailure: Abort maxAttempts: 2 inputs: delaySeconds: 60 ``` **輸出** 無。 **重新啟動**模組完成後，Image Builder 會繼續執行建置中的下一個步驟。 ### SetRegistry (Windows) **SetRegistry** 動作模組接受輸入清單，並可讓您設定指定登錄機碼的值。如果登錄機碼不存在，則會在定義的路徑中建立。此功能僅適用於 Windows。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | | --- | --- | --- | --- | | path | 登錄機碼的路徑。 | String | 是 | | name | 登錄機碼的名稱。 | String | 是 | | value | 登錄機碼的值。 | String/Number/Array | 是 | | type | 登錄機碼的值類型。 | String | 是 | **支援的路徑字首** + `HKEY_CLASSES_ROOT / HKCR:` + `HKEY_USERS / HKU:` + `HKEY_LOCAL_MACHINE / HKLM:` + `HKEY_CURRENT_CONFIG / HKCC:` + `HKEY_CURRENT_USER / HKCU:` **支援的 類型** + `BINARY` + `DWORD` + `QWORD` + `SZ` + `EXPAND_SZ` + `MULTI_SZ` **輸入範例：設定登錄機碼值** ``` - name: SetRegistryKeyValues action: SetRegistry maxAttempts: 3 inputs: - path: HKLM:\SOFTWARE\MySoftWare name: MyName value: FirstVersionSoftware type: SZ - path: HKEY_CURRENT_USER\Software\Test name: Version value: 1.1 type: DWORD ``` **輸出** 無。 ### UpdateOS (Linux、Windows) **UpdateOS** 動作模組新增了安裝 Windows 和 Linux 更新的支援。預設會安裝所有可用的更新。或者，您可以為要安裝的動作模組設定一或多個特定更新清單。您也可以指定要從安裝中排除的更新。 如果同時提供「包含」和「排除」清單，則產生的更新清單只能包含未列在「排除」清單中的「包含」清單。 **注意** **UpdateOS** 不支援 Amazon Linux 2023 (AL2023)。建議您將基本 AMI 更新為每個版本隨附的新版本。如需其他替代方案，請參閱《*Amazon Linux 2023 使用者指南*》中的[控制從主要和次要版本收到的更新](https://docs.aws.amazon.com/linux/al2023/ug/deterministic-upgrades.html#controlling-release-updates)。 + **Windows**。更新是從目標機器上設定的更新來源進行安裝。 + **Linux**。應用程式會在 Linux 平台中檢查支援的套件管理員，並使用 `yum`或 `apt-get`套件管理員。如果都不支援，則會傳回錯誤。您應該具有執行 **UpdateOS** 動作模組的`sudo`許可。如果您沒有`sudo`許可，`error.Input`則會傳回 。 **Input** | 金鑰名稱 | 說明 | Type | 必要 | | --- | --- | --- | --- | | include | 對於 Windows，您可以指定下列項目： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/toe-action-modules.html) 對於 Linux，您可以指定要包含在安裝更新清單中的一或多個套件。 | 字串清單 | 否 | | exclude | 對於 Windows，您可以指定下列項目： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/toe-action-modules.html) 對於 Linux，您可以指定要從安裝更新清單中排除的一或多個套件。 | 字串清單 | 否 | **輸入範例：新增安裝 Linux 更新的支援** ``` - name: UpdateMyLinux action: UpdateOS onFailure: Abort maxAttempts: 3 inputs: exclude: - ec2-hibinit-agent ``` **輸入範例：新增安裝 Windows 更新的支援** ``` - name: UpdateWindowsOperatingSystem action: UpdateOS onFailure: Abort maxAttempts: 3 inputs: include: - KB1234567 - '*Security*' ``` **輸出** 無。 # 設定 AWS TOE 執行命令的輸入 若要簡化命令的 AWS TOE **run**命令列輸入，您可以在具有`.json`副檔名的 JSON 格式輸入組態檔案中包含命令參數和選項的設定。 AWS TOE 可以從下列其中一個位置讀取檔案： + 本機檔案路徑 (*./config.json)。* + S3 儲存貯體 (*s3：////config.json)。* 當您輸入 **run**命令時，您可以使用 **--config** 參數指定輸入組態檔案。例如： ``` awstoe run --config /config.json ``` **輸入組態檔案** 輸入組態 JSON 檔案包含您可以直接透過**run**命令參數和選項提供的所有設定的鍵/值對。如果您在輸入組態檔案和 **run**命令中指定設定，做為參數或選項，則適用下列優先順序規則： **優先順序規則** 1. 透過 AWS CLI參數或選項直接提供給 中**run**命令的設定，會覆寫輸入組態檔案中針對相同設定定義的任何值。 1. 輸入組態檔案中的設定會覆寫元件預設值。 1. 如果沒有其他設定傳遞到元件文件中，則可以套用預設值，如果有的話。 此規則有兩個例外狀況：文件和參數。這些設定在輸入組態和命令參數中運作方式不同。如果您使用輸入組態檔案，則不得將這些參數直接指定給 **run**命令。這樣做會產生錯誤。 **元件設定** 輸入組態檔案包含下列設定。若要簡化檔案，您可以捨棄任何不需要的選用設定。除非另有說明，否則所有設定都是選用的。 + **cwIgnoreFailures** （布林值） – 忽略 CloudWatch Logs 中的記錄失敗。 + **cwLogGroup** （字串） – CloudWatch Logs `LogGroup`的名稱。 + **cwLogRegion** （字串） – 適用於 CloudWatch Logs AWS 的區域。 + **cwLogStream** （字串） – CloudWatch Logs `LogStream`的名稱，指示 AWS TOE 在何處串流`console.log`檔案。 + **documentS3BucketOwner** （字串） – S3 URI 型文件儲存貯體擁有者的帳戶 ID。 + **文件** （物件陣列，必要） – 代表 AWS TOE **run**命令正在執行之 YAML 元件文件的 JSON 物件陣列。至少必須指定一個元件文件。 每個物件都包含下列欄位： + **path** （字串，必要） – YAML 元件文件的檔案位置。這必須是下列其中一項： + 本機檔案路徑 (*./component-doc-example.yaml)。* + S3 URI (`s3://bucket/key`)。 + Image Builder 元件建置版本 ARN (arn：aws：imagebuilder：us-west-*2：123456789012*：component/*my-example-component*/2021.12.02/1)。 + **參數** （物件陣列） – 鍵值對物件的陣列，每個物件代表**run**命令在執行元件文件時傳入的元件特定參數。元件的參數是選用的。元件文件不一定會定義參數。 每個物件都包含下列欄位： + **name** （字串，必要） – 元件參數的名稱。 + **value** （字串，必要） – 要傳入具名參數元件文件的值。 若要進一步了解元件參數，請參閱 [在自訂元件文件中使用變數](toe-user-defined-variables.md)頁面中的**參數**一節。 + **executonId** （字串） – 這是套用至目前**run**命令執行的唯一 ID。此 ID 包含在輸出和日誌檔案名稱中，以唯一識別這些檔案，並將其連結至目前的命令執行。如果沒有此設定， AWS TOE 會產生 GUID。 + **logDirectory** （字串） – AWS TOE 儲存此命令執行中所有日誌檔案的目的地目錄。根據預設，此目錄位於下列父目錄內：`TOE__`。如果您未指定日誌目錄， AWS TOE 會使用目前的工作目錄 (`.`)。 + **logS3BucketName** （字串） – 如果元件日誌存放在 Amazon S3 （建議） 中，請將元件應用程式日誌 AWS TOE 上傳到此參數中名為 的 S3 儲存貯體。 + **logS3BucketOwner** （字串） – 如果元件日誌存放在 Amazon S3 （建議），這是 AWS TOE 寫入日誌檔案之儲存貯體的擁有者帳戶 ID。 + **logS3KeyPrefix** （字串） – 如果元件日誌存放在 Amazon S3 （建議） 中，這是儲存貯體中日誌位置的 S3 物件金鑰字首。 + **參數** （物件陣列） – 代表全域套用至目前**run**命令執行中所有元件之參數的鍵值對物件陣列。 + **name** （字串，必要） – 全域參數的名稱。 + **value** （字串，必要） – 要傳遞至具名參數之所有元件文件的值。 + **階段** （字串） – 以逗號分隔的清單，指定要從 YAML 元件文件執行的階段。如果元件文件包含其他階段，則不會執行這些階段。 + **stateDirectory** （字串） – 存放狀態追蹤檔案的檔案路徑。 + **trace** （布林值） – 啟用主控台的詳細記錄。 **範例** 下列範例顯示為兩個元件文件執行 `build`和 `test`階段的輸入組態檔案：`sampledoc.yaml`、 和 `conversation-intro.yaml`。每個元件文件都有一個參數，僅適用於其本身，而且兩者都使用一個共用參數。`project` 參數適用於這兩個元件文件。 ``` { "documents": [ { "path": "/awstoe/sampledoc.yaml>", "parameters": [ { "name": "dayofweek", "value": "Monday" } ] }, { "path": "/awstoe/conversation-intro.yaml>", "parameters": [ { "name": "greeting", "value": "Hello, HAL." } ] } ], "phases": "build,test", "parameters": [ { "name": "project", "value": "examples" } ], "cwLogGroup": "", "cwLogStream": "", "documentS3BucketOwner": "", "executionId": "", "logDirectory": "", "logS3BucketName": "", "logS3KeyPrefix": "", "logS3BucketOwner": "" } ```