Elementi di dati e parametri - AWS Systems Manager
Elementi di dati di primo livelloEsempi type di parametri di documenti SSMVisualizzazione del contenuto del documento Command SSM

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Elementi di dati e parametri

Questo argomento descrive gli elementi di dati utilizzati nei documenti SSM. La versione dello schema utilizzata per creare un documento definisce la sintassi e gli elementi di dati accettati. Per i documenti di comando è consigliabile utilizzare la versione dello schema 2.2 o successiva. I runbook Automation utilizzano la versione dello schema 0.3. Inoltre, i runbook Automation supportano l'uso di Markdown, un linguaggio di markup, che consente di aggiungere descrizioni in stile wiki ai documenti e alle singole fasi all'interno del documento. Per ulteriori informazioni sull'utilizzo di Markdown, consulta Utilizzo di Markdown nella console nella Guida alle operazioni di base di AWS Management Console .

La sezione seguente descrive gli elementi di dati che si possono includere in un documento SSM.

Elementi di dati di primo livello

schemaVersion

La versione dello schema da utilizzare.

Tipo: Versione

Campo obbligatorio: sì

description

Le informazioni fornite per descrivere lo scopo del documento. È inoltre possibile utilizzare questo campo per specificare se un parametro richiede un valore per l'esecuzione di un documento o se è facoltativo fornire un valore per il parametro. I parametri obbligatori e facoltativi possono essere visualizzati negli esempi in questo argomento.

Tipo: string

Campo obbligatorio: no

parametri

Una struttura che definisce i parametri accettati dal documento.

Per i parametri che usi spesso, ti consigliamo di memorizzarli in Parameter Store, uno strumento in AWS Systems Manager. Quindi, potete definire nel documento i parametri a cui fare riferimento Parameter Store parametri come valore predefinito. Per fare riferimento a Parameter Store parametro, utilizzare la seguente sintassi. 

{{ssm:parameter-name}}

È possibile utilizzare un parametro che fa riferimento a Parameter Store parametro allo stesso modo di qualsiasi altro parametro del documento. Nell'esempio seguente, il valore predefinito per il commands parametro è Parameter Store parametromyShellCommands. Specificando il valore del parametro commands come stringa runCommand, il documento esegue i comandi memorizzati nel parametro myShellCommands.

YAML
---
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 }}"]
mainSteps:
- action: aws:runShellScript
  name: runShellScriptDefaultParams
  inputs:
    runCommand:"{{ commands }}"
JSON
{
    "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 }}"]
      }
    },
    "mainSteps": [
      {
        "action": "aws:runShellScript",
        "name": "runShellScriptDefaultParams",
        "inputs": {
            "runCommand": [
              "{{ commands }}"
          ]
        }
      }
    ]
  }
Nota

È possibile fare riferimento a String e StringList Parameter Store parametri nella parameters sezione del documento. Non puoi fare riferimento SecureString Parameter Store parametri.

Per ulteriori informazioni sull' Parameter Store, consulta AWS Systems Manager Parameter Store.

Tipo: Struttura

La struttura parameters accetta i seguenti campi e valori:

  • type: (Obbligatorio) I valori consentiti sono i seguenti: String, StringList, Integer, Boolean, MapList e StringMap. Per visualizzare esempi di ciascun tipo, consulta Esempi type di parametri di documenti SSM nella sezione successiva.

    Nota

    I documenti di tipo di comando supportano solo i tipi di parametri String e StringList.

  • description: (facoltativo) La descrizione del parametro.

  • default: (Facoltativo) Il valore predefinito del parametro o un riferimento a un parametro in Parameter Store.

  • allowedValues: (facoltativo) una matrice dei valori consentiti per il parametro. La definizione dei valori consentiti per il parametro convalida l'input dell'utente. Se un utente inserisce un valore non consentito, l'esecuzione non viene avviata.

    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: (facoltativo) un'espressione regolare che convalida se l'input dell'utente corrisponde al modello definito per il parametro. Se l'input dell'utente non corrisponde al modello consentito, l'esecuzione non viene avviata.

    Nota

    Systems Manager esegue due convalide per allowedPattern. La prima convalida viene eseguita utilizzando la libreria Java regex a livello di API quando si utilizza un documento. La seconda convalida viene eseguita su SSM Agent utilizzando la libreria regexp GO prima di elaborare il documento.

    YAML
    InstanceId:
  type: String
  description: "(Required) The instance ID to target."
  allowedPattern: "^i-[a-z0-9]{8,17}$"
  default: ''
    JSON
    "InstanceId": {
  "type": "String",
  "description": "(Required) The instance ID to target.",
  "allowedPattern": "^i-[a-z0-9]{8,17}$",
  "default": ""
}

  • displayType: (Facoltativo) Utilizzato per visualizzare un textfield o un textarea in. AWS Management Consoletextfieldè una casella di testo a riga singola. textareaè un'area di testo su più righe.

  • minItems: (facoltativo) Il numero minimo di elementi consentiti.

  • maxItems: (facoltativo) Il numero massimo di elementi consentiti.

  • minChars: (facoltativo) Il numero minimo di caratteri del parametro consentiti.

  • maxChars: (facoltativo) Il numero massimo di caratteri del parametro consentiti.

