翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # カスタム AWSTOE コンポーネントのコンポーネントドキュメントフレームワークを使用する AWS Task Orchestrator and Executor (AWSTOE) コンポーネントフレームワークを使用してコンポーネントを構築するには、作成したコンポーネントに適用されるフェーズとステップを表す YAML ベースのドキュメントを提供する必要があります。コンポーネントは、新しい Amazon マシンイメージ (AMI) またはコンテナイメージを作成するときに AWS のサービス 使用します。 **Topics** + [コンポーネントドキュメントワークフロー](#component-doc-workflow) + [コンポーネントロギング](#component-logging) + [入力チェーンと出力連鎖](#document-chaining) + [文書スキーマと定義](#document-schema) + [ドキュメントの例](#document-example) + [カスタムコンポーネントドキュメントでの変数の使用](toe-user-defined-variables.md) + [で条件付きコンストラクトを使用する AWSTOE](toe-conditional-constructs.md) + [AWSTOE コンポーネントドキュメントで比較演算子を使用する](toe-comparison-operators.md) + [AWSTOE コンポーネントドキュメントで論理演算子を使用する](toe-logical-operators.md) + [でループコンストラクトを使用する AWSTOE](toe-looping-constructs.md) ## コンポーネントドキュメントワークフロー AWSTOE コンポーネントドキュメントでは、フェーズとステップを使用して関連タスクをグループ化し、それらのタスクをコンポーネントの論理ワークフローに整理します。 **ヒント** コンポーネントを使用してイメージを構築するサービスには、ビルドプロセスにどのフェーズを使用するか、またそれらのフェーズをいつ実行できるかについてのルールが実装されている場合があります。これはコンポーネントを設計する際に考慮すべき重要な点です。 **phases** フェーズは、イメージビルドプロセスにおけるワークフローの進行状況を表します。例えば、Image Builder サービスは、生成するイメージのビルド段階で `build` と `validate` のフェーズを使用します。*テスト段階*では `test` と `container-host-test` フェーズを使用して、イメージスナップショットまたはコンテナイメージが期待どおりの結果を生成することを確認してから、最終的な AMI を作成するか、コンテナイメージを配布します。 コンポーネントが実行されると、各フェーズの関連コマンドがコンポーネントドキュメントに表示されている順序で適用されます。 **フェーズのルール** + フェーズ名はドキュメント内で一意である必要があります。 + 文書には多数のフェーズを定義できます。 + ドキュメントには、次のうち、少なくとも 1 つは指定が必要です。 + **ビルド** — Image Builder の場合、このフェーズは通常、ビルド段階で使用されます。 + **検証** — Image Builder の場合、このフェーズは通常、ビルド段階で使用されます。 + **テスト** — Image Builder の場合、このフェーズは通常、テスト段階で使用されます。 + フェーズは、常にドキュメントで定義されている順序で実行されます。で AWSTOE AWS CLI コマンドに指定された順序は効果がありません。 **Steps** ステップは、各フェーズ内のワークフローを定義する個別の作業単位です。ステップは順番に実行されます。ただし、あるステップのインプットまたはアウトプットを、インプットとして後続のステップに送ることもあります。これをロールの連鎖と呼びます。 **ステップのルール** + その名前はボットに対して一意である必要があります。 + ステップでは、終了コードを返すサポートされているアクション (アクションモジュール) を使用する必要があります。 サポートされているアクションモジュールの全リスト、その仕組み、入出力値、例については、[AWSTOE コンポーネントマネージャーでサポートされるアクションモジュール](toe-action-modules.md) を参照してください。 ## コンポーネントロギング AWSTOE は、コンポーネントが実行されるたびに、新しいイメージの構築とテストに使用される新しいログフォルダを EC2 インスタンスに作成します。コンテナイメージの場合、ログフォルダはコンテナに保存されます。 イメージ作成プロセス中に問題が発生した場合のトラブルシューティングを支援するために、コンポーネントの実行中に AWSTOE が作成する入力ドキュメントとすべての出力ファイルはログフォルダに保存されます。 ログフォルダ名は次の部分で構成されています。 1. **ログディレクトリ** – サービスが AWSTOE コンポーネントを実行すると、コマンドの他の設定とともにログディレクトリに渡されます。以下の例では、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** – これは、 が 1 つ以上のコンポーネント AWSTOE を実行するときに割り当てられる GUID です。 例: `/var/lib/amazon/toe/TOE_2021-07-01_12-34-56_UTC-0_a1bcd2e3-45f6-789a-bcde-0fa1b2c3def4` AWSTOE は、次のコアファイルを ログフォルダに保存します。 **入力ファイル** + **document.yaml** — コマンドの入力として使用されるドキュメント。コンポーネントが実行されると、このファイルはアーティファクトとして保存されます。 **出力ファイル** + **application.log** — アプリケーションログには、コンポーネントの実行中に何が起こっているかを示す。 AWSTOE のタイムスタンプ付きのデバッグレベルの情報が含まれます。 + **detailedoutput.json** — この JSON ファイルには、コンポーネントのランタイムに適用されるすべてのドキュメント、フェーズ、ステップの実行ステータス、入力、出力、失敗に関する詳細情報が含まれています。 + **console.log** – コンソールログには、コンポーネントの実行中に がコンソールに AWSTOE 書き込むすべての標準出力 (stdout) および標準エラー (stderr) 情報が含まれます。 + **chaining.json** – この JSON ファイルは、連鎖式の解決 AWSTOE に適用された最適化を表します。 **注記** ログフォルダには、ここで説明していない他の一時ファイルが含まれている場合もあります。 ## 入力チェーンと出力連鎖 AWSTOE 設定管理アプリケーションは、以下の形式でリファレンスを記述することで、入出力を連鎖させる機能を提供します。 `{{ 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 }}'` + 連鎖式は同じドキュメント内の他のステップやフェーズの変数を参照できます。ただし、呼び出し元のサービスには、連鎖式を 1 つのステージのコンテキスト内でのみ動作させることを要求するルールがある場合があります。例えば、Image Builder は各ステージを独立して実行するため、ビルドステージから*テストステージ*へのチェーニングをサポートしていません。 + 連鎖式のインデックスは 0 から始まるインデックスに従います。インデックスは最初の要素を参照するゼロ (0) から始まります。 **例** 次のサンプルステップの 2 番目のエントリでソース変数を参照する場合、チェーンパターンは `{{ 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: ``` ドキュメントのスキーマ定義は次のとおりです。 | フィールド | 説明 | タイプ | 必須 | | --- | --- | --- | --- | | 名前 | 文書の名前。 | String | いいえ | | 説明 | 文書の説明。 | String | いいえ | | schemaVersion | ドキュメントのスキーマバージョン。現在は 1.0。 | String | はい | | phases | フェーズとそのステップのリスト。 | リスト | はい | フェーズのスキーマ定義は次のとおりです。 | フィールド | 説明 | タイプ | 必須 | | --- | --- | --- | --- | | 名前 | フェーズの名前。 | String | はい | | ステップ | フェーズ内のステップのリスト。 | リスト | はい | ステップのスキーマ定義は次のとおりです。 | フィールド | 説明 | タイプ | 必須 | デフォルトの値 | | --- | --- | --- | --- | --- | | 名前 | ステップのユーザー定義名。 | String | | | | アクション | ステップを実行するモジュールに関するキーワード。 | String | | | | timeoutSeconds | ステップが失敗または再試行されるまでに実行される秒数。 また、タイムアウトが無限であることを示す -1 値もサポートします。0 やその他の負の値は使用できません。 | 整数 | いいえ | 7,200 秒 (120 分) | | onFailure | ステップが失敗した場合は実行する内容を指定します。有効な値は次のとおりです。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/imagebuilder/latest/userguide/toe-use-documents.html) | String | いいえ | 中止 | | maxAttempts | ステップが失敗するまでに許可される最大試行回数。 | 整数 | いいえ | 1 | | 入力 | アクションモジュールがステップを実行するのに必要なパラメータが含まれます。 | dict | はい | | ## ドキュメントの例 次の例は、ターゲットオペレーティングシステムのタスクを実行する 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: MSI インストーラ AWS CLI を使用して をインストールする** 以下は、MSI インストーラ AWS CLI で をインストールするドキュメントの例です。 ``` 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 }}' ``` ------ # カスタムコンポーネントドキュメントでの変数の使用 変数を使用すると、アプリケーション全体で使用できるわかりやすい名前でデータにラベルを付けることができます。複雑なワークフローでは、シンプルで読み取り可能な形式でカスタム変数を定義し、 AWSTOE コンポーネントの YAML アプリケーションコンポーネントドキュメントで参照できます。 このセクションでは、構文、名前の制約、例など、YAML アプリケーション AWSTOE コンポーネントドキュメントでコンポーネントの変数を定義するのに役立つ情報を提供します。 ## 定数 定数は不変の変数で、一度定義すると変更したりオーバーライドしたりすることはできません。定数は、 AWSTOE ドキュメントの `constants`セクションの値を使用して定義できます。 **定数命名規則** + 名前は 3 文字以上 128 文字以下でなければならない。 + 名前には、英数字（a-z, A-Z, 0-9）、ダッシュ（-）、アンダースコア（\$1）のみを含めることができます。 + 名前は文書内で一意でなければならない。 + 名前は YAML 文字列として指定する必要があります。 **[Syntax]** (構文) ``` 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 }} ``` ## パラメータ パラメータは、呼び出し元のアプリケーションがランタイムに提供できる設定を含む可変変数です。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 }} ``` ### ランタイムにパラメータをオーバーライドする の `--parameters`オプションをキーと値のペア AWS CLI とともに使用して、実行時にパラメータ値を設定できます。 + パラメータのキーと値のペアを等号 (=) で区切って名前と値として指定します。 + 複数のパラメータはカンマで区切る必要があります。 + YAML コンポーネントドキュメントにないパラメータ名は無視されます。 + パラメータ名と値はどちらも必須です。 **重要** コンポーネントパラメータはプレーンテキストの値で、 AWS CloudTrailに記録されます。シークレットを保存するには、 AWS Secrets Manager または AWS Systems Manager Parameter Store を使用することをお勧めします。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 オプション: | 必要 | 説明 | | --- | --- | --- | | --parameters *name*=*value*,... | いいえ | このオプションは、パラメータ名をキーとして、キーと値のペアのリストを取得します。 | **例** 次の例は YAML ドキュメントでのパラメータの使用方法を示しています。 + この `--parameter` オプションで指定されたパラメータのキーと値のペアは無効です。 ``` --parameters ntp-server= ``` + AWS CLIに `--parameter` オプションでパラメータのキーと値のペアを 1 つ設定します。 ``` --parameters ntp-server=ntp-server-windows-qe.us-east1.amazon.com ``` + AWS CLIの `--parameter` オプションで複数のパラメータのキーと値のペアを設定します。 ``` --parameters ntp-server=ntp-server.amazon.com,http-url=https://internal-us-east1.amazon.com ``` ## Systems Manager パラメータストアパラメータを使用する 変数の前に を付けることで、コンポーネントドキュメントで AWS Systems Manager Parameter Store パラメータ (SSM パラメータ) を参照できます`aws:ssm`。例えば、 `{{ aws:ssm:/my/param }}` は SSM パラメータ の値に解決されます`/my/param`。 この機能は、次の SSM パラメータタイプをサポートしています。 + 文字列 – AWSTOE 文字列タイプにマッピングされます。 + StringList – タイプにマッピングします AWSTOE `stringList`。 + SecureString – AWSTOE 文字列タイプにマッピングします。 パラメータストアの詳細については、 *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 }}`。詳細については、[「Parameter Store パラメータからのシークレットの参照 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-*" } ] } ``` ------ 暗号化された値にアクセスするには、次のアクセス許可も必要です。 + カスタマーマネージドで暗号化された`SecureString`パラメータまたは AWS Secrets Manager 値`kms:Decrypt`に を追加します AWS KMS key。 + Secrets Manager シークレットを参照`secretsmanager:GetSecretValue`する場合は、 を追加します。 ### コンポーネントドキュメントで 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) }}" ``` # で条件付きコンストラクトを使用する AWSTOE 条件構造は、指定された条件式が `true` と `false` のどちらに評価されるかに基づいて、異なるアクションをコンポーネントドキュメントで実行します。`if` 構造を使用すると、コンポーネントドキュメントの実行フローを制御できます。 ## if 構造 `if` 構造を使用すると、ステップを実行する必要があるかどうかを評価できます。デフォルトでは、`if` 条件式が `true` に評価されると AWSTOE はステップを実行し、条件が `false` に評価されると AWSTOE はステップをスキップします。ステップがスキップされた場合でも、フェーズとドキュメントが正常に実行されたかどうかを AWSTOE が評価するときは、成功したステップとして扱われます。 **注記** `if` ステートメントが評価されるのは 1 回だけです。これは、ステップが再起動をトリガーした場合でも同様です。再起動したステップは、その `if` ステートメントが既に評価されたことを認識し、中断した箇所から続行します。 ### 構文 ``` if: - : [then: ] [else: ] ``` | キー名 | 必要 | 説明 | | --- | --- | --- | | 条件式 | はい | 条件式の最上位には、次のタイプの演算子を 1 つだけ含めることができます。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/imagebuilder/latest/userguide/toe-conditional-constructs.html) 式が複数の条件を満たす必要がある場合は、論理演算子を使用して条件を指定します。 | | 次に | いいえ | 条件式が `true` に評価された場合に実行するアクションを定義します。 | | else | いいえ | 条件式が `false` に評価された場合に実行するアクションを定義します。 | | ステップアクション | 条件付き | `then` または `else` を使用するときは、次のステップアクションのいずれかを指定する必要があります。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/imagebuilder/latest/userguide/toe-conditional-constructs.html) | **例 1: パッケージをインストールする** AWSTOE コンポーネントドキュメントの以下のステップ例では、論理演算子を使用してパラメータ値をテストし、パッケージが解凍されている場合は、適切なパッケージマネージャーコマンドを実行してアプリケーションをインストールします。 ``` - 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: ステップをスキップする** 次の例は、ステップをスキップする 2 つの方法を示しています。1 つは論理演算子を使用し、もう 1 つは比較演算子と `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' ``` # AWSTOE コンポーネントドキュメントで比較演算子を使用する **[Assert](toe-action-modules.md#action-modules-assertion)** アクションモジュールや [if 構造構文](toe-conditional-constructs.md#toe-conditional-if) を使用する条件式では、以下の比較演算子を使用できます。比較演算子には、`stringIsEmpty` など、単一の値に対して動作するものもあれば、ベースライン値を 2 番目の値 (変数値) と比較して、条件式が `true` と `false` のどちらに評価されるかを判定するものもあります。 比較が 2 つの値で動作する場合、2 番目の値は連鎖変数にすることができます。 異なるタイプの値を比較すると、次の値変換が比較前に発生する可能性があります。 + 数値比較の場合、変数値が文字列の場合、 は文字列を評価前の数値 AWSTOE に変換します。変換が不可能な場合、比較は `false` を返します。例えば、変数値が `"1.0"` の場合は変換が機能しますが、変数値が `"a10"` の場合は変換に失敗します。 + 文字列比較の場合、変数値が数値の場合、 は評価の前に文字列 AWSTOE に変換します。 ## 文字列の比較 以下の比較演算子は文字列を対象として、値の比較、スペースや空の文字列かどうかのテスト、入力値と正規表現パターンの比較を行います。文字列比較では、大文字と小文字は区別されず、入力文字列の先頭または末尾のスペースはトリミングされません。 **文字列比較演算子** + [stringIsEmpty](#stringIsEmpty) + [stringIsWhitespace](#stringIsWhitespace) + [stringEquals](#stringEquals) + [stringLessThan](#stringLessThan) + [stringLessThanEquals](#stringLessThanEquals) + [stringGreaterThan](#stringGreaterThan) + [stringGreaterThanEquals](#stringGreaterThanEquals) + [patternMatches](#patternMatches) **stringIsEmpty** `stringIsEmpty` 演算子は、指定された文字列に文字が含まれていない場合に `true` を返します。例えば、次のようになります。 ``` # 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` パラメータで指定された文字列が、`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 の big パッケージの比較演算子 ([func (\$1Float) Cmp](https://pkg.go.dev/math/big#Float.Cmp) など) が使用されます。 + 整数 + 浮動小数点数 (float64 に基づき、-1.7e\$1308～\$11.7e\$1308 の数値をサポート) + 正規表現パターン `^[-+]?([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' ``` # AWSTOE コンポーネントドキュメントで論理演算子を使用する 次の論理演算子を使用して、コンポーネントドキュメントの条件式を追加または変更できます。 AWSTOE は、条件式を条件が指定された順序で評価します。コンポーネントドキュメントの比較演算子の詳細については、「[AWSTOE コンポーネントドキュメントで比較演算子を使用する](toe-comparison-operators.md)」を参照してください。 **and** `and` 演算子を使用すると、2 つ以上の比較を 1 つの式として評価できます。リスト内のすべての条件が true になる場合、式は `true` に評価されます。それ以外の場合、式は `false` に評価されます。 **例:** 次の例では、文字列と数値の 2 つの比較を実行します。どちらの比較も true になるため、式は true に評価されます。 ``` and: - stringEquals: 'test_string' value: 'test_string' - numberEquals: 1 value: 1 ``` 次の例も 2 つの比較を実行します。最初の比較は false になるため、その時点で評価は停止し、2 番目の比較はスキップされます。式は `false` に評価されます。 ``` and: - stringEquals: 'test_string' value: 'Hello world!' - numberEquals: 1 value: 1 ``` **or** `or` 演算子を使用すると、2 つ以上の比較を 1 つの式として評価できます。指定された比較のいずれかが true になる場合、式は `true` に評価されます。指定された比較のいずれも `true` に評価されない場合、式は `false` に評価されます。 **例:** 次の例では、文字列と数値の 2 つの比較を実行します。最初の比較は true になるため、式は `true` に評価され、2 番目の比較はスキップされます。 ``` or: - stringEquals: 'test_string' value: 'test_string' - numberEquals: 1 value: 3 ``` 次の例も 2 つの比較を実行します。最初の比較は false になり、評価は続行されます。2 番目の比較は 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** `not` 演算子を使用すると、1 つの比較を否定できます。比較が false になる場合、式は `true` に評価されます。比較が true になる場合、式は `false` に評価されます。 **例:** 次の例では、文字列比較を実行します。比較は false になるため、式は `true` に評価されます。 ``` not: - stringEquals: 'test_string' value: 'Hello world!' ``` 次の例も文字列比較を実行します。比較は true になるため、式は `false` に評価されます。 ``` not: - stringEquals: 'test_string' value: 'test_string' ``` # でループコンストラクトを使用する AWSTOE このセクションでは、 AWSTOEでループ構文を作成する際に役立つ情報を提供します。ループは、繰り返される命令シーケンスを定義する。 AWSTOEでは以下のタイプのループ構文を使用できます。 + `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 }}` — 指定したループの現在のイテレーション変数に関連付けられた値。 ### 参照式を解決する は参照式を次のように AWSTOE 解決します。 + `{{ .* }}` – 次のロジックを使用してこの式を AWSTOE 解決します。 + 現在実行中のステップのループが `` 値と一致すると、参照式は現在実行中のステップのループ構文に変換されます。 + 現在実行中のステップ内に指定されたループ構文がある場合は、`` はそのループ構文に解決されます。 + `{{ loop.* }}` – 現在実行中のステップで定義されているループコンストラクトを使用して式を AWSTOE 解決します。 参照式がループを含まないステップ内で使用されている場合、 AWSTOE は式を解決せず、置き換えなしでステップに表示されます。 **注記** YAML コンパイラーが参照式を正しく解釈するには、二重引用符で囲む必要があります。 ## ループ構文のタイプ このセクションでは、 AWSTOEで使用できるループ構文タイプに関する情報と例を紹介します。 **Topics** + [`for` ループ](#toe-loop-types-for) + [`forEach` ループ (入力リスト付き)](#toe-loop-types-foreach) + [区切りリストによる `forEach` ループ](#toe-loop-types-foreach-delimited) ### `for` ループ `for` ループは、変数の先頭と末尾で囲まれた境界内で指定された整数の範囲で反復処理を行います。イテレーション値は `[start, end]` のセットに含まれており、境界値も含まれます。 AWSTOE は、`start`、`end`、および `updateBy`の値を検証して、組み合わせが無限ループにならないようにします。 `for` ループスキーマ ``` - name: "StepName" action: "ActionModule" loop: name: "string" for: start: int end: int updateBy: int inputs: ... ``` **`for` ループ入力** | フィールド | 説明 | タイプ | [Required] (必須) | [Default] (デフォルト) | | --- | --- | --- | --- | --- | | `name` | ループの一意の名前。同じフェーズの他のループ名と比べると一意でなければなりません。 | String | いいえ | "" | | `start` | イテレーションの開始値。連鎖式は受け付けません。 | 整数 | はい | 該当なし | | `end` | 反復の終了値。連鎖式は受け付けません。 | 整数 | はい | 該当なし | | `updateBy` | 加算によってイテレーション値が更新される場合の違い。負または正の 0 以外の値でなければなりません。連鎖式は受け付けません。 | 整数 | はい | 該当なし | `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` ループ (入力リスト付き)** | フィールド | 説明 | タイプ | [Required] (必須) | [Default] (デフォルト) | | --- | --- | --- | --- | --- | | `name` | ループの一意の名前。同じフェーズの他のループ名と比べると一意でなければなりません。 | String | いいえ | "" | | `forEach` ループの文字列のリスト | 反復処理用の文字列のリスト。連鎖式をリスト内の文字列として受け入れます。YAML コンパイラが正しく解釈するために、連鎖式は二重引用符で囲む必要があります。 | 文字列のリスト | はい | 該当なし | 入力リストによる `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` ループ ループは、区切り文字で区切られた値を含む文字列を繰り返し処理します。文字列の構成要素を反復処理するには、 は区切り文字 AWSTOE を使用して文字列を反復処理に適した配列に分割します。 区切りリストスキーマによる `forEach` ループ ``` - name: "StepName" action: "ActionModule" loop: name: "string" forEach: list: "string" delimiter: ".,;:\n\t -_" inputs: ... ``` **区切りリスト入力による `forEach` ループ** | フィールド | 説明 | タイプ | [Required] (必須) | [Default] (デフォルト) | | --- | --- | --- | --- | --- | | `name` | ループに付けられた一意の名前。同じフェーズの他のループ名と比較した場合、ユニークでなければならない。 | String | いいえ | "" | | `list` | 構成文字列を共通の区切り文字で結合した文字列です。連鎖式も受け付けます。連鎖式の場合は、YAML コンパイラが正しく解釈できるように、必ず二重引用符で囲んでください。 | String | はい | 該当なし | | `delimiter` | ブロック内の文字列を区切るために使用する文字。デフォルトはカンマ文字です。与えられたリストで使用できる区切り文字は 1 つだけです。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/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* - ループのすべての反復は、このフィールドで指定された時間内に実行されなければならない。ループがタイムアウトすると、 はステップの再試行ポリシー AWSTOE を実行し、新しい試行ごとにタイムアウトパラメータをリセットします。最大再試行回数に達した後でループ実行がタイムアウト値を超えると、ステップの失敗メッセージにループ実行がタイムアウトになったことが示されます。 + onFailure - 以下のようにステップに失敗処理が適用される： + *onFailure* が に設定されている場合`Abort`、 はループ AWSTOE を終了し、再試行ポリシーに従ってステップを再試行します。最大再試行回数に達すると、 は現在のステップを失敗として AWSTOE マークし、プロセスの実行を停止します。 AWSTOE は、親フェーズとドキュメントのステータスコードを に設定します`Failed`。 **注記** 失敗したステップの後に、それ以上のステップは実行されません。 + onFailure が `Continue` に設定されている場合、 AWSTOE はループを抜け、リトライポリシーに従ってステップをリトライする。再試行の最大回数に達すると、 は現在のステップを失敗として AWSTOE マークし、次のステップの実行を続行します。 AWSTOE は、親フェーズとドキュメントのステータスコードを に設定します`Failed`。 + onFailure が `Ignore` に設定されている場合、 AWSTOE はループを抜け、リトライポリシーに従ってステップをリトライする。最大再試行回数に達すると、 は現在のステップを として AWSTOE マークし`IgnoredFailure`、次のステップの実行を続行します。 AWSTOE は、親フェーズとドキュメントのステータスコードを に設定します`SuccessWithIgnoredFailure`。 **注記** これでも実行は成功したとみなされますが、1 つ以上のステップが失敗して無視されたことを知らせる情報が含まれます。 + maxAttempts - 再試行ごとに、全ステップと全反復が最初から実行されます。 + status - ステップの実行の全体的なステータス。`status` は個々の反復のステータスを表すものではない。ループを含むステップのステータスは次のように決定されます。 + 1 回のイテレーションが実行に失敗した場合、ステップのステータスは失敗を示します。 + すべてのイテレーションが成功すると、ステップのステータスは成功を示します。 + startTime - ステップ実行の全体的な開始時間。個々のイテレーションの開始時間を表すものではありません。 + endTime - ステップ実行の全体的な終了時間。個々の反復の終了時刻を表すものではない。 + failureMessage - タイムアウト以外のエラーの場合に失敗した反復インデックスを含みます。タイムアウトエラーの場合、メッセージにはループの実行が失敗したことが示されます。失敗メッセージのサイズを最小限に抑えるため、イテレーションごとに個別のエラーメッセージは表示されません。 ## ステップとイテレーションの出力 すべてのイテレーションには出力が含まれます。ループ実行の終了時に、 は成功したすべての反復出力を AWSTOE に統合します`detailedOutput.json`。統合出力は、アクションモジュールの出力スキーマで定義されている対応する出力キーに属する値を照合したものです。次の例では、出力の統合方法を示しています。 **イテレーション 1 の `ExecuteBash` の出力** ``` { "stdout":"Hello" } ``` **イテレーション 2 の `ExecuteBash` の出力** ``` { "stdout":"World" } ``` **ステップ `ExecuteBash` の出力** ``` { "stdout":"Hello\nWorld" } ``` 例えば、`ExecuteBash`、`ExecutePowerShell`、および `ExecuteBinary` はアクションモジュール出力として `STDOUT` を返すアクションモジュールです。 `STDOUT` メッセージは改行文字で結合され、`detailedOutput.json` のステップの全体的な出力が生成されます。 AWSTOE は、失敗した反復の出力を統合しません。