Éléments de données et paramètres - AWS Systems Manager
Éléments de données niveau supérieurExemples de paramètres type de document SSMAffichage du contenu du document SSM Command

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Éléments de données et paramètres

Cette rubrique décrit les éléments de données utilisés dans les documents SSM. La version du schéma utilisée pour créer un document définit la syntaxe et les éléments de données que le document accepte. Nous vous recommandons l'utilisation de la version de schéma 2.2 ou celle ultérieure pour les documents de Commande. Les runbooks Automation utilisent la version de schéma 0.3. De plus, les runbooks Automation prennent en charge l'utilisation de Markdown, un langage de balisage, qui vous permet d'ajouter des descriptions de style wiki aux documents et des étapes individuelles au sein du document. Pour plus d'informations relatives à l'utilisation de Markdown, consultez Utilisation de Markdown dans la console dans le Guide de mise en route AWS Management Console .

La section suivante décrit les éléments de données pouvant être inclut dans un document SSM.

Éléments de données niveau supérieur

schemaVersion

Version de schéma à utiliser.

Type : Version

Obligatoire : oui

description

Informations que vous fournissez pour décrire l'objectif du document. Vous pouvez également utiliser ce champ pour spécifier si un paramètre nécessite une valeur pour qu'un document s'exécute ou si la fourniture d'une valeur pour le paramètre est facultative. Les paramètres obligatoires et facultatifs peuvent être consultés dans les exemples de cette rubrique.

Type : chaîne

Obligatoire : non

parameters

Structure qui définit les paramètres acceptés par le document.

Pour les paramètres que vous utilisez souvent, nous vous recommandons de les stocker dans Parameter Store une fonctionnalité de AWS Systems Manager. Ensuite, définissez les paramètres de votre document faisant référence aux paramètres Parameter Store comme valeur par défaut. Pour référencer un paramètre Parameter Store, utilisez la syntaxe suivante. 

{{ssm:parameter-name}}

Utilisez un paramètre faisant référence à un paramètre Parameter Store similaire à tout autre paramètre du document. Dans l'exemple suivant, la valeur par défaut du paramètre commands est le paramètre Parameter Store myShellCommands. En spécifiant le paramètre commands en tant que chaîne runCommand, le document exécute les commandes stockées dans le paramètre 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 }}"
          ]
        }
      }
    ]
  }
Note

Vous pouvez référencer les paramètres String et StringList Parameter Store dans la section parameters d'un document. Vous ne pouvez pas référencer les paramètres Parameter Store SecureString.

Pour plus d’informations sur Parameter Store, consultez AWS Systems Manager Parameter Store.

Type : Structure

La structure parameters accepte les champs et valeurs suivants :

  • type : (Obligatoire) les valeurs autorisées sont : String, StringList, Integer, Boolean, MapList et StringMap. Pour consulter des exemples de chaque type, consultez Exemples de paramètres type de document SSM dans la section suivante.

    Note

    Les documents de type Command ne prennent en charge que les types de paramètres String et StringList.

  • description : (Facultatif) Description du paramètre.

  • default : (Facultatif) Valeur par défaut du paramètre ou référence à un paramètre dans Parameter Store.

  • allowedValues : (facultatif) tableau de valeurs autorisées pour le paramètre. La définition des valeurs autorisées pour le paramètre valide l'entrée utilisateur. Si un utilisateur saisit une valeur non autorisée, l'exécution échoue.

    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 : (facultatif) expression régulière qui valide si l'entrée utilisateur correspond au modèle défini pour le paramètre. Si l'entrée utilisateur ne correspond pas au modèle autorisé, l'exécution échoue.

    Note

    Systems Manager effectue deux validations pour allowedPattern. La première validation est effectuée à l'aide de la bibliothèque Java regex au niveau de l'API lorsque vous utilisez un document. La deuxième validation est effectuée sur SSM Agent en utilisant la bibliothèque Go regexpavant de traiter le document.

    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: (Facultatif) Utilisé pour afficher un textfield ou un textarea dans le AWS Management Console. textfieldest une zone de texte d'une seule ligne. textareaest une zone de texte multiligne.

  • minItems : (Facultatif) Nombre minimum d'éléments autorisés.

  • maxItems : (Facultatif) Nombre maximum d'éléments autorisés.

  • minChars : (Facultatif) Nombre minimum d'éléments autorisés.

  • maxChars : (Facultatif) Nombre maximum de caractères de paramètre autorisés.

