• AWS Systems Manager CloudWatch ダッシュボードは、2026 年 4 月 30 日以降は利用できなくなります。お客様は、これまでと同様に Amazon CloudWatch コンソールを使用して、Amazon CloudWatch ダッシュボードの表示、作成、管理を継続できます。詳細については、「[Amazon CloudWatch ダッシュボードのドキュメント](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)」を参照してください。
# データ要素とパラメータ
このトピックでは、SSM ドキュメントで使用されるデータ要素について説明します。ドキュメントの作成に使用されるスキーマのバージョンは、ドキュメントで使用できる構文とデータ要素を定義します。コマンドドキュメントには、スキーマバージョン 2.2 以降を使用することをお勧めします。Automation ランブックはスキーマバージョン 0.3 を使用します。さらに、Automation ランブックでは、マークアップ言語である Markdown の使用がサポートされています。これにより、wiki スタイルの説明をドキュメントやドキュメント内の個々のステップに追加できます。Markdown の使用に関する詳細については、「AWS マネジメントコンソール 入門ガイド」の「[コンソールでの Markdown の使用](https://docs.aws.amazon.com/general/latest/gr/aws-markdown.html)」を参照してください。
次のセクションでは、SSM ドキュメントに含めることができるデータ要素について説明します。
## 最上位のデータ要素
**schemaVersion**
使用するスキーマバージョン。
型: バージョン
必須: はい
**description**
ドキュメントの目的を説明するために提供する情報。またこのフィールドを使用して、ドキュメントの実行にパラメータの値が必要か否か、またはパラメータの値の指定が任意か否かを指定することもできます。必須と任意のパラメータはこのトピックのサンプルをご参照ください。
タイプ: 文字列
必須: いいえ
**パラメータ**
ドキュメントが許可するパラメータを定義する構造。
文字列パラメータを処理する際のセキュリティを強化するには、`interpolationType` プロパティを指定して環境変数補間を使用します。`ENV_VAR` に設定すると、システムは、パラメータの値を含む `SSM_parameter-name` という名前の環境変数を作成します。
次は、環境変数 `interpolationType` を使用するパラメータの例です。
```
{
"schemaVersion": "2.2",
"description": "An example document.",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType" : "ENV_VAR",
"allowedPattern": "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"precondition" : {
"StringEquals" : ["platformType", "Linux"]
},
"inputs": {
"runCommand": [
"echo {{Message}}"
]
}
}
}
```
SSM ドキュメントが二重中括弧 `{{ }}` を使用していない場合、`allowedPattern` は理論的には必要ありません。
頻繁に使用するパラメータの場合は、そのパラメータを AWS Systems Manager のツールである Parameter Store に保存することをお勧めします。次に、デフォルト値として Parameter Store パラメータを参照するパラメータをドキュメントで定義できます。Parameter Store パラメータを参照するには、次の構文を使用します。
```
{{ssm:parameter-name}}
```
他のドキュメントパラメータと同じ方法で、Parameter Store パラメータを参照するパラメータを使用できます。次の例では、`commands` パラメータのデフォルト値は Parameter Store パラメータ `myShellCommands` です。`commands` パラメータを `runCommand` 文字列として指定すると、ドキュメントは `myShellCommands` パラメータに格納されているコマンドを実行します。
```
---
schemaVersion: '2.2'
description: runShellScript with command strings stored as Parameter Store parameter
parameters:
commands:
type: StringList
description: "(Required) The commands to run on the instance."
default: ["{{ ssm:myShellCommands }}"],
interpolationType : 'ENV_VAR'
allowedPattern: '^[^"]*$'
mainSteps:
- action: aws:runShellScript
name: runShellScriptDefaultParams
inputs:
runCommand:"{{ commands }}"
```
```
{
"schemaVersion": "2.2",
"description": "runShellScript with command strings stored as Parameter Store parameter",
"parameters": {
"commands": {
"type": "StringList",
"description": "(Required) The commands to run on the instance.",
"default": ["{{ ssm:myShellCommands }}"],
"interpolationType" : "ENV_VAR"
}
},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "runShellScriptDefaultParams",
"inputs": {
"runCommand": [
"{{ commands }}"
]
}
}
]
}
```
`String` および `StringList` Parameter Store パラメータは、ドキュメントの `parameters` セクションで参照できます。`SecureString` Parameter Store パラメータは参照できません。
の詳細については、「Parameter Store」を参照してください。[AWS Systems Manager Parameter Store](systems-manager-parameter-store.md)
型: 構造
`parameters`構造は次のフィールドと値を受け入れます。
+ `type`: (必須) その値として `String`、`StringList`、`Integer`、`Boolean`、`MapList`、`StringMap` を使用できます。各タイプの例を表示するには、次のセクションの「[SSM ドキュメントパラメータ `type` の例](#top-level-properties-type)」を参照してください。
**注記**
コマンドタイプのドキュメントでは、`String` および `StringList` パラメータタイプのみがサポートされます。
+ `description`: (オプション) パラメータグループの説明。
+ `default`: (オプション) Parameter Store でのパラメータのデフォルト値またはパラメータへの参照。
+ `allowedValues`: (オプション) パラメータに使用できる値の配列。パラメータに使用できる値を定義すると、ユーザー入力が検証されます。使用できない値をユーザーが入力すると、実行の開始に失敗します。
------
#### [ YAML ]
```
DirectoryType:
type: String
description: "(Required) The directory type to launch."
default: AwsMad
allowedValues:
- AdConnector
- AwsMad
- SimpleAd
```
------
#### [ JSON ]
```
"DirectoryType": {
"type": "String",
"description": "(Required) The directory type to launch.",
"default": "AwsMad",
"allowedValues": [
"AdConnector",
"AwsMad",
"SimpleAd"
]
}
```
------
+ `allowedPattern`: (オプション) ユーザー入力がパラメータに対して定義されたパターンと一致するかどうかを検証する正規表現。ユーザー入力が使用できるパターンと一致しない場合、実行は開始されません。
**注記**
Systems Manager は、`allowedPattern` について 2 つの検証を実行します。1 つ目の検証は、ドキュメントを使用するときに API レベルで [Java 正規表現ライブラリ](https://docs.oracle.com/javase/8/docs/api/java/util/regex/package-summary.html)を使用して実行されます。2 つ目の検証は、ドキュメントを処理する前に [GO regexp ライブラリ](https://pkg.go.dev/regexp)を使用して SSM Agent に対して実行されます。
------
#### [ YAML ]
```
InstanceId:
type: String
description: "(Required) The instance ID to target."
allowedPattern: "^i-(?:[a-f0-9]{8}|[a-f0-9]{17})$"
default: ''
```
------
#### [ JSON ]
```
"InstanceId": {
"type": "String",
"description": "(Required) The instance ID to target.",
"allowedPattern": "^i-(?:[a-f0-9]{8}|[a-f0-9]{17})$",
"default": ""
}
```
------
+ `displayType`: (オプション) `textfield` の `textarea` または AWS マネジメントコンソール のいずれかを表示するために使用されます。`textfield` は、1 行のテキストボックスで、`textarea` は、複数行のテキストエリアです。
+ `minItems`: (オプション) 許可される項目の最小数。
+ `maxItems`: (オプション) 許可される項目の最大数。
+ `minChars`: (オプション) 許可される項目の最小数。
+ `maxChars`: (オプション) を許可されているパラメータ文字の最大数。
+ `interpolationType`: (オプション) コマンドを実行する前にパラメータ値をどのように処理するかを定義します。`ENV_VAR` に設定すると、パラメータ値は `SSM_parameter-name` という名前の環境変数として使用できるようになります。この機能を使うと、パラメータ値をリテラル文字列として処理することによりコマンドインジェクションを防げるようになります。
型: 文字列
有効な値: `ENV_VAR`
必須：いいえ
**variables**
(スキーマバージョン 0.3 のみ) 自動化ランブックのステップ全体で参照または更新できる値。変数はパラメーターと似ていますが、非常に重要な点において異なります。パラメーター値はランブックのコンテキストでは静的ですが、変数の値はランブックのコンテキストでは変更できます。変数の値を更新する場合、データ型は定義されたデータ型と一致する必要があります。オートメーションの変数値の更新に関する詳細は、「[`aws:updateVariable` — ランブック変数の値を更新します。](automation-action-update-variable.md)」を参照してください。
型: ブール値｜整数｜マップリスト｜文字列｜文字列リスト｜文字列マップ
必須: いいえ
```
variables:
payload:
type: StringMap
default: "{}"
```
```
{
"variables": [
"payload": {
"type": "StringMap",
"default": "{}"
}
]
}
```
**runtimeConfig**
(スキーマバージョン 1.2 のみ) 1 つ以上の Systems Manager プラグインによって適用されるインスタンスの構成。プラグインは必ずしも順番に実行されるとは限りません。
型: Dictionary
必須: いいえ
**mainSteps**
(スキーマバージョン 0.3、2.0、および 2.2 のみ) 複数のステップ (プラグイン) を含むことができるオブジェクト。プラグインはステップ内で定義されます。ステップは、ドキュメントに記載されている順番に実行されます。
型: Dictionary
必須: はい
**出力**
(スキーマバージョン 0.3 のみ) このドキュメントの実行によって生成され、他のプロセスで使用できるデータ。例えば、ドキュメントで新しい AMI を作成する場合、出力値として「CreateImage.ImageId」を指定すると、この出力を使用して後続のオートメーションの実行から新しいインスタンスを作成できます。出力の詳細については、「[アクション出力の入力としての使用](automation-action-outputs-inputs.md)」を参照してください。
型: Dictionary
必須: いいえ
**files**
(スキーマバージョン 0.3 のみ) ドキュメントに添付され、自動実行時に実行されるスクリプトファイル (およびそのチェックサム)。`aws:executeScript` アクションを含むドキュメントのうち、添付ファイルが 1 つ以上のステップに指定されているもののみに適用されます。
オートメーションランブックでサポートされているランタイムについては、「[`aws:executeScript` – スクリプトを実行する](automation-action-executeScript.md)」を参照してください。Automation ランブックにスクリプトを含める方法の詳細については、「[ランブックでのスクリプトの使用](automation-document-script-considerations.md)」および「[オートメーションランブックのビジュアルデザインエクスペリエンス](automation-visual-designer.md)」を参照してください。
アタッチメントの付いたオートメーションランブックを作成するときは、`--attachments` オプション (AWS CLI の場合) または `Attachments` (API および SDK の場合) を使用して添付ファイルを指定する必要があります。SSM ドキュメントと、Amazon Simple Storage Service (Amazon S3) バケット内に保存されているファイルの両方で、ファイルの場所を指定できます。詳細については、「AWS Systems Manager API リファレンス」の「[Attachments](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateDocument.html#systemsmanager-CreateDocument-request-Attachments)」(アタッチメント) を参照してください。
```
---
files:
launch.py:
checksums:
sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
```
```
"files": {
"launch.py": {
"checksums": {
"sha256": "18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE"
}
}
}
```
型: Dictionary
必須: いいえ
## SSM ドキュメントパラメータ `type` の例
SSM ドキュメント内のパラメータのデータ型は静的です。つまり、パラメータのデータ型は定義後に変更することはできません。SSM ドキュメントプラグインでパラメータを使用する場合、パラメータのデータ型をプラグインの入力内で動的に変更することはできません。例えば、`Integer` プラグインの `runCommand` 入力内の `aws:runShellScript` パラメータを参照することはできません。この入力は文字列または文字列のリストを受け入れるためです。プラグインの入力にパラメータを使用するには、パラメータのデータ型が、入力の受け入れ可能なデータ型と一致している必要があります。例えば、`Boolean` プラグインの `allowDowngrade` 入力には `aws:updateSsmAgent` 型のパラメータを指定する必要があります。パラメータのデータ型がプラグインの入力のデータ型と一致しない場合、SSM ドキュメントの検証は失敗となり、システムによってドキュメントは作成されません。これは、他のプラグイン、もしくは AWS Systems Manager のオートメーションアクション用に、入力内にある下流のパラメータを使用する場合にも当てはまります。例えば、`aws:runDocument` プラグインの `documentParameters` 入力にある `StringList` パラメータを参照することはできません。ダウンストリーム SSM ドキュメントパラメータのタイプが `StringList` パラメータで、かつ参照しようとしているパラメータと一致する場合でも、`documentParameters` 入力は、文字列へのマッピングを受け入れます。
オートメーションアクションでパラメータを使用するときは、ほとんどの場合、SSM ドキュメントを作成するときにパラメータのデータ型は検証されません。`aws:runCommand` アクションを使用する場合にのみ、SSM ドキュメントを作成するときにパラメータのデータ型が検証されます。それ以外の場合、オートメーションの実行中、アクションが実行される前にその入力が検証されるときに、パラメータが検証されます。例えば、入力パラメータが `String` であり、それを `MaxInstanceCount` アクションの `aws:runInstances` 入力の値として参照する場合は、SSM ドキュメントが作成されます。ただし、ドキュメントを実行すると、`aws:runInstances` アクションの検証中にオートメーションは失敗します。`MaxInstanceCount` 入力に `Integer` が必要なためです。
以下に示しているのは、各パラメータ `type` の例です。
文字列
引用符で囲んだ 0 個以上の Unicode 文字のシーケンス。例えば、"i-1234567890abcdef0" など。バックスラッシュを使用してエスケープします。
文字列パラメータには、セキュリティを高めるために環境変数補間を有効にする値 `ENV_VAR` を持つ、オプションの `interpolationType` フィールドを含めることができます。
```
---
InstanceId:
type: String
description: "(Optional) The target EC2 instance ID."
interpolationType: ENV_VAR
```
```
"InstanceId":{
"type":"String",
"description":"(Optional) The target EC2 instance ID.",
"interpolationType": "ENV_VAR"
}
```
StringList
カンマ区切りの文字列項目のリスト。例えば、["cd \$1", "pwd"] など。
```
---
commands:
type: StringList
description: "(Required) Specify a shell script or a command to run."
default: ""
minItems: 1
displayType: textarea
```
```
"commands":{
"type":"StringList",
"description":"(Required) Specify a shell script or a command to run.",
"minItems":1,
"displayType":"textarea"
}
```
Boolean
`true` または `false` のみを使用できます。"true" または 0 は使用できません。
```
---
canRun:
type: Boolean
description: ''
default: true
```
```
"canRun": {
"type": "Boolean",
"description": "",
"default": true
}
```
整数
整数。小数 (3.14159 など) や引用符で囲んだ数字 ("3" など) は使用できません。
```
---
timeout:
type: Integer
description: The type of action to perform.
default: 100
```
```
"timeout": {
"type": "Integer",
"description": "The type of action to perform.",
"default": 100
}
```
StringMap
キーと値のマッピング。キーと値は文字列でなければなりません。例えば、\$1"Env": "Prod"\$1 など。
```
---
notificationConfig:
type: StringMap
description: The configuration for events to be notified about
default:
NotificationType: 'Command'
NotificationEvents:
- 'Failed'
NotificationArn: "$dependency.topicArn"
maxChars: 150
```
```
"notificationConfig" : {
"type" : "StringMap",
"description" : "The configuration for events to be notified about",
"default" : {
"NotificationType" : "Command",
"NotificationEvents" : ["Failed"],
"NotificationArn" : "$dependency.topicArn"
},
"maxChars" : 150
}
```
MapList
StringMap オブジェクトのリスト。
```
blockDeviceMappings:
type: MapList
description: The mappings for the create image inputs
default:
- DeviceName: "/dev/sda1"
Ebs:
VolumeSize: "50"
- DeviceName: "/dev/sdm"
Ebs:
VolumeSize: "100"
maxItems: 2
```
```
"blockDeviceMappings":{
"type":"MapList",
"description":"The mappings for the create image inputs",
"default":[
{
"DeviceName":"/dev/sda1",
"Ebs":{
"VolumeSize":"50"
}
},
{
"DeviceName":"/dev/sdm",
"Ebs":{
"VolumeSize":"100"
}
}
],
"maxItems":2
}
```
## SSM コマンドドキュメントの内容の表示
AWS Systems Manager (SSM) コマンドドキュメントの必須パラメータとオプションのパラメータ、およびドキュメントが実行するアクションをプレビューするには、Systems Manager コンソールでドキュメントのコンテンツを表示できます。
**SSM コマンドドキュメントの内容を表示するには**
1. AWS Systems Manager コンソール ([https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)) を開きます。
1. ナビゲーションペインで、**[ドキュメント]** を選択します。
1. 検索ボックスで、[**ドキュメントのタイプ**] を選択し、[**コマンド**] を選択します。
1. ドキュメントの名前を選択し、[**コンテンツ**] タブをクリックします。
1. [コンテンツ] フィールドで、ドキュメントで使用できるパラメータとアクションステップを確認します。
例えば、次の図は、(1) `version` と (2) `allowDowngrade` が `AWS-UpdateSSMAgent` ドキュメントのオプションのパラメータで、ドキュメントによって実行される最初のアクションが (3) `aws:updateSsmAgent` であることを示しています。
![\[Systems Manager コンソールで SSM ドキュメントの内容を表示する\]](http://docs.aws.amazon.com/ja_jp/systems-manager/latest/userguide/images/view-document-content.png)