• O AWS Systems Manager CloudWatch Dashboard não estará mais disponível a partir de 30 de abril de 2026. Os clientes podem continuar usando o console do Amazon CloudWatch para visualizar, criar e gerenciar os painéis do Amazon CloudWatch exatamente como fazem hoje. Para obter mais informações, consulte a [documentação do Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html).
# Componentes do documento
Esta seção contém informações sobre os componentes presentes nos documentos do SSM.
**Topics**
+ [
# Esquemas, atributos e exemplos
](documents-schemas-features.md)
+ [
# Elementos e parâmetros de dados
](documents-syntax-data-elements-parameters.md)
+ [
# Referência de plug-ins de documentos de comando
](documents-command-ssm-plugin-reference.md)
# Esquemas, atributos e exemplos
AWS Systems ManagerOs documentos do (SSM) usam as versões de esquema a seguir.
+ Os documentos do tipo `Command` podem usar o esquema versão 1.2, 2.0 e 2.2. Se você usa documentos do esquema 1.2, recomendamos criar documentos que utilizem o esquema versão 2.2.
+ Os documentos do tipo `Policy` devem usar o esquema versão 2.0 ou posterior.
+ Os documentos do tipo `Automation` devem usar o esquema versão 0.3.
+ Os documentos do tipo `Session` devem usar o esquema versão 1.0.
+ Você pode criar documentos em JSON ou YAML.
Para obter mais informações sobre o esquema de documentos do `Session`, consulte [Esquema do documento de sessão](session-manager-schema.md).
Ao usar a versão de esquema mais recentes para documentos `Command` e `Policy`, você poderá aproveitar os seguintes recursos.
**Recursos de documentos da versão 2.2 do esquema**
| Recurso | Detalhes |
| --- | --- |
| Edição de documentos | Agora, documentos podem ser atualizados. Com a versão 1.2, qualquer atualização de um documento exigia que você o salvasse com um nome diferente. |
| Versionamento automático | Qualquer atualização de um documento cria uma nova versão. Esta não é uma versão de esquema, mas uma versão do documento. |
| Versão padrão | Se você possui várias versões de um documento, pode especificar qual delas é o documento padrão. |
| Sequenciamento | Os plugins ou as *etapas* em um documento são executados na ordem que você especificou. |
| Suporte entre plataformas | O suporte entre plataformas permite que você especifique diferentes sistemas operacionais para diferentes plugins dentro do mesmo documento do SSM. O suporte entre plataformas usa o parâmetro `precondition` dentro de uma etapa. |
| Interpolação de parâmetros | Interpolação significa inserir ou substituir um valor variável em uma string. Pense nisso como preencher um espaço em branco com valores reais antes que a string seja usada. No contexto de documentos do SSM, a interpolação de parâmetros permite que parâmetros de string sejam interpolados em variáveis de ambiente antes da execução do comando, fornecendo melhor segurança contra injeções de comando. Quando definido como `ENV_VAR`, o agente cria uma variável de ambiente denominada `SSM_parameter-name` que contém o valor do parâmetro. |
**nota**
Você deve manter o AWS Systems Manager SSM Agent atualizado em suas instâncias com a versão mais recente para usar os novos recursos do Systems Manager e os recursos de documento do SSM. Para obter mais informações, consulte [Atualização do SSM Agent por meio de Run Command](run-command-tutorial-update-software.md#rc-console-agentexample).
A tabela a seguir lista as diferenças entre as principais versões de esquema.
****
| Versão 1.2 | Versão 2.2 (versão mais recente) | Detalhes |
| --- | --- | --- |
| runtimeConfig | mainSteps | Na versão 2.2, a seção `mainSteps` substitui `runtimeConfig`. O`mainSteps`A seção permite que o Systems Manager execute etapas em sequência. |
| propriedades | inputs | Na versão 2.2, a seção `inputs` substitui a seção `properties`. A seção `inputs` aceita parâmetros para as etapas. |
| comandos | runCommand | Na versão 2.2, a seção `inputs` usa o parâmetro `runCommand` em vez do parâmetro `commands`. |
| id | ação | Na versão 2.2, `Action` substitui `ID`. Esta é apenas uma mudança de nome. |
| não aplicável | name | Na versão 2.2, `name` é um nome definido pelo usuário para uma etapa. |
**Usar o parâmetro precondition**
Com o esquema versão 2.2 ou superior, você pode usar o parâmetro `precondition` para especificar o sistema operacional de destino de cada plugin ou para validar parâmetros de entrada que você definiu em seu documento do SSM. O`precondition`suporta referenciar os parâmetros de entrada do documento SSM, e`platformType`usando valores de`Linux`,`MacOS`, e`Windows`. Somente a`StringEquals`é suportado.
Para documentos que utilizam o esquema versão 2.2 ou posterior, se a `precondition` não for especificada, cada plugin será executado ou ignorado com base na compatibilidade do plugin com o sistema operacional. Compatibilidade de plugins com o sistema operacional é avaliada antes do `precondition`. Para documentos que utilizam o esquema 2.0 ou anterior, os plugins incompatíveis geram um erro.
Por exemplo, em um documento com a versão 2.2 do esquema, se `precondition` não for especificado e o plugin `aws:runShellScript` estiver relacionado, a etapa será executada em instâncias do Linux, mas será ignorada pelo sistema em instâncias do Windows Server porque o `aws:runShellScript` não é compatível com instâncias do Windows Server. No entanto, para um documento de esquema versão 2.0, se você especificar o plugin `aws:runShellScript` e depois executar o documento em instâncias do Windows Server, a execução falhará. Você poderá ver um exemplo do parâmetro de pré-condição em um documento do SSM ainda nesta seção.
## Versão 2.2 do esquema
**Elementos de nível superior**
O exemplo a seguir mostra os elementos de nível superior de um documento do SSM usando o esquema versão 2.2.
------
#### [ YAML ]
```
---
schemaVersion: "2.2"
description: A description of the document.
parameters:
parameter 1:
property 1: "value"
property 2: "value"
parameter 2:
property 1: "value"
property 2: "value"
mainSteps:
- action: Plugin name
name: A name for the step.
inputs:
input 1: "value"
input 2: "value"
input 3: "{{ parameter 1 }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "A description of the document.",
"parameters": {
"parameter 1": {
"property 1": "value",
"property 2": "value"
},
"parameter 2":{
"property 1": "value",
"property 2": "value"
}
},
"mainSteps": [
{
"action": "Plugin name",
"name": "A name for the step.",
"inputs": {
"input 1": "value",
"input 2": "value",
"input 3": "{{ parameter 1 }}"
}
}
]
}
```
------
**Exemplo de esquema versão 2.2**
Veja como o exemplo a seguir usa o plugin `aws:runPowerShellScript` para executar um comando do PowerShell nas instâncias de destino.
------
#### [ YAML ]
```
---
schemaVersion: "2.2"
description: "Example document"
parameters:
Message:
type: "String"
description: "Example parameter"
default: "Hello World"
allowedValues:
- "Hello World"
mainSteps:
- action: "aws:runPowerShellScript"
name: "example"
inputs:
timeoutSeconds: '60'
runCommand:
- "Write-Output {{Message}}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Example document",
"parameters": {
"Message": {
"type": "String",
"description": "Example parameter",
"default": "Hello World",
"allowedValues": ["Hello World"]
}
},
"mainSteps": [
{
"action": "aws:runPowerShellScript",
"name": "example",
"inputs": {
"timeoutSeconds": "60",
"runCommand": [
"Write-Output {{Message}}"
]
}
}
]
}
```
------
**Exemplos do parâmetro precondition da versão 2.2 do esquema**
O esquema versão 2.2 fornece suporte para várias plataformas. Isso significa que, dentro de um único documento do SSM, você pode especificar diferentes sistemas operacionais para diferentes plugins. O suporte entre plataformas usa o parâmetro `precondition` dentro de uma etapa, como mostra o exemplo a seguir. Você também pode usar o`precondition`para validar os parâmetros de entrada definidos no documento do SSM. Veja isso no segundo exemplo a seguir.
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: cross-platform sample
mainSteps:
- action: aws:runPowerShellScript
name: PatchWindows
precondition:
StringEquals:
- platformType
- Windows
inputs:
runCommand:
- cmds
- action: aws:runShellScript
name: PatchLinux
precondition:
StringEquals:
- platformType
- Linux
inputs:
runCommand:
- cmds
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "cross-platform sample",
"mainSteps": [
{
"action": "aws:runPowerShellScript",
"name": "PatchWindows",
"precondition": {
"StringEquals": [
"platformType",
"Windows"
]
},
"inputs": {
"runCommand": [
"cmds"
]
}
},
{
"action": "aws:runShellScript",
"name": "PatchLinux",
"precondition": {
"StringEquals": [
"platformType",
"Linux"
]
},
"inputs": {
"runCommand": [
"cmds"
]
}
}
]
}
```
------
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
parameters:
action:
type: String
allowedValues:
- Install
- Uninstall
confirmed:
type: String
allowedValues:
- True
- False
mainSteps:
- action: aws:runShellScript
name: InstallAwsCLI
precondition:
StringEquals:
- "{{ action }}"
- "Install"
inputs:
runCommand:
- sudo apt install aws-cli
- action: aws:runShellScript
name: UninstallAwsCLI
precondition:
StringEquals:
- "{{ action }} {{ confirmed }}"
- "Uninstall True"
inputs:
runCommand:
- sudo apt remove aws-cli
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"parameters": {
"action": {
"type": "String",
"allowedValues": [
"Install",
"Uninstall"
]
},
"confirmed": {
"type": "String",
"allowedValues": [
true,
false
]
}
},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "InstallAwsCLI",
"precondition": {
"StringEquals": [
"{{ action }}",
"Install"
]
},
"inputs": {
"runCommand": [
"sudo apt install aws-cli"
]
}
},
{
"action": "aws:runShellScript",
"name": "UninstallAwsCLI",
"precondition": {
"StringEquals": [
"{{ action }} {{ confirmed }}",
"Uninstall True"
]
},
"inputs": {
"runCommand": [
"sudo apt remove aws-cli"
]
}
}
]
}
```
------
**Exemplo de interpolação do esquema versão 2.2 com versões do SSM Agent anteriores à 3.3.2746.0**
Nas versões do SSM Agent anteriores à 3.3.2746.0, o agente ignora o parâmetro `interpolationType` e, em vez disso, executa uma substituição de string bruta. Se estiver referenciando `SSM_parameter-name` de forma explícita, você deve definir explicitamente. No exemplo a seguir para Linux, a variável de ambiente `SSM_Message` é referenciada explicitamente.
```
{
"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",
"inputs": {
"runCommand": [
"if [ -z "${SSM_Message+x}" ]; then",
" export SSM_Message=\"{{Message}}\"",
"fi",
"",
"echo $SSM_Message"
]
}
}
}
```
**nota**
`allowedPattern` não será tecnicamente necessário se um documento do SSM não usar chaves duplas: `{{ }}`
**Exemplo de esquema versão 2.2 do State Manager**
Você pode usar o seguinte documento do SSM com o State Manager, uma ferramenta do Systems Manager, para baixar e instalar o software antivírus ClamAV. O State Manager impõe uma configuração específica, o que significa que cada vez que a associação do State Manager for executada, o sistema verificará se o software ClamAV está instalado. Se não, o State Manager executa novamente esse documento.
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: State Manager Bootstrap Example
parameters: {}
mainSteps:
- action: aws:runShellScript
name: configureServer
inputs:
runCommand:
- sudo yum install -y httpd24
- sudo yum --enablerepo=epel install -y clamav
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "State Manager Bootstrap Example",
"parameters": {},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "configureServer",
"inputs": {
"runCommand": [
"sudo yum install -y httpd24",
"sudo yum --enablerepo=epel install -y clamav"
]
}
}
]
}
```
------
**Exemplo de inventário do esquema versão 2.2**
Você pode usar o documento SSM a seguir com o State Manager para coletar metadados de inventário sobre suas instâncias.
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: Software Inventory Policy Document.
parameters:
applications:
type: String
default: Enabled
description: "(Optional) Collect data for installed applications."
allowedValues:
- Enabled
- Disabled
awsComponents:
type: String
default: Enabled
description: "(Optional) Collect data for AWS Components like amazon-ssm-agent."
allowedValues:
- Enabled
- Disabled
networkConfig:
type: String
default: Enabled
description: "(Optional) Collect data for Network configurations."
allowedValues:
- Enabled
- Disabled
windowsUpdates:
type: String
default: Enabled
description: "(Optional) Collect data for all Windows Updates."
allowedValues:
- Enabled
- Disabled
instanceDetailedInformation:
type: String
default: Enabled
description: "(Optional) Collect additional information about the instance, including
the CPU model, speed, and the number of cores, to name a few."
allowedValues:
- Enabled
- Disabled
customInventory:
type: String
default: Enabled
description: "(Optional) Collect data for custom inventory."
allowedValues:
- Enabled
- Disabled
mainSteps:
- action: aws:softwareInventory
name: collectSoftwareInventoryItems
inputs:
applications: "{{ applications }}"
awsComponents: "{{ awsComponents }}"
networkConfig: "{{ networkConfig }}"
windowsUpdates: "{{ windowsUpdates }}"
instanceDetailedInformation: "{{ instanceDetailedInformation }}"
customInventory: "{{ customInventory }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Software Inventory Policy Document.",
"parameters": {
"applications": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for installed applications.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"awsComponents": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for AWS Components like amazon-ssm-agent.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"networkConfig": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for Network configurations.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"windowsUpdates": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for all Windows Updates.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"instanceDetailedInformation": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect additional information about the instance, including\nthe CPU model, speed, and the number of cores, to name a few.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"customInventory": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for custom inventory.",
"allowedValues": [
"Enabled",
"Disabled"
]
}
},
"mainSteps": [
{
"action": "aws:softwareInventory",
"name": "collectSoftwareInventoryItems",
"inputs": {
"applications": "{{ applications }}",
"awsComponents": "{{ awsComponents }}",
"networkConfig": "{{ networkConfig }}",
"windowsUpdates": "{{ windowsUpdates }}",
"instanceDetailedInformation": "{{ instanceDetailedInformation }}",
"customInventory": "{{ customInventory }}"
}
}
]
}
```
------
**Exemplo de esquema versão 2.2 do `AWS-ConfigureAWSPackage`**
O exemplo a seguir mostra o documento `AWS-ConfigureAWSPackage`. O`mainSteps`Inclui a seção`aws:configurePackage`plugin no`action`Etapa.
**nota**
Nos sistemas operacionais Linux, somente os pacotes `AmazonCloudWatchAgent` e `AWSSupport-EC2Rescue` são suportados.
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Install or uninstall the latest version or specified version of an AWS
package. Available packages include the following: AWSPVDriver, AwsEnaNetworkDriver,
AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.'
parameters:
action:
description: "(Required) Specify whether or not to install or uninstall the package."
type: String
allowedValues:
- Install
- Uninstall
name:
description: "(Required) The package to install/uninstall."
type: String
allowedPattern: "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$|^[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$"
version:
type: String
description: "(Optional) A specific version of the package to install or uninstall."
mainSteps:
- action: aws:configurePackage
name: configurePackage
inputs:
name: "{{ name }}"
action: "{{ action }}"
version: "{{ version }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Install or uninstall the latest version or specified version of an AWS package. Available packages include the following: AWSPVDriver, AwsEnaNetworkDriver, AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.",
"parameters": {
"action": {
"description":"(Required) Specify whether or not to install or uninstall the package.",
"type":"String",
"allowedValues":[
"Install",
"Uninstall"
]
},
"name": {
"description": "(Required) The package to install/uninstall.",
"type": "String",
"allowedPattern": "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$|^[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$"
},
"version": {
"type": "String",
"description": "(Optional) A specific version of the package to install or uninstall."
}
},
"mainSteps":[
{
"action": "aws:configurePackage",
"name": "configurePackage",
"inputs": {
"name": "{{ name }}",
"action": "{{ action }}",
"version": "{{ version }}"
}
}
]
}
```
------
## Versão 1.2 do esquema
O exemplo a seguir mostra os elementos de nível superior de um documento do esquema versão 1.2.
```
{
"schemaVersion":"1.2",
"description":"A description of the SSM document.",
"parameters":{
"parameter 1":{
"one or more parameter properties"
},
"parameter 2":{
"one or more parameter properties"
},
"parameter 3":{
"one or more parameter properties"
}
},
"runtimeConfig":{
"plugin 1":{
"properties":[
{
"one or more plugin properties"
}
]
}
}
}
```
**Exemplo de esquema versão 1.2 do `aws:runShellScript`**
O exemplo a seguir mostra o`AWS-RunShellScript`Documento do MUS do. A seção **runtimeConfig** inclui o plugin `aws:runShellScript`.
```
{
"schemaVersion":"1.2",
"description":"Run a shell script or specify the commands to run.",
"parameters":{
"commands":{
"type":"StringList",
"description":"(Required) Specify a shell script or a command to run.",
"minItems":1,
"displayType":"textarea"
},
"workingDirectory":{
"type":"String",
"default":"",
"description":"(Optional) The path to the working directory on your instance.",
"maxChars":4096
},
"executionTimeout":{
"type":"String",
"default":"3600",
"description":"(Optional) The time in seconds for a command to complete before it is considered to have failed. Default is 3600 (1 hour). Maximum is 172800 (48 hours).",
"allowedPattern":"([1-9][0-9]{0,3})|(1[0-9]{1,4})|(2[0-7][0-9]{1,3})|(28[0-7][0-9]{1,2})|(28800)"
}
},
"runtimeConfig":{
"aws:runShellScript":{
"properties":[
{
"id":"0.aws:runShellScript",
"runCommand":"{{ commands }}",
"workingDirectory":"{{ workingDirectory }}",
"timeoutSeconds":"{{ executionTimeout }}"
}
]
}
}
}
```
## Versão 0.3 do esquema
**Elementos de nível superior**
O exemplo a seguir mostra os elementos de nível superior de um runbook do Automation versão 0.3 do esquema no formato JSON.
```
{
"description": "document-description",
"schemaVersion": "0.3",
"assumeRole": "{{assumeRole}}",
"parameters": {
"parameter1": {
"type": "String",
"description": "parameter-1-description",
"default": ""
},
"parameter2": {
"type": "String",
"description": "parameter-2-description",
"default": ""
}
},
"variables": {
"variable1": {
"type": "StringMap",
"description": "variable-1-description",
"default": {}
},
"variable2": {
"type": "String",
"description": "variable-2-description",
"default": "default-value"
}
},
"mainSteps": [
{
"name": "myStepName",
"action": "action-name",
"maxAttempts": 1,
"inputs": {
"Handler": "python-only-handler-name",
"Runtime": "runtime-name",
"Attachment": "script-or-zip-name"
},
"outputs": {
"Name": "output-name",
"Selector": "selector.value",
"Type": "data-type"
}
}
],
"files": {
"script-or-zip-name": {
"checksums": {
"sha256": "checksum"
},
"size": 1234
}
}
}
```
**Exemplo de runbook de automação YAML**
O exemplo a seguir mostra o conteúdo de um runbook do Automation, no formato YAML. Este exemplo funcional da versão 0.3 do esquema do documento também demonstra o uso do Markdown para formatar descrições de documentos.
```
description: >-
##Title: LaunchInstanceAndCheckState
-----
**Purpose**: This Automation runbook first launches an EC2 instance
using the AMI ID provided in the parameter ```imageId```. The second step of
this document continuously checks the instance status check value for the
launched instance until the status ```ok``` is returned.
##Parameters:
-----
Name | Type | Description | Default Value
------------- | ------------- | ------------- | -------------
assumeRole | String | (Optional) The ARN of the role that allows Automation to
perform the actions on your behalf. | -
imageId | String | (Optional) The AMI ID to use for launching the instance.
The default value uses the latest Amazon Linux AMI ID available. | {{
ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64 }}
schemaVersion: '0.3'
assumeRole: 'arn:aws:iam::111122223333::role/AutomationServiceRole'
parameters:
imageId:
type: String
default: '{{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64 }}'
description: >-
(Optional) The AMI ID to use for launching the instance. The default value
uses the latest released Amazon Linux AMI ID.
tagValue:
type: String
default: ' LaunchedBySsmAutomation'
description: >-
(Optional) The tag value to add to the instance. The default value is
LaunchedBySsmAutomation.
instanceType:
type: String
default: t2.micro
description: >-
(Optional) The instance type to use for the instance. The default value is
t2.micro.
mainSteps:
- name: LaunchEc2Instance
action: 'aws:executeScript'
outputs:
- Name: payload
Selector: $.Payload
Type: StringMap
inputs:
Runtime: python3.11
Handler: launch_instance
Script: ''
InputPayload:
image_id: '{{ imageId }}'
tag_value: '{{ tagValue }}'
instance_type: '{{ instanceType }}'
Attachment: launch.py
description: >-
**About This Step**
This step first launches an EC2 instance using the ```aws:executeScript```
action and the provided python script.
- name: WaitForInstanceStatusOk
action: 'aws:executeScript'
inputs:
Runtime: python3.11
Handler: poll_instance
Script: |-
def poll_instance(events, context):
import boto3
import time
ec2 = boto3.client('ec2')
instance_id = events['InstanceId']
print('[INFO] Waiting for instance status check to report ok', instance_id)
instance_status = "null"
while True:
res = ec2.describe_instance_status(InstanceIds=[instance_id])
if len(res['InstanceStatuses']) == 0:
print("Instance status information is not available yet")
time.sleep(5)
continue
instance_status = res['InstanceStatuses'][0]['InstanceStatus']['Status']
print('[INFO] Polling to get status of the instance', instance_status)
if instance_status == 'ok':
break
time.sleep(10)
return {'Status': instance_status, 'InstanceId': instance_id}
InputPayload: '{{ LaunchEc2Instance.payload }}'
description: >-
**About This Step**
The python script continuously polls the instance status check value for
the instance launched in Step 1 until the ```ok``` status is returned.
files:
launch.py:
checksums:
sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
```
## Exemplos de tratamento seguro de parâmetros
Os exemplos a seguir demonstram o tratamento seguro de parâmetros usando a variável de ambiente `interpolationType`.
### Execução segura básica de comandos
Este exemplo mostra como tratar com segurança um parâmetro de comando:
**nota**
`allowedPattern` não é tecnicamente exigido em documentos do SSM que não usam chaves duplas: `{{ }}`
------
#### [ YAML ]
```
---
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}}
```
------
#### [ JSON ]
```
{
"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}}"
]
}
}]
}
```
------
### Uso de parâmetros em linguagens interpretadas
Este exemplo demonstra o tratamento seguro de parâmetros em Python:
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Secure Python script execution'
parameters:
inputData:
type: String
description: 'Input data for processing'
interpolationType: 'ENV_VAR'
mainSteps:
- action: aws:runPowerShellScript
name: runPython
inputs:
runCommand:
- |
python3 -c '
import os
import json
# Safely access parameter through environment variable
input_data = os.environ.get("SSM_inputData", "")
# Process the data
try:
processed_data = json.loads(input_data)
print(f"Successfully processed: {processed_data}")
except json.JSONDecodeError:
print("Invalid JSON input")
'
```
------
### Exemplo de compatibilidade com versões anteriores
Este exemplo mostra como tratar parâmetros de forma segura enquanto mantém a compatibilidade com versões anteriores:
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Backwards compatible secure parameter handling'
parameters:
userInput:
type: String
description: 'User input to process'
interpolationType: 'ENV_VAR'
allowedPattern: '^[^"]*$'
mainSteps:
- action: aws:runShellScript
name: processInput
inputs:
runCommand:
- |
# Handle both modern and legacy agent versions
if [ -z "${SSM_userInput+x}" ]; then
# Legacy agent - fall back to direct parameter reference
export SSM_userInput="{{userInput}}"
fi
# Process the input securely
echo "Processing input: $SSM_userInput"
```
------
**nota**
`allowedPattern` não é tecnicamente exigido em documentos do SSM que não usam chaves duplas: `{{ }}`
## Práticas recomendadas de segurança de parâmetros
Siga estas práticas recomendadas ao tratar parâmetros em documentos do SSM:
+ **Use a interpolação de variáveis de ambiente**: sempre use `interpolationType: "ENV_VAR"` para parâmetros de string que serão usados na execução do comando.
+ **Implemente uma validação de entrada**: use `allowedPattern` para restringir os valores dos parâmetros a padrões seguros.
+ **Lide com sistemas legados**: inclua lógica de fallback para as versões anteriores do SSM Agent que não são compatíveis com a interpolação de variáveis de ambiente.
+ **Escape de caracteres especiais**: ao usar valores de parâmetros em comandos, escape adequadamente dos caracteres especiais para evitar a interpretação pelo shell.
+ **Limite o escopo do parâmetro**: use os padrões de parâmetros mais restritivos possíveis para seu caso de uso.
# Elementos e parâmetros de dados
Este tópico descreve os elementos de dados usados nos documentos do SSM. A versão do esquema usada para criar um documento define a sintaxe e os elementos de dados que o documento aceita. Recomendamos usar a versão 2.2 ou posterior do esquema para documentos do Command. Runbooks de automação usam o esquema versão 0.3. Além disso, runbooksde automação são compatíveis com o uso de Markdown, uma linguagem de marcação, que permite adicionar descrições de estilo wiki a documentos e etapas individuais dentro do documento. Para obter mais informações sobre o uso de Markdown, consulte [Usar o Markdown no console](https://docs.aws.amazon.com/general/latest/gr/aws-markdown.html) no *Guia de conceitos básicos do Console de gerenciamento da AWS*.
A seção a seguir descreve os elementos de dados que você pode incluir em um documento SSM.
## Elementos de dados de nível superior
**schemaVersion**
A versão do esquema a ser usada.
Tipo: versão
Obrigatório: Sim
**descrição**
Informações que você fornece para descrever a finalidade do documento. Você também pode usar esse campo para especificar se um parâmetro requer um valor para que um documento seja executado ou se fornecer um valor para o parâmetro é opcional. Parâmetros obrigatórios e opcionais podem ser vistos nos exemplos neste tópico.
Tipo: string
Obrigatório: não
**parameters**
Uma estrutura que define os parâmetros que o documento aceita.
Para maior segurança ao tratar parâmetros de string, você pode usar a interpolação de variáveis de ambiente especificando a propriedade `interpolationType`. Quando definido como `ENV_VAR`, o sistema cria uma variável de ambiente denominada `SSM_parameter-name` contendo o valor do parâmetro.
Veja a seguir um exemplo de um parâmetro usando a variável de ambiente `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}}"
]
}
}
}
```
`allowedPattern` não é tecnicamente exigido em documentos do SSM que não usam chaves duplas: `{{ }}`
Para os parâmetros usados com frequência, recomendamos armazená-los no Parameter Store, uma ferramenta do AWS Systems Manager. Em seguida, você pode definir parâmetros em seu documento que façam referência a parâmetros do Parameter Store como o valor padrão deles. Para fazer referência a um parâmetro do Parameter Store, use a sintaxe a seguir.
```
{{ssm:parameter-name}}
```
Você pode usar um parâmetro que faça referência a um parâmetro do Parameter Store da mesma forma que faria com qualquer outro parâmetro de documento. No exemplo a seguir, o valor padrão para o parâmetro `commands` é o parâmetro `myShellCommands` do Parameter Store. Ao especificar o parâmetro `commands` como uma string `runCommand`, o documento executa os comandos armazenados no parâmetro `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 }}"
]
}
}
]
}
```
Você pode fazer referência aos parâmetros `String` e `StringList` do Parameter Store na seção `parameters` do seu documento. Você não pode fazer referência a parâmetros `SecureString` do Parameter Store.
Para obter mais informações sobre o Parameter Store, consulte [AWS Systems Manager Parameter Store](systems-manager-parameter-store.md).
Tipo: estrutura
A estrutura `parameters` aceita os seguintes campos e valores:
+ `type`: (obrigatório) os valores permitidos incluem os seguintes: `String`, `StringList`, `Integer`, `Boolean`, `MapList` e `StringMap`. Para ver exemplos de cada tipo, consulte [Exemplos de `type` de parâmetro de documentos SSM](#top-level-properties-type) na próxima seção.
**nota**
Os documentos do tipo de comando oferecem suporte somente aos tipos de parâmetros `String` e `StringList`.
+ `description`: (opcional) uma descrição do parâmetro.
+ `default`: (opcional) o valor padrão do parâmetro ou uma referência a um parâmetro no Parameter Store.
+ `allowedValues`: (opcional) uma matriz de valores permitidos para o parâmetro. A definição de valores permitidos para o parâmetro valida a entrada do usuário. Se um usuário inserir um valor que não é permitido, a execução falhará ao iniciar.
------
#### [ 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`: (opcional) uma expressão regular que valida se a entrada do usuário corresponde ao padrão definido para o parâmetro. Se a entrada do usuário não corresponder ao padrão permitido, a execução não será iniciada.
**nota**
O Systems Manager realiza duas validações para `allowedPattern`. A primeira validação é realizada usando a [biblioteca de regex Java](https://docs.oracle.com/javase/8/docs/api/java/util/regex/package-summary.html) no nível da API quando você usa um documento. A segunda validação é realizada no SSM Agent usando [a biblioteca de regex GO ](https://pkg.go.dev/regexp) antes de processar o documento.
------
#### [ 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`: (opcional) usado para exibir um `textfield` ou uma `textarea` no Console de gerenciamento da AWS. `textfield` é uma caixa de texto de uma única linha. `textarea` é uma área de texto de várias linhas.
+ `minItems`: (opcional) o número mínimo de itens permitidos.
+ `maxItems`: (opcional) o número máximo de itens permitidos.
+ `minChars`: (opcional) o número mínimo de caracteres de parâmetro permitidos.
+ `maxChars`: (opcional) o número máximo de caracteres de parâmetro permitidos.
+ `interpolationType`: (opcional) define como os valores dos parâmetros são processados antes da execução do comando. Quando definido como `ENV_VAR`, o valor do parâmetro é disponibilizado como uma variável de ambiente denominada `SSM_parameter-name`. Esse recurso ajuda a evitar a injeção de comando tratando os valores dos parâmetros como strings literais.
Tipo: string
Valores válidos: `ENV_VAR`
Obrigatório: não
**variables**
(Somente na versão 0.3 do esquema) Valores que podem ser referenciados ou atualizados em todas as etapas em um runbook de automação. As variáveis são semelhantes aos parâmetros, mas diferem de uma forma muito importante. Os valores dos parâmetros são estáticos no contexto de um runbook, mas os valores das variáveis podem ser alterados no contexto do runbook. Ao atualizar o valor de uma variável, o tipo de dados deve corresponder ao tipo de dados definido. Para informações sobre como atualizar valores de variáveis em uma automação, consulte [`aws:updateVariable`: atualiza um valor para uma variável do runbook](automation-action-update-variable.md)
Tipo: Boolean \$1 Integer \$1 MapList \$1 String \$1 StringList \$1 StringMap
Obrigatório: não
```
variables:
payload:
type: StringMap
default: "{}"
```
```
{
"variables": [
"payload": {
"type": "StringMap",
"default": "{}"
}
]
}
```
**runtimeConfig**
(Esquema somente para a versão 1.2) A configuração para a instância conforme aplicada por um ou mais plugins do Systems Manager. Não há garantia de execução dos plugins em sequência.
Tipo: Dictionary
Obrigatório: não
**mainSteps**
(Somente para versões 0.3, 2.0 e 2.2 do esquema) um objeto que pode incluir várias etapas (plugins). Plugins são definidos dentro de etapas. As etapas são executadas na ordem sequencial listada no documento.
Tipo: Dictionary
Obrigatório: Sim
**outputs**
(Somente versão 0.3 do esquema) dados gerados pela execução deste documento que podem ser usados em outros processos. Por exemplo, se o documento criar uma nova AMI, você poderá especificar "CreateImage.ImageId" como o valor de saída e usar essa saída para criar novas instâncias em uma execução de automação subsequente. Para obter mais informações sobre saídas, consulte [Uso de saídas de ações como entradas](automation-action-outputs-inputs.md).
Tipo: Dictionary
Obrigatório: não
**files**
(Somente a versão 0.3 do esquema) os arquivos de script (e as respectivas somas de verificação) anexados ao documento e executados durante uma execução de automação. Aplica-se somente a documentos que incluem a ação `aws:executeScript` e para os quais anexos foram especificados em uma ou mais etapas.
Para saber mais sobre os runtimes compatíveis com os runbooks do Automation, consulte [`aws:executeScript` – Executa um script](automation-action-executeScript.md). Para obter mais informações sobre como incluir scripts em runbooks do Automation, consulte [Uso de scripts em runbooks](automation-document-script-considerations.md) e [Experiência de design visual para runbooks de automação](automation-visual-designer.md).
Ao criar um runbook de automação com anexos, é necessário especificar arquivos de anexo usando a opção `--attachments` (na AWS CLI) ou `Attachments` (na API e no SDK). É possível especificar o local do arquivo para documentos do SSM e arquivos armazenados nos buckets do Amazon Simple Storage Service (Amazon S3). Para obter mais informações, consulte [Anexos](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateDocument.html#systemsmanager-CreateDocument-request-Attachments) na referência da API da AWS Systems Manager.
```
---
files:
launch.py:
checksums:
sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
```
```
"files": {
"launch.py": {
"checksums": {
"sha256": "18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE"
}
}
}
```
Tipo: Dictionary
Obrigatório: não
## Exemplos de `type` de parâmetro de documentos SSM
Os tipos de parâmetro em documentos SSM são estáticos. Isso significa que o tipo de parâmetro não pode ser alterado depois de definido. Ao usar parâmetros com plugins de documento do , o tipo de um parâmetro não pode ser alterado dinamicamente dentro da entrada de um plugin. Por exemplo, você não pode fazer referência a um parâmetro `Integer` dentro da entrada `runCommand` do plugin `aws:runShellScript` porque essa entrada aceita uma string ou lista de strings. Para usar um parâmetro para uma entrada de plugin, o tipo de parâmetro deve corresponder ao tipo aceito. Por exemplo, você deve especificar um parâmetro de tipo `Boolean` para a entrada `allowDowngrade` do plugin `aws:updateSsmAgent`. Se o tipo de parâmetro não corresponder ao tipo de entrada de um plugin, o documento do não será validado e o sistema não criará o documento. Isso também é verdadeiro ao usar parâmetros downstream dentro de entradas para outros plugins ou ações do AWS Systems Manager Automation. Por exemplo, não é possível fazer referência a um parâmetro `StringList` dentro da entrada `documentParameters` do plugin `aws:runDocument`. A entrada `documentParameters` aceita um mapa de strings mesmo que o tipo de parâmetro de documento do SSM downtream seja um parâmetro `StringList` e corresponda ao parâmetro que você está referenciando.
Ao usar parâmetros com ações do Automation do , os tipos de parâmetro não são validados quando você cria o documento SSM na maioria dos casos. Somente quando você usa a ação `aws:runCommand`, os tipos de parâmetro são validados ao criar o documento SSM. Em todos os outros casos, a validação do parâmetro ocorre durante a execução da automação quando a entrada de uma ação é verificada antes de executar a ação. Por exemplo, se o parâmetro de entrada for uma `String` e você fizer referência a ele como o valor da entrada `MaxInstanceCount` da ação `aws:runInstances`, o documento SSM será criado. No entanto, ao executar o documento, a automação falha ao validar a ação `aws:runInstances` porque a entrada `MaxInstanceCount` requer um `Integer`.
Veja a seguir exemplos de cada parâmetro `type`.
String
Uma sequência de zero ou mais caracteres Unicode colocados entre aspas. Por exemplo, "i-1234567890abcdef0". Use barras invertidas como caractere de escape.
Os parâmetros de string podem incluir um campo opcional `interpolationType` com o valor `ENV_VAR` para habilitar a interpolação de variáveis de ambiente para melhorar a segurança.
```
---
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
Uma lista de itens de strings separadas por vírgulas. Por exemplo, ["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"
}
```
Booleano
Aceita somente `true` ou `false`. Não aceita "true" ou 0.
```
---
canRun:
type: Boolean
description: ''
default: true
```
```
"canRun": {
"type": "Boolean",
"description": "",
"default": true
}
```
Inteiro
Números inteiros. Não aceita números decimais, como 3,14159, ou números colocados entre aspas, como "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
Um mapeamento de chaves para valores. Chaves e valores devem ser strings. Por exemplo, \$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
Uma lista de objetos 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
}
```
## Visualizar o conteúdo do documento do SSM Command
Para visualizar os parâmetros obrigatórios e opcionais para um documento de comando do AWS Systems Manager (SSM), além das ações executadas pelo documento, você pode visualizar o conteúdo do documento no console do Systems Manager.
**Para visualizar o conteúdo do documento do Comando SSM**
1. Abra o console AWS Systems Manager em [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. No painel de navegação, escolha **Documents**.
1. Na caixa de pesquisa, selecione **Tipo de documento** e, em seguida, **Comando**.
1. Selecione o nome de um documento existente e, em seguida, escolha a guia **Content** (Conteúdo).
1. No campo de conteúdo, revise os parâmetros disponíveis e as etapas de ação para o documento.
Por exemplo, a seguinte imagem mostra que (1) `version` e (2) `allowDowngrade` são parâmetros opcionais para o documento `AWS-UpdateSSMAgent` e que a primeira ação executada pelo documento é (3) `aws:updateSsmAgent`.
![\[Visualizar o conteúdo do documento do SSM no console do Systems Manager\]](http://docs.aws.amazon.com/pt_br/systems-manager/latest/userguide/images/view-document-content.png)
# Referência de plug-ins de documentos de comando
Essa referência descreve os plugins que você pode especificar em um documento de comando do AWS Systems Manager (SSM). Esses plugins não podem ser usados em documentos de automação do SSM que usam ações de automação. Para obter informações sobre ações de automação do AWS Systems Manager, consulte [Referência de ações do Systems Manager Automation](automation-actions.md).
O Systems Manager determina as ações a serem executadas em uma instância gerenciada lendo o conteúdo de um documento do SSM. Todo documento contém uma seção de execução de código. Dependendo da versão do esquema do documento, essa seção de execução de código pode conter um ou mais plugins ou etapas. Para a finalidade deste tópico da Ajuda, plugins e etapas são chamados de *plugins*. Esta seção inclui informações sobre cada um dos plugins do Systems Manager. Para obter mais informações sobre documentos, incluindo informações sobre a criação de documentos e as diferenças entre as versões de esquema, consulte [Documentos do AWS Systems Manager](documents.md).
Para plug-ins que aceitam parâmetros String, como `aws:runShellScript` e `aws:runPowerShellScript`, o parâmetro `interpolationType` pode ser usado para aumentar a segurança, tratando as entradas de parâmetros como literais de string em vez de comandos potencialmente executáveis. Por exemplo:
```
{
"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"
}
},
//truncated
}
```
**nota**
Alguns dos plugins descritos aqui são executados apenas em instâncias do Windows Server ou em instâncias do Linux. São indicadas dependências de plataforma para cada plugin.
Os plugins de documento a seguir são compatíveis com instâncias do Amazon Elastic Compute Cloud (Amazon EC2) para o macOS:
`aws:refreshAssociation`
`aws:runShellScript`
`aws:runPowerShellScript`
`aws:softwareInventory`
`aws:updateSsmAgent`
**Topics**
+ [
## Entradas compartilhadas
](#shared-inputs)
+ [
## `aws:applications`
](#aws-applications)
+ [
## `aws:cloudWatch`
](#aws-cloudWatch)
+ [
## `aws:configureDocker`
](#aws-configuredocker)
+ [
## `aws:configurePackage`
](#aws-configurepackage)
+ [
## `aws:domainJoin`
](#aws-domainJoin)
+ [
## `aws:downloadContent`
](#aws-downloadContent)
+ [
## `aws:psModule`
](#aws-psModule)
+ [
## `aws:refreshAssociation`
](#aws-refreshassociation)
+ [
## `aws:runDockerAction`
](#aws-rundockeraction)
+ [
## `aws:runDocument`
](#aws-rundocument)
+ [
## `aws:runPowerShellScript`
](#aws-runPowerShellScript)
+ [
## `aws:runShellScript`
](#aws-runShellScript)
+ [
## `aws:softwareInventory`
](#aws-softwareinventory)
+ [
## `aws:updateAgent`
](#aws-updateagent)
+ [
## `aws:updateSsmAgent`
](#aws-updatessmagent)
## Entradas compartilhadas
comSSM Agentversão 3.0.502 e posterior somente, todos os plugins podem usar as seguintes entradas:
**finallyStep**
A última etapa que você deseja que o documento seja executado. Se essa entrada for definida para uma etapa, ela terá precedência sobre um`exit`especificado no parâmetro`onFailure`ou`onSuccess`entradas. Para que uma etapa com essa entrada seja executada conforme esperado, a etapa deve ser a última definida no`mainSteps`do documento.
Tipo: booliano
Valores válidos: `true` \$1 `false`
Obrigatório: não
**onFailure**
Se você especificar esta entrada para um plugin com a opção`exit`e a etapa falhar, o status da etapa reflete a falha e o documento não executa as etapas restantes, a menos que um`finallyStep`foi definido. Se você especificar esta entrada para um plugin com a opção`successAndExit`e a etapa falhar, o status da etapa mostra bem-sucedida e o documento não executa as etapas restantes, a menos que um`finallyStep`foi definido.
Tipo: string
Valores válidos: `exit` \$1 `successAndExit`
Obrigatório: não
**onSuccess**
Se você especificar essa entrada para um plugin e a etapa for executada com êxito, o documento não executará nenhuma etapa restante, a menos que um`finallyStep`foi definido.
Tipo: string
Valores válidos: `exit`
Obrigatório: não
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: Shared inputs example
parameters:
customDocumentParameter:
type: String
description: Example parameter for a custom Command-type document.
mainSteps:
- action: aws:runDocument
name: runCustomConfiguration
inputs:
documentType: SSMDocument
documentPath: "yourCustomDocument"
documentParameters: '"documentParameter":{{customDocumentParameter}}'
onSuccess: exit
- action: aws:runDocument
name: ifConfigurationFailure
inputs:
documentType: SSMDocument
documentPath: "yourCustomRepairDocument"
onFailure: exit
- action: aws:runDocument
name: finalConfiguration
inputs:
documentType: SSMDocument
documentPath: "yourCustomFinalDocument"
finallyStep: true
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Shared inputs example",
"parameters": {
"customDocumentParameter": {
"type": "String",
"description": "Example parameter for a custom Command-type document."
}
},
"mainSteps":[
{
"action": "aws:runDocument",
"name": "runCustomConfiguration",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomDocument",
"documentParameters": "\"documentParameter\":{{customDocumentParameter}}",
"onSuccess": "exit"
}
},
{
"action": "aws:runDocument",
"name": "ifConfigurationFailure",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomRepairDocument",
"onFailure": "exit"
}
},
{
"action": "aws:runDocument",
"name":"finalConfiguration",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomFinalDocument",
"finallyStep": true
}
}
]
}
```
------
## `aws:applications`
Instala, repara ou desinstala aplicativos em uma instância do EC2. Este plugin é executado somente em sistemas operacionais Windows Server.
### Sintaxe
#### Esquema 2.2
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: aws:applications plugin
parameters:
source:
description: "(Required) Source of msi."
type: String
mainSteps:
- action: aws:applications
name: example
inputs:
action: Install
source: "{{ source }}"
```
------
#### [ JSON ]
```
{
"schemaVersion":"2.2",
"description":"aws:applications",
"parameters":{
"source":{
"description":"(Required) Source of msi.",
"type":"String"
}
},
"mainSteps":[
{
"action":"aws:applications",
"name":"example",
"inputs":{
"action":"Install",
"source":"{{ source }}"
}
}
]
}
```
------
#### Esquema 1.2
------
#### [ YAML ]
```
---
runtimeConfig:
aws:applications:
properties:
- id: 0.aws:applications
action: "{{ action }}"
parameters: "{{ parameters }}"
source: "{{ source }}"
sourceHash: "{{ sourceHash }}"
```
------
#### [ JSON ]
```
{
"runtimeConfig":{
"aws:applications":{
"properties":[
{
"id":"0.aws:applications",
"action":"{{ action }}",
"parameters":"{{ parameters }}",
"source":"{{ source }}",
"sourceHash":"{{ sourceHash }}"
}
]
}
}
}
```
------
### Propriedades
**ação**
A medida a ser tomada.
Tipo: Enum
Valores válidos: `Install` \$1 `Repair` \$1 `Uninstall`
Obrigatório: Sim
**parameters**
Os parâmetros para o instalador.
Tipo: string
Obrigatório: não
**origem**
O URL do arquivo `.msi` para o aplicativo.
Tipo: String
Exigido: sim
**sourceHash**
O hash SHA256 do arquivo `.msi`.
Tipo: string
Obrigatório: não
## `aws:cloudWatch`
Exporte dados do Windows Server para o Amazon CloudWatch ou Amazon CloudWatch Logs e monitore os dados usando as métricas do CloudWatch. Este plugin é executado somente em sistemas operacionais Windows Server. Para obter mais informações sobre como configurar a integração do CloudWatch, ao Amazon Elastic Compute Cloud (Amazon EC2) consulte [Coletar métricas, logs e rastreamentos com o atendente do CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) no *Guia de usuário do Amazon CloudWatch*.
**Importante**
O atendente unificado do CloudWatch substituiu SSM Agent como a ferramenta para enviar dados de log para o Amazon CloudWatch Logs. Não há compatibilidade com o plugin aws:cloudWatch do SSM Agent. Recomendamos usar somente o atendente do CloudWatch unificado nos processos de coleta de logs. Para saber mais, consulte os seguintes tópicos:
[Enviar logs de nós para o CloudWatch Logs unificado (agente do CloudWatch)](monitoring-cloudwatch-agent.md)
[Migrar a coleta de logs de nós do Windows Server para o agente do CloudWatch](monitoring-cloudwatch-agent.md#monitoring-cloudwatch-agent-migrate)
[Coletar métricas, logs e rastreamentos com o atendente do CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) no *Guia do usuário do Amazon CloudWatch*.
Você pode exportar e monitorar os seguintes tipos de dados:
**ApplicationEventLog**
Envia dados de log de eventos da aplicação para o CloudWatch Logs.
**CustomLogs**
Envia qualquer arquivo de log baseado em texto para o Amazon CloudWatch Logs. O plugin do CloudWatch cria uma impressão digital para os arquivos de log. O sistema associa então um deslocamento de dados com cada impressão digital. O plugin faz upload dos arquivos quando há alterações, registra o deslocamento e associa o deslocamento com uma impressão digital. Esse método é usado para evitar uma situação em que um usuário ativa o plugin, associa o serviço com um diretório que contém um grande número de arquivos, e o sistema faz upload de todos os arquivos.
Lembre-se de que, se seu aplicativo truncar ou tentar limpar os logs durante a sondagem, qualquer log especificado para `LogDirectoryPath` pode perder entradas. Se, por exemplo, você quiser limitar o tamanho do arquivo de log, crie um novo arquivo de log quando o limite for atingido e continue a gravar dados no novo arquivo.
**ETW**
Envia os dados de rastreamento de eventos para Windows (ETW) ao CloudWatch Logs.
**IIS**
Envia dados de log do IIS ao CloudWatch Logs.
**PerformanceCounter**
Envia contadores de performance do Windows para o CloudWatch. Você poderá selecionar categorias diferentes para fazer upload no CloudWatch como métricas. Para cada contador de performance que você deseja carregar, crie uma seção **PerformanceCounter** com um ID exclusivo (por exemplo, "PerformanceCounter2", "PerformanceCounter3" e assim por diante) e configure as respectivas propriedades.
Se o AWS Systems Manager SSM Agent ou o plugin do CloudWatch for interrompido, os dados do contador de performance não serão registrados em log no CloudWatch. Esse comportamento é diferente daquele dos logs personalizados ou dos logs de eventos do Windows. Os logs personalizados e logs de eventos do Windows preservarão dados do contador de performance e farão upload dos dados no CloudWatch depois que o SSM Agent ou o plugin do CloudWatch estiver disponível.
**SecurityEventLog**
Envia dados de log de eventos de segurança para o CloudWatch Logs.
**SystemEventLog**
Envia dados de log de eventos de sistema ao CloudWatch Logs
Você pode definir os seguintes destinos para os dados:
**CloudWatch**
O destino para o qual os dados de métrica do contador de performance são enviados. Você pode incluir mais seções com IDs exclusivos (por exemplo, "CloudWatch2", "CloudWatch3" etc.) e especificar uma região diferente para cada novo ID a fim de enviar os mesmos dados para diferentes locais.
**CloudWatchLogs**
O destino para o qual os dados de log são enviados. Você pode incluir mais seções com IDs exclusivos (por exemplo, "CloudWatchLogs2", "CloudWatchLogs3" etc.) e especificar uma região diferente para cada novo ID a fim de enviar os mesmos dados para diferentes locais.
### Sintaxe
```
"runtimeConfig":{
"aws:cloudWatch":{
"settings":{
"startType":"{{ status }}"
},
"properties":"{{ properties }}"
}
}
```
### Configurações e propriedades
**AccessKey**
Sua ID de chave de acesso. Essa propriedade é obrigatória, a menos que você tenha lançado sua instância usando uma função do IAM. Essa propriedade não pode ser usada com o SSM.
Tipo: string
Obrigatório: não
**CategoryName**
A categoria de contador de performance no Performance Monitor.
Tipo: String
Exigido: sim
**CounterName**
O nome do contador de performance no Performance Monitor.
Tipo: String
Exigido: sim
**CultureName**
O local em que o time stamp é registrado. Se **CultureName** estiver em branco, o mesmo local usado atualmente por sua instância do Windows Server será usado como o padrão.
Tipo: string
Valores válidos: para obter uma lista de valores comportados, consulte [National Language Support (NLS)](https://msdn.microsoft.com/en-us/library/cc233982.aspx) no site da Microsoft. Os valores **div**, **div-MV**, **hu** e **hu-HU** não são compatíveis.
Obrigatório: não
**DimensionName**
Uma dimensão para sua métrica do Amazon CloudWatch. Se você especificar `DimensionName`, também deverá especificar `DimensionValue`. Esses parâmetros produzem outro modo de exibição para a listagem de métricas. Você pode usar a mesma dimensão para várias métricas de modo a visualizar todas as métricas que pertencem a uma dimensão específica.
Tipo: string
Obrigatório: não
**DimensionValue**
Um valor de dimensão para a métrica do Amazon CloudWatch.
Tipo: string
Obrigatório: não
**Codificação**
A codificação de arquivo a ser usada (por exemplo, UTF-8). Use o nome da codificação, não o nome da exibição.
Tipo: string
Valores válidos: para obter uma lista de valores comportados, consulte [Encoding Class](https://learn.microsoft.com/en-us/dotnet/api/system.text.encoding?view=net-7.0) na biblioteca Microsoft Learn.
Obrigatório: Sim
**Filtro**
O prefixo dos nomes de log. Deixe esse parâmetro em branco para monitorar todos os arquivos.
Tipo: string
Valores válidos: para obter uma lista de valores compatíveis, consulte [FileSystemWatcherFilter property](http://msdn.microsoft.com/en-us/library/system.io.filesystemwatcher.filter.aspx) na biblioteca do MSDN.
Obrigatório: não
**Fluxos**
Cada tipo de dados para fazer upload, bem como o destino dos dados (CloudWatch ou CloudWatch Logs). Por exemplo, para enviar um contador de performance definido de acordo com `"Id": "PerformanceCounter"` para o destino do CloudWatch definido em `"Id": "CloudWatch"`, insira **"PerformanceCounter,CloudWatch"**. Da mesma forma, para enviar o log personalizado, o log do ETW e o log do sistema para o destino do CloudWatch Logs definido em `"Id": "ETW"`, insira **“(ETW),CloudWatchLogs”**. Além disso, é possível enviar o mesmo contador de performance ou arquivo de log para mais de um destino. Por exemplo, para enviar o log do aplicativo para dois destinos diferentes que você definiu em `"Id": "CloudWatchLogs"` e `"Id": "CloudWatchLogs2"`, insira **"ApplicationEventLog, (CloudWatchLogs, CloudWatchLogs2)"**.
Tipo: string
Valores válidos (origem): `ApplicationEventLog` \$1 `CustomLogs` \$1 `ETW` \$1 `PerformanceCounter` \$1 `SystemEventLog` \$1 `SecurityEventLog`
Valores válidos (destino): `CloudWatch` \$1 `CloudWatchLogs` \$1 `CloudWatch`*n* \$1 `CloudWatchLogs`*n*
Obrigatório: Sim
**FullName**
O nome completo do componente.
Tipo: String
Exigido: sim
**Id**
Identifica a origem de dados ou o destino. Esse identificador deve ser exclusivo no arquivo de configuração.
Tipo: String
Exigido: sim
**InstanceName**
O nome da instância do contador de performance. Não use um asterisco (\$1) para indicar todas as instâncias, pois cada componente do contador de performance só é compatível com uma única métrica. Você pode, porém, usar **\$1Total**.
Tipo: String
Exigido: sim
**Níveis**
Os tipos de mensagem a enviar para o Amazon CloudWatch.
Tipo: string
Valores válidos:
+ **1** - Somente o upload de mensagens de erro.
+ **2** - Somente o upload de mensagens de aviso.
+ **4** - Somente o upload de mensagens de informação.
Observe que você pode adicionar valores para incluir mais de um tipo de mensagem. Por exemplo, **3** significa que mensagens de erro (**1**) e mensagens de aviso (**2**) estão incluídas. Um valor de **7** significa que mensagens de erro (**1**), mensagens de aviso (**2**) e mensagens informativas (**4**) estão incluídas.
Obrigatório: Sim
Os logs de segurança do Windows devem definir os níveis como 7.
**LineCount**
O número de linha no cabeçalho para identificar o arquivo de log. Por exemplo, os arquivos de log do IIS têm cabeçalhos praticamente idênticos. Você pode especificar **3**, que leria as três primeiras linhas do cabeçalho do arquivo de log para identificá-lo. Em arquivos de log do IIS, a terceira linha é o time stamp que é diferente entre arquivos de log.
Tipo: inteiro
Obrigatório: não
**LogDirectoryPath**
Em CustomLogs, o caminho em que os logs são armazenados na instância do EC2. Para logs do IIS, a pasta em que os logs do IIS são armazenados para um site específico (por exemplo, **C:\$1\$1inetpub\$1\$1logs\$1\$1LogFiles\$1\$1W3SVC*n***). Para logs do IIS, somente o formato de log W3C é comportado. Não há suporte para os formatos IIS, NCSA e Personalizado.
Tipo: String
Exigido: sim
**LogGroup**
O nome para o seu grupo de logs. Esse nome é exibido na tela **Log Groups** (Grupos de logs) no console do CloudWatch.
Tipo: String
Exigido: sim
**LogName**
O nome do arquivo de log.
1. Para encontrar o nome do log, no Visualizador de Eventos, no painel de navegação, clique em **Logs de aplicações e serviços**.
1. Na lista de logs, clique com o botão direito do mouse no log do qual você deseja fazer upload (por exemplo, `Microsoft` > `Windows` > `Backup` > `Operational`) e clique em **Criar Modo de Exibição Personalizado**.
1. Na caixa de diálogo **Create Custom View** (Criar modo de exibição personalizado), selecione a guia **XML**. O **LogName** está na tag