Obligatoire : non

variables

(Schéma version 0.3 uniquement) Valeurs que vous pouvez référencer ou mettre à jour tout au long des étapes d’un runbook d’Automation. Les variables sont similaires aux paramètres, mais diffèrent d’une manière très importante. Les valeurs des paramètres sont statiques dans le contexte d’un runbook, mais les valeurs des variables peuvent être modifiées dans le contexte du runbook. Lors de la mise à jour de la valeur d’une variable, le type de données doit correspondre au type de données défini. Pour plus d’informations sur la mise à jour des valeurs de variables dans une automatisation, veuillez consulter aws:updateVariable : met à jour la valeur d’une variable runbook.

Type : booléen | Entier | | Chaîne MapList | | StringList StringMap

Obligatoire : non

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

(Version de schéma 1.2 seulement) Configuration de l'instance telle qu'appliquée par un ou plusieurs plugins Systems Manager. L'exécution en séquence des plugins n'est pas garantie.

Type : Dictionnaire<String, > PluginConfiguration

Obligatoire : non

mainSteps

(Version de schéma 0.3, 2.0 et 2.2 uniquement) Objet pouvant inclure plusieurs étapes (plug-ins). Les plug-ins sont définis en étapes. Les étapes s'exécutent par ordre séquentiel telles que listées dans le document.

Type : Dictionnaire<String, > PluginConfiguration

Obligatoire : oui

outputs

(Version de schéma 0.3 uniquement) Données générées par l'exécution de ce document pouvant être utilisées dans d'autres processus. Par exemple, si votre document en crée un nouveauAMI, vous pouvez spécifier « »CreateImage. ImageId« comme valeur de sortie, puis utilisez cette sortie pour créer de nouvelles instances lors d'une exécution d'automatisation ultérieure. Pour plus d'informations sur les sorties, consultez Utilisation des sorties d'action comme entrées.

Type : Dictionnaire<String, > OutputConfiguration

Obligatoire : non

files

(Version de schéma 0.3 uniquement) Les fichiers de script (et leurs sommes de contrôle) attachés au document et exécutés lors d'une exécution Automation. S'applique uniquement aux documents qui incluent l'action aws:executeScript et pour lesquels des pièces jointes ont été spécifiées dans une ou plusieurs étapes.

Pour la prise en charge de l'exécution des scripts, les runbooks Automation prennent en charge les scripts pour Python 3.7, Python 3.8, PowerShell Core 6.0 et PowerShell 7.0. Pour de plus amples informations sur l'inclusion de scripts dans les runbooks Automation, veuillez consulter Utilisation de scripts dans des runbooks et Créer des runbooks à l'aide de Document Builder.

Lorsque vous créez un runbook d'automatisation avec des pièces jointes, vous devez également spécifier les fichiers joints à l'aide de l'--attachmentsoption (pour AWS CLI) ou Attachments (pour l'API et le SDK). Vous pouvez spécifier l'emplacement du fichier tant pour les fichiers locaux que pour les fichiers stockés dans des compartiments Amazon Simple Storage Service (Amazon S3). Pour plus d'informations, consultez la section Pièces jointes dans le Guide de référence de AWS Systems Manager l'API.

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

Type : Dictionnaire<String, > FilesConfiguration

Obligatoire : non

Exemples de paramètres type de document SSM

