翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Image Builder が AWS Task Orchestrator and Executor アプリケーションを使用してコンポーネントを管理する方法
EC2 Image Builder は AWS Task Orchestrator and Executor （AWSTOE) アプリケーションを使用して、追加の devops スクリプトやコードを使用せずに、複雑なワークフローの調整、システム設定の変更、イメージのテストを行います。このアプリケーションは、宣言型ドキュメントスキーマを実装するコンポーネントを管理および実行します。
AWSTOE は、イメージの作成時に Image Builder がビルドインスタンスとテストインスタンスにインストールするスタンドアロンアプリケーションです。これを手動で EC2 インスタンスにインストールして、独自のカスタムコンポーネントを作成することもできます。追加のセットアップは必要なく、オンプレミスでも実行できます。
**Topics**
+ [AWSTOE ダウンロード](#toe-downloads)
+ [サポート対象の リージョン](#toe-supported-regions)
+ [AWSTOE コマンドリファレンス](#toe-commands)
+ [を使用してカスタムコンポーネントを開発するための手動セットアップ AWSTOE](toe-get-started.md)
+ [カスタム AWSTOE コンポーネントのコンポーネントドキュメントフレームワークを使用する](toe-use-documents.md)
+ [AWSTOE コンポーネントマネージャーでサポートされるアクションモジュール](toe-action-modules.md)
+ [AWSTOE run コマンドの入力を設定する](toe-run-config-input.md)
## AWSTOE ダウンロード
インストールするには AWSTOE、アーキテクチャとプラットフォームのダウンロードリンクを選択します。サービスの VPC エンドポイント (Image Builder など) にアタッチする場合、 AWSTOE ダウンロード用の S3 バケットへのアクセスを含むカスタムエンドポイントポリシーがアタッチされている必要があります。そうしないと、ビルドインスタンスとテストインスタンスはブートストラップスクリプト (`bootstrap.sh`) をダウンロードして AWSTOE アプリケーションをインストールできなくなります。詳細については、「[Image Builder 用 VPC エンドポイントポリシーの作成](vpc-interface-endpoints.md#vpc-endpoint-policy)」を参照してください。
**重要**
AWS は TLS バージョン 1.0 および 1.1 のサポートを段階的に廃止しています。 AWSTOE ダウンロード用に S3 バケットにアクセスするには、クライアントソフトウェアで 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 スーズ 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 スーズ 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 スーズ 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) |
## サポート対象の リージョン
AWSTOE は、次のリージョンでスタンドアロンアプリケーションとしてサポートされています。
| 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 |
| アフリカ (ケープタウン) | 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 |
| 欧州 (ストックホルム) | eu-north-1 |
| 欧州 (ミラノ) | eu-south-1 |
| 欧州 (スペイン) | eu-south-2 |
| 欧州 (アイルランド) | eu-west-1 |
| 欧州 (ロンドン) | eu-west-2 |
| 欧州 (パリ) | eu-west-3 |
| イスラエル (テルアビブ) | il-central-1 |
| 中東 (アラブ首長国連邦) | me-central-1 |
| 中東 (バーレーン) | me-south-1 |
| 南米 (サンパウロ） | sa-east-1 |
| 中国 (北京) | cn-north-1 |
| 中国 (寧夏) | cn-northwest-1 |
## AWSTOE コマンドリファレンス
AWSTOE は、Amazon EC2 インスタンスで実行されるコマンドラインコンポーネント管理アプリケーションです。Image Builder が EC2 ビルドインスタンスまたはテストインスタンスを起動すると、インスタンス AWSTOE に がインストールされます。次に、 で AWSTOE コマンドを実行して AWS CLI 、イメージまたはコンテナレシピで指定されたコンポーネントをインストールまたは検証します。
**注記**
一部の AWSTOE アクションモジュールでは、Linux サーバーで実行するための昇格されたアクセス許可が必要です。昇格された権限を使用するには、コマンド構文の前に **sudo** を付けるか、ログイン時に **sudo su** コマンドを 1 回実行してから、以下にリンクされているコマンドを実行します。 AWSTOE アクションモジュールの詳細については、「」を参照してください[AWSTOE コンポーネントマネージャーでサポートされるアクションモジュール](toe-action-modules.md)。
***[run](#cmd-run)***
**run** コマンドを使用して、1 つ以上のコンポーネントドキュメントの YAML ドキュメントスクリプトを実行します。
***[validate](#cmd-validate)***
1 つ以上のコンポーネントドキュメントの YAML ドキュメント構文を検証するために、**validate**コマンドを実行する。
### awstoe run コマンド
このコマンドは、YAML コンポーネントドキュメントスクリプトを、`--config` パラメータで指定された設定ファイル、または `--documents` パラメータで指定されたコンポーネントドキュメントのリストに含まれている順序で実行します。
**注記**
次のパラメータのうち、1 つのみを正確に指定する必要があります。両方は指定しないでください。
--config
--documents
#### 構文
```
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` パラメータは指定しないでください。入力設定の詳細については、[AWSTOE run コマンドの入力を設定する](toe-run-config-input.md)を参照のこと。
有効な場所は以下のとおり:
+ ローカルファイルパス (*`./config-example.json`*)
+ S3 URI (`s3://bucket/key`)
**--cw-ignore-failures**
ショートフォーム:N/A
CloudWatch Logs からのロギングエラーは無視してください。
**--cw-log-group**
ショートフォーム:N/A
CloudWatch Logs の `LogGroup` の名前。
**--cw-log-region**
ショートフォーム:N/A
CloudWatch Logs に適用される AWS リージョン。
**--cw-log-stream**
ショートフォーム:N/A
`console.log` ファイルのストリーミング AWSTOE 先を指定する CloudWatch Logs `LogStream`の名前。
**--document-s3-bucket-owner**
ショートフォーム:N/A
S3 URI ベースのドキュメントのバケット所有者のアカウントID。
**--documents *`./doc-1.yaml`,`./doc-n.yaml`***
ショートフォーム:-d *`./doc-1.yaml`*,*`./doc-n`*
コンポーネント文書 (条件付き)。このパラメータには、実行する YAML コンポーネントドキュメントのファイルロケーションのカンマ区切りリストが含まれます。`--documents` パラメータを使用して**run**コマンドに YAML ドキュメントを指定する場合、`--config` パラメータを指定してはなりません。
有効な場所は以下のとおり:
+ ローカルファイルパス (*/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).
リスト内の項目間にはスペースがなく、カンマのみが入ります。
**--execution-id**
短縮形： -i
これは現在の **run** コマンドの実行に適用される固有の ID です。この ID は出力ファイル名とログファイル名に含まれ、これらのファイルを一意に識別し、現在のコマンド実行にリンクします。この設定を省略すると、 は GUID AWSTOE を生成します。
**--log-directory**
短縮形： -l
がこのコマンド実行のすべてのログファイル AWSTOE を保存する送信先ディレクトリ。デフォルトでは、このディレクトリは親ディレクトリ `TOE__` の中にあります。ログディレクトリを指定しない場合、 は現在の作業ディレクトリ () AWSTOE を使用します`.`。
**--log-s3-bucket-name**
短縮形： -b
コンポーネントログが Amazon S3 に保存されている場合 (推奨）、 はこのパラメータで という名前の S3 バケットにコンポーネントアプリケーションログ AWSTOE をアップロードします。
**--log-s3-bucket-owner**
ショートフォーム:N/A
コンポーネントログが Amazon S3 に保存されている場合 (推奨）、これは がログファイルを AWSTOE 書き込むバケットの所有者アカウント ID です。
**--log-s3-key-prefix**
短縮形： -k
コンポーネントログが Amazon S3 に保存されている場合（推奨）、これはバケット内のログの場所を示す S3 オブジェクトキーのプレフィックスです。
**--parameters *name1*=*value1*,*name2*=*value2*...**
ショートフォーム:N/A
パラメータは、コンポーネントドキュメントで定義される変更可能な変数であり、呼び出し元のアプリケーションが実行時に提供できる設定を持つ。
**--phases**
ショートフォーム:-p
YAML コンポーネントドキュメントから実行するフェーズを指定するカンマ区切りのリスト。コンポーネントドキュメントに追加のフェーズが含まれている場合、そのフェーズは実行されません。
**--state-directory**
短縮形： -s
状態追跡ファイルが保存されているファイルパス。
**--version**
短縮形： -v
コンポーネントアプリケーションのバージョンを指定します。オプション
**--help**
短縮形： -h
コンポーネント管理アプリケーションオプションを使用するためのヘルプマニュアルを表示します。
**--trace**
短縮形： -t
コンソールへの冗長ロギングを有効にする。
### awstoe 検証コマンド
このコマンドを実行すると、`--documents` パラメータで指定された各コンポーネントドキュメントの YAML ドキュメント構文が検証されます。
#### 構文
```
awstoe validate [--document-s3-bucket-owner ]
--documents [--help] [--trace]
```
#### パラメータとオプション
パラメータ
**--document-s3-bucket-owner**
ショートフォーム:N/A
S3 URI ベースのドキュメントのソースアカウント ID が提供されました。
**--documents *`./doc-1.yaml`,`./doc-n.yaml`***
ショートフォーム:-d *`./doc-1.yaml`*,*`./doc-n`*
コンポーネントのドキュメント (必須)。このパラメータには、実行する YAML コンポーネントドキュメントのファイルロケーションのカンマ区切りリストが含まれます。有効な場所は以下のとおり:
+ ローカルファイルパス (*./component-doc-example.yaml*)
+ S3 URI (`s3://bucket/key`)
+ Image Builder コンポーネントビルドバージョン ARNs (arn:aws:imagebuilder:us-west-*2:123456789012*:component/*my-example-component*/2021.12.02/1)
リスト内の項目間にはスペースがなく、カンマのみが入ります。オプション
**--help**
短縮形： -h
コンポーネント管理アプリケーションオプションを使用するためのヘルプマニュアルを表示します。
**--trace**
短縮形： -t
コンソールへの冗長ロギングを有効にする。
# を使用してカスタムコンポーネントを開発するための手動セットアップ AWSTOE
AWS Task Orchestrator and Executor （AWSTOE) アプリケーションは、コンポーネント定義フレームワーク内でコマンドを作成、検証、実行するスタンドアロンアプリケーションです。 AWS のサービスでは、 AWSTOE を使用してワークフローのオーケストレーション、ソフトウェアのインストール、システム設定の変更、イメージビルドのテストを行うことができます。
AWSTOE アプリケーションを手動でインストールし、カスタムコンポーネントを開発するためのスタンドアロンアプリケーションとして使用するには、次の手順に従います。Image Builder コンソールまたは AWS CLI コマンドを使用してカスタムコンポーネントを作成する場合、Image Builder はこれらのステップを自動的に処理します。詳細については、「[Image Builder を使用したカスタムコンポーネントの作成](create-component.md)」を参照してください。
# AWSTOE インストールダウンロードの署名を確認する
このセクションでは、Linux、macOS、Windows ベースのオペレーティングシステム AWSTOE での のインストールダウンロードの有効性を検証するための推奨プロセスについて説明します。
**Topics**
+ [Linux または macOS で AWSTOE のインストールダウンロードの署名を検証する](#awstoe-verify-sig-linux)
+ [Windows で AWSTOE のインストールダウンロードの署名を確認する](#awstoe-verify-sig-win)
## Linux または macOS で AWSTOE のインストールダウンロードの署名を検証する
このトピックでは、Linux ベースまたは macOS オペレーティングシステム AWSTOE での のインストールダウンロードの有効性を検証するための推奨プロセスについて説明します。
インターネットからアプリケーションをダウンロードする際は、必ずソフトウェアパブリッシャーの身元を認証することをお勧めします。また、アプリケーションが公開されてから変更または破損していないことを確認してください。これにより、ウイルスやマルウェアに感染したバージョンのアプリケーションをインストールせずに済みます。
このトピックのステップを実行した後に AWSTOE アプリケーションのソフトウェアが変更されているか破損していることが判明した場合は、インストールファイルを実行しないでください。代わりに、 サポート にお問い合わせください。サポートオプションの詳細については、「」を参照してください[サポート](https://aws.amazon.com/premiumsupport/)。
AWSTOE 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/) を参照してください。
まず、ソフトウェア発行元との信頼を確立します。ソフトウェア発行元のパブリックキーをダウンロードし、キー所有者が一致していることを確認してから、*キーリング*に追加します。キーリングとは、既知のパブリックキーの集合です。真正性が確立されたパブリック キーは、アプリケーションの署名を確認するために使用できます。
**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
```
------
### パブリック キーの認証とインポート
プロセスの次のステップでは、 AWSTOE パブリックキーを認証し、`GPG`キーリングに信頼されたキーとして追加します。
**AWSTOE パブリックキーを認証してインポートするには**
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** を保存したディレクトリのコマンドプロンプトで、次のコマンドを使用して AWSTOE パブリックキーをキーリングにインポートします。
```
gpg --import awstoe.gpg
```
コマンドで次のような結果が返されます。
```
gpg: key F5AEBC52: public key "AWSTOE " imported
gpg: Total number processed: 1
gpg: imported: 1 (RSA: 1)
```
次のステップで必要になるため、キーの値を書きとめておきます。前述の例では、キーの値は `F5AEBC52` です。
1. 次のコマンドを使用してフィンガープリントを確認し、*キー値*を前述の手順の値と置き換えます。
```
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`」になります。返されたキー フィンガープリントをこのページで公開されているものと比較します。これらは一致するはずです。一致しない場合は、 AWSTOE インストールスクリプトをインストールせず、 にお問い合わせください サポート。
### パッケージの署名の確認
`GPG` ツールをインストール後、 AWSTOE パブリックキーを認証してインポートし、そのパブリック キーが信頼済みであることを確認すると、インストールスクリプトの署名を確認できるようになります。
**インストールスクリプトの署名を確認するには**
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. 保存したディレクトリのコマンドプロンプト`awstoe.sig`と AWSTOE インストールファイルで次のコマンドを実行して、署名を検証します。ファイルが2つとも存在している必要があります。
```
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 "`」という句が含まれる場合は、署名が正常に確認されており、 AWSTOE のインストールスクリプトを実行できることを意味しています。
出力結果に「`BAD signature`」という句が含まれる場合、手順が正しいことをもう一度確認してください。この応答が続く場合は、 サポートに連絡してください。以前にダウンロードしたインストール ファイルを実行しないでください。
以下は、表示される可能性のある警告の詳細です。
+ 警告: このキーは、信頼済みの署名で認定されていません\$1 署名が所有者に属していることが確認できません。 AWS オフィスを訪問し、直接キーを受け取るのが理想的です。しかし、キーは多くの場合ウェブサイトからダウンロードされます。この場合、ウェブサイトは AWS ウェブサイトです。
+ **gpg: 最終的に信用されたキーが見つかりません。**これは、特定のキーがユーザー (またはユーザーが信頼する他のユーザー) によって「最終的に信頼された」キーでないことを意味します。
詳細については、「[http://www.gnupg.org](http://www.gnupg.org)」を参照してください。
## Windows で AWSTOE のインストールダウンロードの署名を確認する
このトピックでは、Windows ベースのオペレーティングシステム上の AWS Task Orchestrator and Executor アプリケーションのインストールファイルの有効性を検証するための推奨プロセスについて説明します。
インターネットからアプリケーションをダウンロードする場合は、常にソフトウェア発行元のアイデンティティを認証し、アプリケーションの発行後に改ざん、あるいは破損がないか確認することをお勧めします。これにより、ウイルスやマルウェアに感染したバージョンのアプリケーションをインストールせずに済みます。
このトピックのステップを実行した後に AWSTOE アプリケーションのソフトウェアが変更されているか破損していることが判明した場合は、インストールファイルを実行しないでください。代わりに、 にお問い合わせください サポート。
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` を右クリックして、**プロパティ**ウィンドウを開きます。
1. **デジタル署名**タブを選択します。
1. [**Signature List**] で [**Amazon Services LLC**] を選択し、[**Details**] をクリックします。
1. すでに選択していない場合は **一般**タブにアクセスし、**証明書の表示** を選びます。
1. **詳細** タブを選択し、まだの場合は **すべて**を**表示** のドロップダウンリストで選択します。
1. **拇印** フィールドが表示されるまでスクロールして、**拇印** を選択します。下のウィンドウにサムプリントの値全体が表示されます。
+ 下のウィンドウのサムプリントの値が次の値と等しい場合、
**9D CA 72 17 DA FF B8 2F E4 C4 67 77 36 2F A4 AA C9 08 82 15**
ダウンロードした AWSTOE バイナリは本物であり、安全にインストールできます。
+ 下部の詳細ウィンドウのサムプリントの値が上記の値と等しくない場合には、`awstoe.exe` を実行しないでください。
**Topics**
+ [AWSTOE インストールダウンロードの署名を確認する](awstoe-verify-sig.md)
+ [ステップ 1: をインストールする AWSTOE](#toe-start-install)
+ [ステップ 2: AWS 認証情報を設定する](#toe-start-credentials)
+ [ステップ 3: コンポーネントドキュメントをローカルで開発する](#toe-start-develop)
+ [ステップ 4: AWSTOE コンポーネントを検証する](#toe-start-validate)
+ [ステップ 5: AWSTOE コンポーネントを実行する](#toe-start-run)
## ステップ 1: をインストールする AWSTOE
コンポーネントをローカルで開発するには、 AWSTOE アプリケーションをダウンロードしてインストールします。
1.
**AWSTOE アプリケーションをダウンロードする**
インストールするには AWSTOE、アーキテクチャとプラットフォームに適したダウンロードリンクを選択します。アプリケーションのダウンロードリンクの詳細なリストについては、「[AWSTOE ダウンロード](toe-component-manager.md#toe-downloads)」を参照してください。
**重要**
AWS は TLS バージョン 1.0 および 1.1 のサポートを段階的に廃止しています。 AWSTOE ダウンロード用に S3 バケットにアクセスするには、クライアントソフトウェアで TLS バージョン 1.2 以降を使用する必要があります。詳細については、[AWS セキュリティのブログ記事](https://aws.amazon.com/blogs/security/tls-1-2-required-for-aws-endpoints/)を参照してください。
1.
**署名を検証する**
ダウンロードを検証する手順は、インストール後に AWSTOE アプリケーションを実行するサーバープラットフォームによって異なります。Linux サーバーでダウンロードを確認する方法については、「[Linux または macOS での署名の検証](awstoe-verify-sig.md#awstoe-verify-sig-linux)」を参照してください。Windows サーバーでダウンロードを確認する方法については、「[Windows で署名を検証する](awstoe-verify-sig.md#awstoe-verify-sig-win)」を参照してください。
**注記**
AWSTOE は、ダウンロード場所から直接呼び出されます。別途インストールを行う必要はありません。つまり、 はローカル環境を変更 AWSTOE することもできます。
コンポーネント開発中に変更を確実に分離するには、EC2 インスタンスを使用して AWSTOE コンポーネントを開発およびテストすることをお勧めします。
## ステップ 2: AWS 認証情報を設定する
AWSTOE では AWS のサービス、次のようなタスクを実行するときに、Amazon S3 や Amazon CloudWatch などの他の に接続するための AWS 認証情報が必要です。
+ ユーザー提供の Amazon S3 パスから AWSTOE ドキュメントをダウンロードします。
+ `S3Download` または `S3Upload` アクションモジュールを実行する。
+ CloudWatch にログをストリーミングします (有効になっている場合)。
EC2 インスタンス AWSTOE で実行している場合、 の実行は EC2 インスタンスにアタッチされた IAM ロールと同じアクセス許可 AWSTOE を使用します。
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
```
Windows で PowerShell を使ってこれらの変数を設定するには、`$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 ドキュメントを使用して作成されます。ドキュメントの構文については[カスタム AWSTOE コンポーネントのコンポーネントドキュメントフレームワークを使用する](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: AWSTOE コンポーネントを検証する
アプリケーションの AWSTOE コンポーネント構文を AWSTOE ローカルで検証できます。次の例は、コンポーネントを実行せずに構文を検証するための AWSTOE アプリケーション`validate`コマンドを示しています。
**注記**
AWSTOE アプリケーションは、現在のオペレーティングシステムのコンポーネント構文のみを検証できます。例えば、`awstoe.exe` を Windows で実行している場合、`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: AWSTOE コンポーネントを実行する
AWSTOE アプリケーションは、`--phases`コマンドライン引数を使用して、指定されたドキュメントの 1 つ以上のフェーズを実行できます。`--phases`でサポートされている値は`build`、`validate`、`test`です。複数のフェーズ値をカンマで区切って入力できます。
フェーズのリストを指定すると、 AWSTOE アプリケーションは各ドキュメントの指定されたフェーズを順番に実行します。たとえば、 は の `build`および `validate`フェーズ AWSTOE を実行し`document1.yaml`、その後に の `build`および `validate`フェーズを実行します`document2.yaml`。
ログを安全に保存し、トラブルシューティングのために保持するには、Amazon S3 にログストレージを設定することをお勧めします。Image Builder では、ログを発行するための Amazon S3 の場所はインフラストラクチャ設定で指定されます。インフラ構成の詳細については、[Image Builder インフラストラクチャ設定の管理](manage-infra-config.md)を参照。
フェーズのリストが指定されていない場合、 AWSTOE アプリケーションは YAML ドキュメントに記載されている順序ですべてのフェーズを実行します。
1 つまたは複数のドキュメントで特定のフェーズを実行するには、以下のコマンドを使用します。
単一フェーズ
```
awstoe run --documents hello-world.yml --phases build
```
複数フェーズ
```
awstoe run --documents hello-world.yml --phases build,test
```
**ドキュメント実行**
1 つのドキュメントですべてのフェーズを実行
```
awstoe run --documents documentName.yaml
```
複数のドキュメントで全フェーズを実行
```
awstoe run --documents documentName1.yaml,documentName2.yaml
```
Amazon S3 情報を入力して、ユーザー定義のローカルパスから AWSTOE ログをアップロードする (推奨）
```
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
```
1 つのドキュメントですべてのフェーズを実行し、すべてのログをコンソールに表示する
```
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
```
のヘルプを取得する AWSTOE
```
awstoe --help
```
# カスタム 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 は、失敗した反復の出力を統合しません。
# AWSTOE コンポーネントマネージャーでサポートされるアクションモジュール
EC2 Image Builder などのイメージ構築サービスは、 AWSTOE アクションモジュールを使用して、カスタマイズされたマシンイメージの構築とテストに使用される EC2 インスタンスの設定に役立ちます。このセクションでは、一般的に使用される AWSTOE アクションモジュールの機能と、それらの設定方法について説明します。
コンポーネントは、プレーンテキストの YAML ドキュメントを使用して作成されます。ドキュメントの構文については[カスタム AWSTOE コンポーネントのコンポーネントドキュメントフレームワークを使用する](toe-use-documents.md)を参照。
**注記**
すべてのアクションモジュールは、Linux の `root` と Windows の `NT Authority\SYSTEM` の両方で、実行時に Systems Manager エージェントと同じアカウントを使用します。
以下のクロスリファレンスは、実行されるアクションのタイプ別にアクションモジュールを分類したものです。
**一般実行**
+ [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)
**システムアクション**
+ [Reboot (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**
| キー名 | 説明 | タイプ | 必須 |
| --- | --- | --- | --- |
| input | 比較演算子または論理演算子を 1 つ含みます。論理演算子には複数の比較演算子を含めることができます。 | 演算子に応じて可変 | はい |
**入力の例: `stringEquals` 比較演算子を使用した単純な比較**
この例は `true` に評価されます。
```
- name: StringComparison
action: Assert
inputs:
stringEquals: '2.1.1'
value: '{{ validate.ApplicationVersion.outputs.stdout }}'
```
**入力の例: `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'
```
**入力例: 論理演算子と連鎖変数を使用してネストされた比較**
次の例は、連鎖変数との比較を使用する論理演算子を含む、ネストされた比較を示しています。`Assert` は、次のいずれかが true の場合に `true` に評価されます。
+ `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** アクションモジュールを使用すると、インラインシェルコード/コマンドで bash スクリプトを実行できます。このモジュールは Linux をサポートします。
コマンドブロックで指定したすべてのコマンドと命令はファイル (例:`input.sh`) に変換され、bash シェルで実行されます。シェルファイルを実行した結果がステップの終了コードです。
**ExecuteBash** モジュールは、スクリプトが終了コード `194` で終了した場合、システムの再起動を処理します。起動すると、アプリケーションは以下のいずれかのアクションを実行します。
+ Systems Manager エージェントによって実行された場合、アプリケーションは終了コードを呼び出し側に渡します。Systems Manager エージェント はシステムの再起動を処理し、「[スクリプトからのマネージドインスタンスの再起動](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html)」で説明されているように、再起動を開始したのと同じステップを実行します。
+ アプリケーションは現在の `executionstate` を保存し、アプリケーションを再実行するための再起動トリガーを設定し、システムを再起動します。
システムの再起動後、アプリケーションは再起動を開始したのと同じステップを実行します。この機能が必要な場合は、同じシェルコマンドを複数回呼び出しても処理できる同等のスクリプトを記述する必要があります。
**Input**
| キー名 | 説明 | タイプ | 必須 |
| --- | --- | --- | --- |
| 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**
| フィールド | 説明 | タイプ |
| --- | --- | --- |
| stdout | コマンド実行の標準出力。 | string |
再起動を開始し、`194` アクションモジュールの一部として終了コードを返すと、再起動を開始したのと同じアクションモジュールステップでビルドが再開されます。終了コードなしで再起動を開始すると、ビルドプロセスが失敗する可能性があります。
**出力例: 再起動前 (初めてドキュメントから)**
```
{
“stdout”: “The reboot file does not exist. Creating it and triggering a restart."
}
```
**出力例: 再起動後 (2 回目にドキュメントを通過)**
```
{
“stdout”: “The reboot file exists. Deleting it and exiting with success."
}
```
### ExecuteBinary (Linux、Windows、macOS)
**ExecuteBinary** アクションモジュールを使うと、コマンドライン引数のリストを使ってバイナリファイルを実行することができます。
**ExecuteBinary** モジュールは、バイナリファイルが終了コード `194` (Linux) または `3010` (Windows) で終了した場合にシステムの再起動を処理します。この場合、アプリケーションは以下のいずれかのアクションを実行する：
+ Systems Manager エージェントによって実行された場合、アプリケーションは終了コードを呼び出し側に渡します。Systems Manager エージェントはシステムの再起動を処理し、[スクリプトから管理対象インスタンスを再起動する](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html)で説明したように、再起動を開始したのと同じステップを実行します。
+ アプリケーションは現在の `executionstate` を保存し、アプリケーションを再実行するための再起動トリガーを設定し、システムを再起動します。
システムの再起動後、アプリケーションは再起動を開始したのと同じステップを実行します。この機能が必要な場合は、同じシェルコマンドを複数回呼び出しても処理できる同等のスクリプトを記述する必要があります。
**Input**
| キー名 | 説明 | タイプ | 必須 |
| --- | --- | --- | --- |
| path | 実行用のバイナリファイルへのパス。 | String | はい |
| arguments | バイナリの実行時に使用するコマンドライン引数のリストが含まれています。 | 文字列リスト | いいえ |
**入力例:.NET のインストール**
```
- name: "InstallDotnet"
action: ExecuteBinary
inputs:
path: C:\PathTo\dotnet_installer.exe
arguments:
- /qb
- /norestart
```
**Output**
| フィールド | 説明 | タイプ |
| --- | --- | --- |
| stdout | コマンド実行の標準出力。 | string |
**出力例**
```
{
"stdout": "success"
}
```
### ExecuteDocument (Linux、Windows、macOS)
**ExecuteDocument** アクションモジュールは、ネストされたコンポーネントドキュメントをサポートし、1 つのドキュメントから複数のコンポーネントドキュメントを実行できるようにします。 AWSTOE 実行時に入力パラメータで渡されたドキュメントを検証します。
**制限事項**
+ このアクションモジュールは 1 回だけ実行され、再試行はできません。また、タイムアウト制限を設定するオプションもありません。**ExecuteDocument** は次のデフォルト値を設定し、変更しようとするとエラーを返します。
+ `timeoutSeconds`:-1
+ `maxAttempts`: 1
**注記**
これらの値は空白のままにしておくと、 はデフォルト値 AWSTOE を使用します。
+ 文書のネストは最大 3 レベルまで可能ですが、それ以上はできません。最上位レベルはネストされていないため、3 レベルのネストは 4 つのドキュメントレベルに相当します。このシナリオでは、最下位の文書は他の文書を呼んではならない。
+ コンポーネントドキュメントを繰り返し実行することはできません。ループ構造の外部で自身を呼び出したり、現在の実行チェーンの上位にある別のドキュメントを呼び出したりするドキュメントは、サイクルを開始して無限ループに陥る可能性があります。 AWSTOE は周期的な実行を検出すると、実行を停止し、失敗を記録します。
![\[ExecuteDocument アクションモジュールのネストレベルの制限。\]](http://docs.aws.amazon.com/ja_jp/imagebuilder/latest/userguide/images/toe-component-document-nesting.png)
コンポーネントドキュメント自体を実行しようとしたり、現在の実行チェーンで上位にあるコンポーネントドキュメントを実行しようとしたりすると、実行は失敗します。
**Input** (入力)
| キー名 | 説明 | タイプ | 必須 |
| --- | --- | --- | --- |
| document | コンポーネントドキュメントのパス。有効なオペレーションは以下のとおりです。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/imagebuilder/latest/userguide/toe-action-modules.html) | String | はい |
| document-s3-bucket-owner | コンポーネントドキュメントが保存されている S3 バケットの S3 バケット所有者のアカウント ID。*(コンポーネントドキュメントで S3 URI を使用している場合にお勧めです。)* | String | いいえ |
| phases | コンポーネントドキュメントで実行するフェーズ。カンマ区切りのリストで指定します。フェーズが指定されていない場合は、すべてのフェーズが実行されます。 | String | いいえ |
| parameters | 実行時にキーと値のペアとしてコンポーネントドキュメントに渡される入力パラメータ。 | パラメータマップリスト | いいえ |
**パラメータマップ入力**
| キー名 | 説明 | タイプ | 必須 |
| --- | --- | --- | --- |
| 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**
AWSTOE は、実行される`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":""
+ "status":"success"
**出力例**
次の例は、ネストされた実行が発生した場合の **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** アクションモジュールを使用すると、インラインシェルコード/コマンドを使用して PowerShell スクリプトを実行できます。このモジュールは Windows プラットフォームと Windows PowerShell をサポートしています。
コマンドブロックで指定されたすべてのコマンド/命令は、スクリプトファイル（例えば、`input.ps1`）に変換され、Windows PowerShell を使用して実行されます。シェルファイルを実行した結果が終了コードです。
**ExecutePowerShell** モジュールは、シェルコマンドが終了コードが `3010` で終了した場合、システムの再起動を処理します。起動すると、アプリケーションは以下のいずれかのアクションを実行します。
+ Systems Manager エージェントによって実行された場合、終了コードを呼び出し側に渡します。Systems Manager エージェント はシステムの再起動を処理し、「[スクリプトからのマネージドインスタンスの再起動](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html)」で説明されているように、再起動を開始したのと同じステップを実行します。
+ 現在の `executionstate` を保存し、アプリケーションを再実行するための再起動トリガーを設定し、システムを再起動します。
システムの再起動後、アプリケーションは再起動を開始したのと同じステップを実行します。この機能が必要な場合は、同じシェルコマンドを複数回呼び出しても処理できる同等のスクリプトを記述する必要があります。
**Input**
| キー名 | 説明 | タイプ | 必須 |
| --- | --- | --- | --- |
| 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**
| フィールド | 説明 | タイプ |
| --- | --- | --- |
| stdout | コマンド実行の標準出力。 | string |
アクションモジュールの一部として再起動を実行して終了コード `3010` を返した場合、ビルドは再起動を開始したのと同じアクションモジュールステップで再開されます。終了コードを指定せずに再起動を実行すると、ビルドプロセスが失敗する可能性があります。
**出力例: 再起動前 (初めてドキュメントから)**
```
{
“stdout”: “The reboot file does not exist. Creating it and triggering a restart."
}
```
**出力例: 再起動後 (2 回目にドキュメントを通過)**
```
{
“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**
| キー | 説明 | タイプ | [Required] (必須) | [Default] (デフォルト) |
| --- | --- | --- | --- | --- |
| `source` | ダウンロードのソースである Amazon S3 バケット。特定のオブジェクトへのパスを指定するか、またはキー接頭辞 (末尾がスラッシュ) で終わり、アスタリスクワイルドカード (`/*`) が続くものを使用して、キー接頭辞 に一致するオブジェクトのセットをダウンロードできます。 | String | はい | 該当なし |
| `destination` | Amazon S3 オブジェクトがダウンロードされるローカルパス。1 つのファイルをダウンロードするには、パスの一部としてファイル名を指定する必要があります。例えば、`/myfolder/package.zip`。 | String | はい | 該当なし |
| `expectedBucketOwner` | `source` パスで指定されたバケットの必要な所有者アカウント ID。ソースで指定されている Amazon S3 バケットの所有権を確認することをお勧めします。 | String | いいえ | 該当なし |
| `overwrite` | true に設定すると、指定したローカルパスの宛先フォルダに同じ名前のファイルが既に存在する場合、ダウンロードファイルはローカルファイルを上書きします。false に設定すると、ローカルシステム上の既存のファイルは上書きされないよう保護され、アクションモジュールはダウンロードエラーで失敗します。 例: `Error: S3Download: File already exists and "overwrite" property for "destination" file is set to false. Cannot download.` | ブール値 | なし | 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**
| キー | 説明 | タイプ | [Required] (必須) | [Default] (デフォルト) |
| --- | --- | --- | --- | --- |
| `source` | ソースファイル/フォルダの生成元のローカルパス。`source` はアスタリスクワイルドカード (`*`) をサポートします。 | String | はい | 該当なし |
| `destination` | ソースファイル/フォルダがアップロードされる宛先 Amazon S3 バケットのパス。 | String | はい | 該当なし |
| `recurse` | `true` に設定すると、**S3Upload** を再帰的に実行します。 | String | いいえ | `false` |
| `expectedBucketOwner` | 宛先パスで指定されている Amazon S3 バケットの予想所有者アカウント ID。宛先に指定された Amazon S3 バケットの所有権を確認することをお勧めします。 | String | いいえ | 該当なし |
**入力例: ローカルファイルを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` ドキュメントフィールドで指定されている試行とは異なります。
このアクションモジュールは暗黙的にリダイレクトを処理します。`200` を除く、すべての HTTP ステータスコードはエラーになります。
**Input**
| キー名 | 説明 | タイプ | [Required] (必須) | [Default] (デフォルト) |
| --- | --- | --- | --- | --- |
| source | RFC 3986 標準に準拠した有効な HTTP/HTTPS URL (HTTPS を推奨)。式を連鎖させることは許可されます。 | String | はい | 該当なし |
| destination | ローカルシステム上のファイルまたはフォルダの絶対パスまたは相対パス。フォルダパスは / で終わる必要があります。末尾が / でなければ、ファイルパスとして扱われます。モジュールは、ダウンロードを成功させるために必要なファイルまたはフォルダを作成します。式を連鎖させることは許可されます。 | String | はい | 該当なし |
| overwrite | 有効にすると、ローカルシステム上の既存のファイルを、ダウンロードしたファイルまたはリソースで上書きします。有効にしないと、ローカルシステム上の既存のファイルは上書きされず、アクションモジュールはエラーで失敗します。上書きが有効で、チェックサムとアルゴリズムが指定されている場合、アクションモジュールは、既存のファイルのチェックサムとハッシュが一致しない場合にのみファイルをダウンロードします。 | ブール値 | いいえ | true |
| checksum | チェックサムを指定すると、指定されたアルゴリズムで生成されたダウンロードファイルのハッシュと照合されます。ファイル検証を有効にするには、チェックサムとアルゴリズムの両方を指定する必要があります。式を連鎖させることは許可されます。 | String | いいえ | 該当なし |
| algorithm | チェックサムの計算に使用するアルゴリズム。オプションには MD5、SHA1、SHA256 および SHA512 があります。ファイル検証を有効にするには、チェックサムとアルゴリズムの両方を指定する必要があります。式を連鎖させることは許可されます。 | String | いいえ | 該当なし |
| ignoreCertificateErrors | SSL 証明書の検証は有効になっていると無視されます。 | ブール値 | いいえ | false |
**Output**
| キー名 | 説明 | タイプ |
| --- | --- | --- |
| 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"
}
```
**入力例: ローカル宛先を上書きせずにリモートファイルを 1 つダウンロードし、ファイル検証を行って別のリモートファイルをダウンロードする**
```
- 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**
| キー名 | 説明 | タイプ | 必須 | デフォルトの値 | 許容値 | すべてのプラットフォームでサポートされています |
| --- | --- | --- | --- | --- | --- | --- |
| path | ファイルパス。 | String | はい | 該当なし | 該当なし | はい |
| content | ファイルに追加するコンテンツ。 | String | いいえ | 空の文字列 | 該当なし | はい |
| encoding | エンコード形式です。 | String | いいえ | utf8 | utf8、utf-8、utf16、utf-16、utf16-LE、utf-16-LE、utf16-BE、utf-16-BE、utf32、utf-32、utf32-LE、utf-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**
| キー名 | 説明 | タイプ | 必須 | デフォルトの値 | 許容値 | すべてのプラットフォームでサポートされています |
| --- | --- | --- | --- | --- | --- | --- |
| source | ソースファイルのパス。 | String | はい | 該当なし | 該当なし | はい |
| destination | デスティネーションファイルパス。 | String | はい | 該当なし | 該当なし | はい |
| overwrite | false に設定すると、指定した場所に指定した名前のファイルが既にある場合でも、宛先ファイルは置き換えられません。 | ブール値 | いいえ | true | 該当なし | はい |
**入力例: ファイルのコピー (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** アクションモジュールは、指定されたソースから指定された宛先にフォルダをコピーします。`destination` オプションの入力はコピーするフォルダであり、`source` オプションの入力はソースフォルダの内容をコピーするフォルダです。デフォルトでは、実行時に宛先フォルダが存在しない場合、モジュールは再帰的に宛先フォルダを作成します。
指定されたフォルダ内に指定された名前のフォルダが既に存在する場合、アクションモジュールは、デフォルトで、既存のフォルダを上書きします。上書きオプションを`false`に設定することで、このデフォルトの動作を上書きすることができます。上書きオプションが `false` に設定されていて、指定した場所に指定した名前のフォルダが既に存在する場合、アクションモジュールはエラーを返します。
ソースフォルダ名にはワイルドカード (`*`) を含めることができます。ワイルドカード文字は、最後のファイルパスの区切り文字 (`/` または `\`) の後でのみ使用できます。コピー元フォルダ名にワイルドカード文字が含まれている場合、ワイルドカードに一致するすべてのフォルダがコピー先フォルダにコピーされます。ワイルドカード文字を使用して複数のフォルダをコピーする場合、`destination` オプションへの入力は、コピー先の入力がフォルダであることを示すファイルパス区切り記号 (`/` または `\`) で終わる必要があります。
コピー先フォルダ名がソースフォルダ名と異なる場合は、`destination` オプションを使用してコピー先フォルダ名を指定できます。宛先フォルダ名を指定しない場合、ソースフォルダの名前が宛先フォルダの作成に使用されます。最後のファイルパスの区切り文字 (`/` または `\`) に続くテキストはすべてフォルダ名として扱われます。ソースフォルダと同じフォルダ名を使用する場合は、`destination` オプションの入力がファイルパスの区切り文字 (`/` または `\`) で終わる必要があります。
アクションモジュールは、以下の場合にエラーを返します。
+ 指定されたフォルダにフォルダを作成する権限がありません。
+ ソースフォルダは実行時には存在しません。
+ 指定したフォルダ名のフォルダが既に存在し、`overwrite` オプションは `false` に設定されています。
+ 操作の実行中にアクションモジュールがエラーに遭遇しました。
**Input**
| キー名 | 説明 | タイプ | 必須 | デフォルトの値 | 許容値 | すべてのプラットフォームでサポートされています |
| --- | --- | --- | --- | --- | --- | --- |
| source | ソースフォルダのパス。 | String | はい | 該当なし | 該当なし | はい |
| destination | 宛先フォルダのパス。 | String | はい | 該当なし | 該当なし | はい |
| overwrite | false に設定すると、指定された場所に指定された名前のフォルダが既にある場合、保存先フォルダは置き換えられません。 | ブール値 | いいえ | true | 該当なし | はい |
**入力例: フォルダのコピー (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`、`group` と `permissions` オプションが使用されている場合、このアクションモジュールは検証してエラーを返します。
このアクションモジュールは、オペレーティングシステムのデフォルト `umask` 値で定義されたパーミッションを持つファイルを作成することができます。デフォルト値をオーバーライドする場合、`umask` 値を設定する必要があります。
アクションモジュールは、以下の場合にエラーを返します。
+ 指定された親フォルダにファイルまたはフォルダを作成する権限がありません。
+ 操作の実行中にアクションモジュールがエラーに遭遇しました。
**Input**
| キー名 | 説明 | タイプ | 必須 | デフォルトの値 | 許容値 | すべてのプラットフォームでサポートされています |
| --- | --- | --- | --- | --- | --- | --- |
| path | ファイルパス。 | String | はい | 該当なし | 該当なし | はい |
| content | ファイルのテキストコンテンツ。 | String | いいえ | 該当なし | 該当なし | はい |
| encoding | エンコード形式です。 | String | いいえ | utf8 | utf8、utf-8、utf16、utf-16、utf16-LE、utf-16-LE、utf16-BE、utf-16-BE、utf32、utf-32、utf32-LE、utf-32-LE、utf32-BEおよび utf-32-BE。エンコーディングオプションの値は大文字と小文字を区別しません。 | はい |
| owner | ユーザー名または ID。 | String | いいえ | 該当なし | 該当なし | Windows ではサポートされていません。 |
| group | グループ名または ID。 | String | いいえ | 現在のユーザー。 | 該当なし | Windows ではサポートされていません。 |
| permissions | ファイルのパーミッション。 | String | いいえ | 0666 | 該当なし | Windows ではサポートされていません。 |
| overwrite | 指定したファイルの名前が既に存在する場合、この値を false に設定すると、デフォルトでファイルが切り捨てられたり上書きされたりするのを防ぐことができます。 | ブール値 | いいえ | true | 該当なし | はい |
**入力例: 上書きせずにファイルを作成 (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`、`group` と `permissions` オプションが使用されている場合、このアクションモジュールは検証してエラーを返します。
このアクションモジュールは、`umask` オペレーティングシステムのデフォルト値で定義された権限を持つフォルダを作成できます。デフォルト値をオーバーライドする場合、`umask` 値を設定する必要があります。
アクションモジュールは、以下の場合にエラーを返します。
+ 指定された場所にフォルダを作成する権限がありません。
+ 操作の実行中にアクションモジュールがエラーに遭遇しました。
**Input**
| キー名 | 説明 | タイプ | 必須 | デフォルトの値 | 許容値 | すべてのプラットフォームでサポートされています |
| --- | --- | --- | --- | --- | --- | --- |
| path | フォルダパス。 | String | はい | 該当なし | 該当なし | はい |
| owner | ユーザー名または ID。 | String | いいえ | 現在のユーザー。 | 該当なし | Windows ではサポートされていません。 |
| group | グループ名または ID。 | String | いいえ | 現在のユーザーのグループ。 | 該当なし | Windows ではサポートされていません。 |
| permissions | フォルダのパーミッション。 | String | いいえ | 0777 | 該当なし | Windows ではサポートされていません。 |
| overwrite | 指定したファイルの名前が既に存在する場合、この値を false に設定すると、デフォルトでファイルが切り捨てられたり上書きされたりするのを防ぐことができます。 | ブール値 | いいえ | true | 該当なし | はい |
**入力例: フォルダの作成 (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**
| キー名 | 説明 | タイプ | 必須 | デフォルトの値 | 許容値 | すべてのプラットフォームでサポートされています |
| --- | --- | --- | --- | --- | --- | --- |
| path | ファイルパス。 | String | はい | 該当なし | 該当なし | Windows ではサポートされていません。 |
| target | シンボリックリンクが指すターゲットファイルのパス。 | String | はい | 該当なし | 該当なし | Windows ではサポートされていません。 |
| force | 同じ名前のリンクが既に存在する場合、リンクの作成を強制します。 | ブール値 | いいえ | false | 該当なし | 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** アクションモジュールは、指定された場所にある 1 つまたは複数のファイルを削除します。
`path` の入力は、有効なファイルパスか、ファイル名にワイルドカード文字(`*`)を含むファイルパスでなければならない。ファイル名にワイルドカード文字を指定すると、ワイルドカードに一致する同じフォルダ内のすべてのファイルが削除されます。
アクションモジュールは、以下の場合にエラーを返します。
+ あなたには削除操作を実行する権限がありません。
+ 操作の実行中にアクションモジュールがエラーに遭遇しました。
**Input**
| キー名 | 説明 | タイプ | 必須 | デフォルトの値 | 許容値 | すべてのプラットフォームでサポートされています |
| --- | --- | --- | --- | --- | --- | --- |
| path | ファイルパス。 | String | はい | 該当なし | 該当なし | はい |
**入力例: 1 つのファイルを削除する (Linux)**
```
- name: DeletingSingleFileLinux
action: DeleteFile
inputs:
- path: /SampleFolder/MyFolder/Sample.txt
```
**入力例: 1 つのファイルを削除する (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**
| キー名 | 説明 | タイプ | 必須 | デフォルトの値 | 許容値 | すべてのプラットフォームでサポートされています |
| --- | --- | --- | --- | --- | --- | --- |
| path | フォルダパス。 | String | はい | 該当なし | 該当なし | はい |
| force | フォルダが空であろうとなかろうと、フォルダを削除します。 | ブール値 | いいえ | false | 該当なし | はい |
**入力例: `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** アクションモジュールは、指定されたフォルダ内のファイルを一覧表示します。recursive オプションを `true` に設定すると、サブフォルダ内のファイルが一覧表示されます。このモジュールは、デフォルトではサブフォルダ内のファイルを一覧表示しません。
指定したパターンに一致する名前のファイルをすべて一覧表示するには、`fileNamePattern` オプションを使用してパターンを指定します。`fileNamePattern` オプションはワイルドカード (`*`) 値を受け入れます。`fileNamePattern` を指定すると、指定されたファイル名形式に一致するすべてのファイルが返されます。
アクションモジュールは、以下の場合にエラーを返します。
+ 指定されたフォルダが実行時に存在しません。
+ 指定された親フォルダにファイルまたはフォルダを作成する権限がありません。
+ 操作の実行中にアクションモジュールがエラーに遭遇しました。
**Input**
| キー名 | 説明 | タイプ | 必須 | デフォルトの値 | 許容値 | すべてのプラットフォームでサポートされています |
| --- | --- | --- | --- | --- | --- | --- |
| path | フォルダパス。 | String | はい | 該当なし | 該当なし | はい |
| fileNamePattern | 一致するパターンで、そのパターンに一致する名前を持つすべてのファイルを一覧表示します。 | String | いいえ | 該当なし | 該当なし | はい |
| recursive | フォルダ内のファイルを再帰的に一覧表示します。 | ブール値 | いいえ | false | 該当なし | はい |
**入力例: 指定したフォルダ内のファイルを一覧表示する (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**
| キー名 | 説明 | タイプ |
| --- | --- | --- |
| files | ファイルのリストです。 | String |
**出力例**
```
{
"files": "/sample1.txt,/sample2.txt,/sample3.txt"
}
```
### MoveFile (Linux、Windows、macOS)
**MoveFile** アクションモジュールは、指定されたソースから指定された宛先にファイルを移動します。
指定したフォルダーにファイルがすでに存在する場合、アクションモジュールはデフォルトで既存のファイルを上書きします。上書きオプションを`false`に設定することで、このデフォルトの動作を上書きすることができます。上書きオプションが `false` に設定されていて、指定した場所に指定した名前のファイルが既に存在する場合、アクションモジュールはエラーを返します。このオプションは Linux `mv` のコマンドと同じように機能し、デフォルトでは上書きされます。
ソースファイル名にはワイルドカード (`*`) を含めることができます。ワイルドカード文字は、最後のファイルパスの区切り文字 (`/` または `\`) の後でのみ使用できます。ソースファイル名にワイルドカード文字が含まれている場合、ワイルドカードに一致するすべてのファイルが宛先フォルダにコピーされます。ワイルドカード文字を使用して複数のファイルを移動する場合は、`destination` オプションへの入力の末尾にファイルパスの区切り文字 (`/` または `\`) を付ける必要があります。これは、移動先の入力がフォルダであることを示します。
移動先のファイル名がソースファイル名と異なる場合は、`destination` オプションを使用して移動先のファイル名を指定できます。宛先ファイル名を指定しない場合、ソースファイルの名前を使用して宛先ファイルが作成されます。最後のファイルパス区切り文字 (`/` または `\`) に続くテキストはすべてファイル名として扱われます。ソースファイルと同じファイル名を使用する場合は、`destination` オプションの入力がファイルパスの区切り文字 (`/` または `\`) で終わる必要があります。
アクションモジュールは、以下の場合にエラーを返します。
+ 指定されたフォルダにファイルを作成する権限がない。
+ ソースファイルは実行時には存在しません。
+ 指定したファイル名のフォルダが既に存在し、`overwrite` オプションは `false` に設定されています。
+ 操作の実行中にアクションモジュールがエラーに遭遇しました。
**Input**
| キー名 | 説明 | タイプ | 必須 | デフォルトの値 | 許容値 | すべてのプラットフォームでサポートされています |
| --- | --- | --- | --- | --- | --- | --- |
| source | ソースファイルのパス。 | String | はい | 該当なし | 該当なし | はい |
| destination | デスティネーションファイルパス。 | String | はい | 該当なし | 該当なし | はい |
| overwrite | false に設定すると、指定した場所に指定した名前のファイルが既にある場合でも、宛先ファイルは置き換えられません。 | ブール値 | いいえ | true | 該当なし | はい |
**入力例: ファイルを移動する (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**
| キー名 | 説明 | タイプ | 必須 | デフォルトの値 | 許容値 | すべてのプラットフォームでサポートされています |
| --- | --- | --- | --- | --- | --- | --- |
| source | ソースフォルダのパス。 | String | はい | 該当なし | 該当なし | はい |
| destination | 宛先フォルダのパス。 | String | はい | 該当なし | 該当なし | はい |
| overwrite | false に設定すると、指定された場所に指定された名前のフォルダが既にある場合、保存先フォルダは置き換えられません。 | ブール値 | いいえ | true | 該当なし | はい |
**入力例: フォルダの移動 (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**
| キー名 | 説明 | タイプ | 必須 | デフォルトの値 | 許容値 | すべてのプラットフォームでサポートされています |
| --- | --- | --- | --- | --- | --- | --- |
| path | ファイルパス。 | String | はい | 該当なし | 該当なし | はい |
| encoding | エンコード形式です。 | String | いいえ | utf8 | utf8、utf-8、utf16、utf-16、utf16-LE、utf-16-LE、utf16-BE、utf-16-BE、utf32、utf-32、utf32-LE、utf-32-LE、utf32-BEおよび utf-32-BE。エンコーディングオプションの値は大文字と小文字を区別しません。 | はい |
| printFileContent | ファイルの内容を console.log ファイルに出力します。 | ブール値 | いいえ | false | 該当なし | はい。 |
**入力例: ファイルの読み取り (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**
| フィールド | 説明 | タイプ |
| --- | --- | --- |
| content | ファイルの内容。 | string |
**出力例**
```
{
"content" : "The file content"
}
```
### SetFileEncoding (Linux、Windows、macOS)
**SetFileEncoding** アクションモジュールは、既存のファイルのエンコーディングプロパティを変更します。このモジュールは、`utf-8` ファイルのエンコーディングを指定されたエンコーディング標準に変換できます。デフォルトでは、`utf-16` と `utf-32` リトルエンディアンエンディアンエンコーディングと想定されています。
アクションモジュールは、以下の場合にエラーを返します。
+ 指定された変更を実行するにはアクセス許可が必要です。
+ 実行時にファイルが存在しません。
+ 操作の実行中にアクションモジュールがエラーに遭遇しました。
**Input**
| キー名 | 説明 | タイプ | 必須 | デフォルトの値 | 許容値 | すべてのプラットフォームでサポートされています |
| --- | --- | --- | --- | --- | --- | --- |
| path | ファイルパス。 | String | はい | 該当なし | 該当なし | はい |
| encoding | エンコード形式です。 | String | いいえ | utf8 | utf8、utf-8、utf16、utf-16、utf16-LE、utf-16-LE、utf16-BE、utf-16-BE、utf32、utf-32、utf32-LE、utf-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**
| キー名 | 説明 | タイプ | 必須 | デフォルトの値 | 許容値 | すべてのプラットフォームでサポートされています |
| --- | --- | --- | --- | --- | --- | --- |
| path | ファイルパス。 | String | はい | 該当なし | 該当なし | Windows ではサポートされていません。 |
| owner | ユーザー名。 | string | はい | 該当なし | 該当なし | Windows ではサポートされていません。 |
| group | ユーザーグループの名前。 | String | いいえ | ユーザーが所属するグループ名。 | 該当なし | 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**
| キー名 | 説明 | タイプ | 必須 | デフォルトの値 | 許容値 | すべてのプラットフォームでサポートされています |
| --- | --- | --- | --- | --- | --- | --- |
| path | フォルダパス。 | String | はい | 該当なし | 該当なし | Windows ではサポートされていません。 |
| owner | ユーザー名。 | string | はい | 該当なし | 該当なし | Windows ではサポートされていません。 |
| group | ユーザーグループの名前。 | String | いいえ | ユーザーが所属するグループ名。 | 該当なし | Windows ではサポートされていません。 |
| recursive | false に設定すると、フォルダのすべてのコンテンツの所有権を変更するというデフォルトの動作が上書きされます。 | ブール値 | いいえ | true | 該当なし | 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` 値を設定する必要があります。
アクションモジュールは、以下の場合にエラーを返します。
+ 指定された変更を実行するにはアクセス許可が必要です。
+ 実行時にファイルが存在しません。
+ 操作の実行中にアクションモジュールがエラーに遭遇しました。
**Input**
| キー名 | 説明 | タイプ | 必須 | デフォルトの値 | 許容値 | すべてのプラットフォームでサポートされています |
| --- | --- | --- | --- | --- | --- | --- |
| path | ファイルパス。 | String | はい | 該当なし | 該当なし | Windows ではサポートされていません。 |
| permissions | ファイルのパーミッション。 | String | はい | 該当なし | 該当なし | 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**
| キー名 | 説明 | タイプ | 必須 | デフォルトの値 | 許容値 | すべてのプラットフォームでサポートされています |
| --- | --- | --- | --- | --- | --- | --- |
| path | フォルダパス。 | String | はい | 該当なし | 該当なし | Windows ではサポートされていません。 |
| permissions | フォルダのパーミッション。 | String | はい | 該当なし | 該当なし | Windows ではサポートされていません。 |
| recursive | false に設定すると、フォルダのすべての内容の権限を変更するというデフォルトの動作が上書きされます。 | ブール値 | いいえ | true | 該当なし | 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."""'
```
この場合、文字列の中でアポストロフィを使用する必要がある場合は、そのアポストロフィをエスケープする必要があります。つまり、アポストロフィの前に一重引用符 (') をもう 1 つ使うということです。
+ 文字列の外側には二重引用符 (「) を使用して格納できます。また、次の例のように、バックスラッシュ文字 (`\`) を使用して、文字列内の二重引用符をエスケープできます。
```
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、またはウェブ URL を使用して MSI ファイルを指定できます。再起動オプションはシステムの再起動動作を設定します。
AWSTOE は、アクションモジュールの入力パラメータに基づいて**msiexec**コマンドを生成します。`path` (MSI ファイルの場所) と `logFile` (ログファイルの場所) の入力パラメータの値は、引用符 (「) で囲む必要があります。
次の MSI 終了コードは成功とみなされます。
+ 0 - 成功
+ 1614 (製品\$1アンインストールエラー)
+ 1641 (再起動が開始されました)
+ 3010 (再起動が必要です)
**Input**
| キー名 | 説明 | タイプ | 必須 | デフォルトの値 | 許容値 |
| --- | --- | --- | --- | --- | --- |
| path | 次のいずれかを使用して MSI ファイルの場所を指定します。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/imagebuilder/latest/userguide/toe-action-modules.html) チェーン式は許可されています。 | String | はい | 該当なし | 該当なし |
| reboot | アクションモジュールが正常に実行された後のシステム再起動動作を設定します。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/imagebuilder/latest/userguide/toe-action-modules.html) | String | いいえ | Allow | Allow, Force, Skip |
| logOptions | MSI インストールロギングに使用するオプションを指定します。指定されたフラグは、ロギングを有効にする `/L` コマンドラインパラメータとともに MSI インストーラーに渡されます。フラグが指定されていない場合、 はデフォルト値 AWSTOE を使用します。 MSI の Log オプションの詳細については、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 | ログファイルの場所への絶対パスまたは相対パス。Log ファイルのパスが存在しない場合は、作成される。ログファイルパスが指定されていない場合、 AWSTOE は MSI インストールログを保存しません。 | String | いいえ | 該当なし | 該当なし |
| properties | MSI ロギングプロパティのキーと値のペア。例: `TARGETDIR: "C:\target\location"` 注:以下のプロパティは変更できません。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/imagebuilder/latest/userguide/toe-action-modules.html) | Map[String]String | いいえ | 該当なし | 該当なし |
| ignoreAuthenticodeSignatureErrors | path で指定されたインストーラーの authenticode 署名検証エラーを無視するフラグ。この **Get-AuthenticodeSignature** コマンドはインストーラーを検証するために使用されます。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/imagebuilder/latest/userguide/toe-action-modules.html) | ブール値 | いいえ | false | true, false |
| allowUnsignedInstaller | パスに指定された署名なしインストーラーの実行を許可するフラグ。この **Get-AuthenticodeSignature** コマンドはインストーラーを検証するために使用されます。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/imagebuilder/latest/userguide/toe-action-modules.html) | ブール値 | いいえ | 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
```
**入力例: ウェブパスのインストール**
```
- 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、またはウェブ URL を使用して、MSI ファイルの場所を指定できます。再起動オプションはシステムの再起動動作を設定します。
AWSTOE は、アクションモジュールの入力パラメータに基づいて**msiexec**コマンドを生成します。MSI ファイルの場所 (`path`) とログファイルの場所 (`logFile`) は、**msiexec** コマンドの生成時に二重引用符 (") で明示的に囲まれます。
次の MSI 終了コードは成功とみなされます。
+ 0 - 成功
+ 1605 (製品不明エラー)
+ 1614 (製品\$1アンインストールエラー)
+ 1641 (再起動が開始されました)
+ 3010 (再起動が必要です)
**Input**
| キー名 | 説明 | タイプ | 必須 | デフォルトの値 | 許容値 |
| --- | --- | --- | --- | --- | --- |
| path | 次のいずれかを使用して MSI ファイルの場所を指定します。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/imagebuilder/latest/userguide/toe-action-modules.html) チェーン式は許可されています。 | String | はい | 該当なし | 該当なし |
| reboot | アクションモジュールが正常に実行された後のシステム再起動動作を設定します。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/imagebuilder/latest/userguide/toe-action-modules.html) | String | いいえ | Allow | Allow, Force, Skip |
| logOptions | MSI インストールロギングに使用するオプションを指定します。指定されたフラグは、ロギングを有効にする `/L` コマンドラインパラメータとともに MSI インストーラーに渡されます。フラグが指定されていない場合、 はデフォルト値 AWSTOE を使用します。 MSI の Log オプションの詳細については、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 | ログファイルの場所への絶対パスまたは相対パス。Log ファイルのパスが存在しない場合は、作成される。ログファイルパスが指定されていない場合、 AWSTOE は MSI インストールログを保存しません。 | String | いいえ | 該当なし | 該当なし |
| properties | MSI ロギングプロパティのキーと値のペア。例: `TARGETDIR: "C:\target\location"` 注:以下のプロパティは変更できません。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/imagebuilder/latest/userguide/toe-action-modules.html) | Map[String]String | いいえ | 該当なし | 該当なし |
| ignoreAuthenticodeSignatureErrors | path で指定されたインストーラーの authenticode 署名検証エラーを無視するフラグ。この **Get-AuthenticodeSignature** コマンドはインストーラーを検証するために使用されます。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/imagebuilder/latest/userguide/toe-action-modules.html) | ブール値 | いいえ | false | true, false |
| allowUnsignedInstaller | パスに指定された署名なしインストーラーの実行を許可するフラグ。この **Get-AuthenticodeSignature** コマンドはインストーラーを検証するために使用されます。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/imagebuilder/latest/userguide/toe-action-modules.html) | ブール値 | いいえ | 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
```
**入力例: ウェブパスのインストールを削除**
```
- 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**
+ [Reboot (Linux、Windows)](#action-modules-reboot)
+ [SetRegistry (Windows)](#action-modules-setregistry)
+ [UpdateOS (Linux、Windows)](#action-modules-updateos)
### Reboot (Linux、Windows)
**再起動**アクションモジュールはインスタンスを再起動します。再起動の開始を遅らせる設定可能なオプションがあります。デフォルトでは、`delaySeconds` は `0` に設定されています。つまり、遅延はありません。ステップタイムアウトは、インスタンスの再起動時には適用されないため、再起動アクションモジュールではサポートされていません。
アプリケーションが Systems Manager エージェントによって呼び出されると、終了コード (Windows `3010` の場合、Linux `194` の場合) がSystems Manager エージェントに渡されます。システムマネージャーエージェントは、[スクリプトからマネージドインスタンスを再起動する](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html)の説明に従ってシステムの再起動を処理します。
アプリケーションがホスト上でスタンドアロンプロセスとして呼び出された場合、現在の実行状態を保存し、再起動後にアプリケーションを再実行するように再起動後の自動実行トリガーを構成し、システムを再起動します。
**再起動後の自動実行トリガー:**
+ **Windows**。 AWSTOE は `SystemStartup` で自動的に実行されるトリガーを含む Windows タスクスケジューラエントリを作成
+ **Linux**。 AWSTOE はシステム再起動後に自動的に実行されるジョブを crontab に追加します。
```
@reboot /download/path/awstoe run --document s3://bucket/key/doc.yaml
```
このトリガーはアプリケーションの起動時にクリーンアップされます。
**再試行**
デフォルトでは、再試行の最大回数は Systems Manager `CommandRetryLimit` に設定されています。再起動回数が再試行制限を超えると、自動化は失敗します。Systems Manager エージェント設定ファイル (`Mds.CommandRetryLimit`) を編集して制限を変更できます。Systems Manager エージェントオープンソースの「[Runtime Configuration](https://github.com/aws/amazon-ssm-agent/blob/mainline/README.md#runtime-configuration)」を参照してください。
**Reboot** アクションモジュールを使用するには、reboot `exitcode` を含むステップ（例えば `3010`）に対して、アプリケーションバイナリを `sudo user` として実行する必要があります。
**Input**
| キー名 | 説明 | タイプ | [Required] (必須) | [Default] (デフォルト) |
| --- | --- | --- | --- | --- |
| delaySeconds | 再起動を開始する前に、特定の時間だけ遅延させます。 | 整数 | いいえ | `0` |
**入力例: 再起動ステップ**
```
- name: RebootStep
action: Reboot
onFailure: Abort
maxAttempts: 2
inputs:
delaySeconds: 60
```
**出力**
なし。
**再起動**モジュールが完了すると、Image Builder はビルドの次のステップに進みます。
### SetRegistry (Windows)
**SetRegistry** アクションモジュールは入力のリストを受け入れ、指定したレジストリキーの値を設定できます。レジストリキーが存在しない場合、定義されたパスに作成されます。この機能は Windows のみに適用されます。
**Input**
| キー名 | 説明 | タイプ | 必須 |
| --- | --- | --- | --- |
| path | レジストリキーのパス。 | String | はい |
| name | レジストリキーの名前。 | String | はい |
| value | レジストリキーの値。 | 文字列/数値/配列 | はい |
| 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 のアップデートをインストールするためのサポートを追加します。使用可能なすべてのアップデートがデフォルトでインストールされます。あるいは、インストールするアクションモジュール用に 1 つ以上の特定のアップデートのリストを設定することもできます。インストールから除外するアップデートを指定することもできます。
「含める」リストと「除外」リストの両方を指定した場合、生成されるアップデートのリストには、「含む」リストにリストされているもののうち、「除外」リストには含まれていないものだけが含まれる可能性があります。
**注記**
**UpdateOS** は Amazon Linux 2023 (AL2023) をサポートしていません。ベース AMI をすべてのリリースに付属する新しいバージョンに更新することをお勧めします。他の方法については、Amazon Linux 2023 User Guide の [Control updates received from major and minor releases](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**
| キー名 | 説明 | タイプ | 必須 |
| --- | --- | --- | --- |
| include | Windows の場合、以下のように指定できる： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/imagebuilder/latest/userguide/toe-action-modules.html) Linux では、インストールするアップデートのリストに含めるパッケージを 1 つ以上指定できます。 | 文字列リスト | いいえ |
| exclude | Windows の場合、以下のように指定できる： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/imagebuilder/latest/userguide/toe-action-modules.html) Linux の場合、インストールするアップデートのリストから除外するパッケージを 1 つ以上指定できます。 | 文字列リスト | いいえ |
**入力例: 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*'
```
**出力**
なし。
# AWSTOE run コマンドの入力を設定する
コマンドのコマンドライン入力を AWSTOE **run**効率化するには、コマンドパラメータとオプションの設定を`.json`ファイル拡張子付きの JSON 形式の入力設定ファイルに含めることができます。 AWSTOE は、次のいずれかの場所からファイルを読み取ることができます。
+ ローカルファイルパス (*./config.json*)。
+ S3 バケット (*s3:////config.json*)。
**run** コマンドを入力すると、**--config** パラメータを使用して入力設定ファイルを指定できます。例:
```
awstoe run --config /config.json
```
**入力設定ファイル**
入力設定 JSON ファイルには、**run** コマンドパラメータとオプションで直接指定できるすべての設定のキーと値のペアが含まれています。入力設定ファイルと **run** コマンドの両方の設定をパラメータまたはオプションとして指定する場合、次の優先順位が適用されます。
**優先順位のルール**
1. パラメータまたはオプション AWS CLIを介して の**run**コマンドに直接提供される設定は、同じ設定の入力設定ファイルで定義されているすべての値を上書きします。
1. 入力設定ファイル内の設定は、コンポーネントのデフォルト値を上書きします。
1. コンポーネントドキュメントに他の設定が渡されない場合、デフォルト値があれば、そのデフォルト値を適用できます。
このルールには、ドキュメントとパラメータという 2 つの例外があります。これらの設定は、入力設定とコマンドパラメータでは動作が異なります。入力設定ファイルを使用する場合は、これらのパラメータを **run** コマンドに直接指定しないでください。そうするとエラーが発生する。
**コンポーネント設定**
入力設定ファイルには次の設定が含まれます。ファイルを効率化するために、不要なオプション設定は省略できます。特に明記されていない限り、すべての設定はオプションです。
+ **CWIgnoreFailures** (ブール値) — CloudWatch Logs からのロギング障害を無視します。
+ **CWLogGroup** (文字列) — CloudWatch Logs `LogGroup` 名。
+ **cwLogRegion** (文字列) – CloudWatch Logs に適用される AWS リージョン。
+ **cwLogStream** (文字列) – CloudWatch Logs `LogStream`の名前。`console.log`ファイルをストリーミングする AWSTOE 場所を指定します。
+ **documents3BuckeTowner** (文字列) — S3 URI ベースのドキュメントのバケット所有者のアカウント ID。
+ **documents** (オブジェクトの配列、必須) – AWSTOE **run** コマンドが実行されている YAML コンポーネントドキュメントを表す JSON オブジェクトの配列。少なくとも 1 つのコンポーネント文書を指定しなければならない。
各オブジェクトは以下のフィールドで構成される：
+ **パス** (文字列、必須) — 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** コマンドが渡すコンポーネント固有のパラメータを表します。コンポーネントではパラメータはオプションです。コンポーネントドキュメントにはパラメータが定義される場合とされない場合があります。
各オブジェクトは以下のフィールドで構成される：
+ **名前** (文字列、必須) — コンポーネントパラメータの名前。
+ **値** (文字列、必須) — コンポーネントドキュメントに渡される名前付きパラメータの値。
コンポーネントパラメータの詳細については、[カスタムコンポーネントドキュメントでの変数の使用](toe-user-defined-variables.md) ページの **[パラメータ]** セクションを参照してください。
+ **ExecutOnID** (文字列) — 現在の **run** コマンドの実行に適用される固有の ID。この ID は出力ファイル名とログファイル名に含まれ、これらのファイルを一意に識別し、現在のコマンド実行にリンクします。この設定を省略すると、 は GUID AWSTOE を生成します。
+ **logDirectory** (文字列) – がこのコマンド実行のすべてのログファイル AWSTOE を保存する送信先ディレクトリ。デフォルトでは、このディレクトリは親ディレクトリ `TOE__` の中にあります。ログディレクトリを指定しない場合、 は現在の作業ディレクトリ () AWSTOE を使用します`.`。
+ **logS3BucketName** (文字列) – コンポーネントログが Amazon S3 に保存されている場合 (推奨）、 はコンポーネントアプリケーションログをこのパラメータで という名前の S3 バケット AWSTOE にアップロードします。
+ **logS3BucketOwner** (文字列) – コンポーネントログが Amazon S3 に保存されている場合 (推奨）、これは がログファイルを AWSTOE 書き込むバケットの所有者アカウント ID です。
+ **Logs3KeyPrefix** (文字列) — コンポーネントログが Amazon S3 に保存されている場合 (推奨)、これはバケット内のログの場所の S3 オブジェクトキープレフィックスです。
+ **パラメータ** (オブジェクトの配列) — 現在の **run** コマンド実行に含まれるすべてのコンポーネントにグローバルに適用されるパラメータを表すキー値のペアオブジェクトの配列。
+ **name**（文字列、必須） - グローバルパラメータの名前。
+ **値** (文字列、必須) — すべてのコンポーネントドキュメントに渡される名前付きパラメータの値。
+ **フェーズ** (文字列) — YAML コンポーネントドキュメントから実行するフェーズを指定するカンマ区切りのリスト。コンポーネントドキュメントに追加のフェーズが含まれている場合、そのフェーズは実行されません。
+ **StateDirectory** (文字列) — ステートトラッキングファイルが保存されているファイルパス。
+ **トレース** (ブール値) — コンソールへの冗長ロギングを有効にする。
**例**
次の例は、2 つのコンポーネント文書に対して `build` と `test` のフェーズを実行する入力設定ファイルを示している: `sampledoc.yaml`と`conversation-intro.yaml`です。各コンポーネントドキュメントには、それ自体にのみ適用されるパラメータがあり、どちらも 1 つの共有パラメータを使用します。この `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": ""
}
```