Campo obbligatorio: no

variables

(Solo versione 0.3 dello schema) Valori a cui è possibile fare riferimento o da aggiornare durante i passaggi di un runbook Automation. Le variabili sono simili ai parametri, ma presentano una differenza molto rilevante. Nel contesto di un runbook, i valori dei parametri sono statici mentre quelli delle variabili possono essere modificati. Quando si aggiorna il valore di una variabile, il tipo di dati deve corrispondere al tipo di dati definito. Per informazioni sull'aggiornamento dei valori delle variabili in un'automazione, consulta la pagina aws:updateVariable: aggiorna un valore per una variabile di runbook

Tipo: Boolean | Integer | | String | | MapList StringList StringMap

Campo obbligatorio: no

YAML
variables:
    payload:
        type: StringMap
        default: "{}"
JSON
{
    "variables": [
        "payload": {
            "type": "StringMap",
            "default": "{}"
        }
    ]
}
runtimeConfig

(Solo versione dello schema 1.2) La configurazione per l'istanza applicata da uno o più plugin di Systems Manager. Non è garantito che l'esecuzione dei plugin avvenga in sequenza.

Tipo: Dictionary<String, > PluginConfiguration

Campo obbligatorio: no

mainSteps

(Solo versione dello schema 0.3, 2.0 e 2.2) Un oggetto che può includere più fasi (plugin). I plugin sono definiti all'interno delle fasi. Le fasi vengono eseguite nell'ordine sequenziale indicato nel documento.

Tipo: Dictionary<String, > PluginConfiguration

Campo obbligatorio: sì

outputs

(Solo versione dello schema 0.3) Dati generati dall'esecuzione di questo documento che possono essere utilizzati in altri processi. Ad esempio, se il documento ne crea uno nuovo AMI, è possibile specificare "CreateImage. ImageId"come valore di output, quindi utilizza questo output per creare nuove istanze in una successiva esecuzione di automazione. Per ulteriori informazioni sugli output, consulta Utilizzo degli output delle operazioni come input.

Tipo: Dictionary<string, > OutputConfiguration

Campo obbligatorio: no

files

(Solo versione dello schema 0.3) I file di script (e i relativi checksum) collegati al documento ed eseguiti durante un'esecuzione dell'automazione. Si applica solo ai documenti che includono l'operazione aws:executeScript e per i quali gli allegati sono stati specificati in una o più fasi.

Per ulteriori informazioni sui runtime supportati dai runbook Automation, vedere aws:executeScript: esecuzione di uno script. Per ulteriori informazioni sull'inclusione di script nei runbook Automation, consultare Utilizzo di script nei runbook e Esperienza di progettazione visiva per i runbook di automazione.

Quando si crea un runbook di automazione con allegati, è inoltre necessario specificare i file allegati utilizzando l'--attachmentsopzione (for AWS CLI) o Attachments (per API e SDK). È possibile specificare la posizione del file sia per i documenti SSM che per i file archiviati nei bucket Amazon Simple Storage Service (Amazon S3). Per ulteriori informazioni, consulta Attachments in the API Reference. AWS Systems Manager

YAML
---
files:
  launch.py:
    checksums:
      sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
JSON
"files": {
    "launch.py": {
        "checksums": {
            "sha256": "18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE"
        }
    }
}

Tipo: dictionary<String, > FilesConfiguration

Campo obbligatorio: no

Esempi type di parametri di documenti SSM

I tipi di parametri nei documenti SSM sono statici. Ciò significa che il tipo di parametro non può essere modificato dopo che è stato definito. Quando si utilizzano parametri con plugin del documento SSM, il tipo di parametro non può essere modificato dinamicamente all'interno dell'input di un plugin. Ad esempio, non è possibile fare riferimento a un parametro Integer all'interno dell'input runCommand del plugin aws:runShellScript perché questo input accetta una stringa o un elenco di stringhe. Per utilizzare un parametro per un input di plugin, il tipo di parametro deve corrispondere al tipo accettato. Ad esempio, è necessario specificare un tipo di parametro Boolean per l'input allowDowngrade del plugin aws:updateSsmAgent. Se il tipo di parametro non corrisponde al tipo di input per un plugin, il documento SSM non viene convalidato e il sistema non crea il documento. Questo vale anche quando si utilizzano parametri a valle all'interno degli input per altri plugin o azioni di automazione. AWS Systems Manager Ad esempio, non è possibile fare riferimento a un parametro di StringList nell'input documentParameters del plugin aws:runDocument. L'input di documentParameters accetta una mappa di stringhe anche se il tipo di parametro del documento SSM a valle è un parametro StringList e corrisponde al parametro a cui si fa riferimento.

