• 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).
# 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)