Les types de paramètres des documents SSM sont statiques. Cela signifie que le type de paramètre ne peut pas être modifié après avoir été défini. Lorsque vous utilisez des paramètres avec des plugins de document SSM, le type d'un paramètre ne peut pas être modifié dynamiquement dans l'entrée d'un plugin. Par exemple, vous ne pouvez pas référencer un paramètre Integer dans l'entrée runCommand du plugin aws:runShellScript, car cette entrée accepte une chaîne ou une liste de chaînes. Pour utiliser un paramètre pour une entrée de plugin, le type de paramètre doit correspondre au type accepté. Par exemple, vous devez spécifier un type de paramètre Boolean pour l'entrée allowDowngrade du plugin aws:updateSsmAgent. Si votre type de paramètre ne correspond pas au type d'entrée d'un plugin, le document SSM n'est pas validé et le système ne crée pas le document. Cela est également vrai lorsque vous utilisez des paramètres en aval dans les entrées pour d'autres plugins ou actions AWS Systems Manager d'automatisation. Par exemple, vous ne pouvez pas référencer un paramètre StringList dans l'entrée documentParameters du plugin aws:runDocument. L'entrée documentParameters accepte une carte de chaînes même si le type de paramètre de document SSM en aval est un paramètre StringList et correspond au paramètre auquel vous faites référence.

Lorsque vous utilisez des paramètres avec des actions Automation, dans la plupart des cas les types de paramètres ne sont pas validés lorsque vous créez le document SSM. Ce n'est que lorsque vous utilisez l'action aws:runCommand que les types de paramètres sont validés lors de la création du document SSM. Dans tous les autres cas, la validation des paramètres se produit pendant l'exécution d'automatisation lorsque l'entrée d'une action est vérifiée avant d'exécuter cette dernière. Par exemple, si votre paramètre d'entrée est une String et que vous le référencez comme valeur pour l'entrée MaxInstanceCount de l'action aws:runInstances, le document SSM est créé. Toutefois, lors de l'exécution du document, l'automatisation échoue lors de la validation de l'action aws:runInstances, car l'entrée MaxInstanceCount nécessite un Integer.

Voici des exemples de chaque type de paramètre.

Chaîne

Une séquence de zéro ou plusieurs caractères Unicode entre guillemets. Par exemple, « i-1234567890abcdef0". Utilisez des barres obliques inverses comme caractères d'échappement.

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

Liste d'éléments String séparés par des virgules. Par exemple, ["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"
}
Booléen

Accepte uniquement true ou false. N'accepte pas la valeur « true », ni 0.

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

Nombres entiers. N'accepte pas de nombres décimaux, par exemple 3,14159, ni de nombres entre guillemets, par exemple « 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

Mappage de clés à des valeurs. Les clés et les valeurs doivent être des chaînes. Par exemple, {"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

Liste d' StringMap objets.

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
}

Affichage du contenu du document SSM Command

Pour prévisualiser les paramètres obligatoires et facultatifs d'un document de commande AWS Systems Manager (SSM), outre les actions exécutées par le document, vous pouvez consulter le contenu du document dans la console Systems Manager.

Pour afficher le contenu d'un document SSM Command

  1. Ouvrez la AWS Systems Manager console à l'adresse https://console.aws.amazon.com/systems-manager/.

  2. Dans le panneau de navigation, cliquez sur Documents.

  3. Dans la zone de recherche, sélectionnez Type de document, puis sélectionnez Command.

  4. Sélectionnez le nom d'un document, puis l'onglet Content (Contenu).

  5. Dans le champ Contenu, vérifiez les paramètres disponibles et les étapes d'action du document.

    Par exemple, l'image suivante montre que (1) version et (2) allowDowngrade sont des paramètres facultatifs pour le document AWS-UpdateSSMAgent, et que la première action exécutée par le document est (3) aws:updateSsmAgent.

    Afficher le contenu d'un document SSM dans la console Systems Manager