Quando si utilizzano parametri con operazioni di automazione di , nella maggior parte dei casi i tipi di parametro non vengono convalidati quando si crea il documento SSM. Solo quando si utilizza l'operazione aws:runCommand, i tipi di parametro vengono convalidati quando si crea il documento SSM. In tutti gli altri casi, la convalida dei parametri avviene durante l'esecuzione dell'automazione quando l'input di un'operazione viene verificato prima dell'esecuzione. Ad esempio, se il parametro di input è String e si fa riferimento ad esso come valore per l'input MaxInstanceCount dell'operazione aws:runInstances, viene creato il documento SSM. Tuttavia, quando si esegue il documento, l'automazione non riesce durante la convalida dell'operazione aws:runInstances perché l'input MaxInstanceCount richiede un valore Integer.

Di seguito sono riportati alcuni esempi di ciascun parametro type.

Stringa

Una sequenza di zero o più caratteri Unicode inclusa tra virgolette. Ad esempio, "i-1234567890abcdef0". Utilizza barre rovesciate come caratteri di escape.

YAML
---
InstanceId:
  type: String
  description: "(Optional) The target EC2 instance ID."
JSON
"InstanceId":{
  "type":"String",
  "description":"(Optional) The target EC2 instance ID."
}
StringList

Un elenco di elementi String separati da virgole. Ad esempio, ["cd ~", "pwd"].

YAML
---
commands:
  type: StringList
  description: "(Required) Specify a shell script or a command to run."
  default: ""
  minItems: 1
  displayType: textarea
JSON
"commands":{
  "type":"StringList",
  "description":"(Required) Specify a shell script or a command to run.",
  "minItems":1,
  "displayType":"textarea"
}
Booleano

Accetta solo true o false. Non accetta "true" o 0.

YAML
---
canRun:
  type: Boolean
  description: ''
  default: true
JSON
"canRun": {
  "type": "Boolean",
  "description": "",
  "default": true
}
Numero intero

Numeri interi. Non accetta numeri decimali, ad esempio 3,14159, o numeri inclusi tra virgolette, ad esempio "3".

YAML
---
timeout:
  type: Integer
  description: The type of action to perform.
  default: 100
JSON
"timeout": {
  "type": "Integer",
  "description": "The type of action to perform.",
  "default": 100    
}
StringMap

Mappatura di chiavi a valori. Le chiavi e i valori devono essere stringhe. Ad esempio, {"Env": "Prod"}.

YAML
---
notificationConfig:
  type: StringMap
  description: The configuration for events to be notified about
  default:
    NotificationType: 'Command'
    NotificationEvents:
    - 'Failed'
    NotificationArn: "$dependency.topicArn"
  maxChars: 150
JSON
"notificationConfig" : {
  "type" : "StringMap",
  "description" : "The configuration for events to be notified about",
  "default" : {
    "NotificationType" : "Command",
    "NotificationEvents" : ["Failed"],
    "NotificationArn" : "$dependency.topicArn"
  },
  "maxChars" : 150
}
MapList

Un elenco di oggetti. StringMap

YAML
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
JSON
"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
}

Visualizzazione del contenuto del documento Command SSM

Per visualizzare in anteprima i parametri obbligatori e facoltativi per un documento di comando AWS Systems Manager (SSM), oltre alle azioni eseguite dal documento, è possibile visualizzare il contenuto del documento nella console Systems Manager.

Per visualizzare il contenuto del documento Command SSM

  1. Aprire la AWS Systems Manager console all'indirizzo https://console.aws.amazon.com/systems-manager/.

  2. Nel riquadro di navigazione, scegli Documenti.

  3. Nella casella di ricerca selezionare Document type (Tipo di documento) e quindi selezionare Command (Comando).

  4. Scegliere il nome di un documento, quindi la scheda Content (Contenuto).

  5. Nel campo del contenuto esaminare i parametri e i passaggi delle operazioni disponibili per il documento.

    Ad esempio, l'immagine seguente mostra che (1) version e (2) allowDowngradesono parametri opzionali per il documento AWS-UpdateSSMAgent e che la prima operazione eseguita dal documento è (3) aws:updateSsmAgent.

    Visualizzare il contenuto dei documenti SSM nella console di Systems Manager