Datenelemente und Parameter - AWS Systems Manager
Top-Level-DatenelementeBeispiele für den Parameter type in SSM-DokumentenInhalte von SSM-Befehlsdokument anzeigen

AWS Systems ManagerChange Managersteht neuen Kunden nicht mehr offen. Bestandskunden können den Service weiterhin wie gewohnt nutzen. Weitere Informationen finden Sie unter Änderung der AWS Systems ManagerChange Manager Verfügbarkeit.

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Datenelemente und Parameter

In diesem Thema werden die in SSM-Dokumenten verwendeten Datenelemente beschrieben. Die Schemaversion, die zum Erstellen eines Dokuments verwendet wird, definiert die Syntax und die Datenelemente, die das Dokument akzeptiert. Es wird empfohlen, Schema-Version 2.2 oder höher für Befehlsdokumente zu verwenden. Automation-Runbooks verwenden die Schema-Version 0.3. Automation-Runbooks unterstützen darüber hinaus die Verwendung von Markdown, einer Markup-Sprache, mit der Sie Wiki-Beschreibungen zu Dokumenten und einzelnen Schritten innerhalb des Dokuments hinzufügen können. Weitere Informationen zur Verwendung von Markdown finden Sie unter Verwenden von Markdown in der Konsole im AWS-Managementkonsole -Handbuch „Erste Schritte“.

Im folgenden Abschnitt werden die Datenelemente beschrieben, die Sie in ein SSM-Dokument aufnehmen können.

Top-Level-Datenelemente

schemaVersion

Die zu verwendende Schema-Version.

Typ: Version

Erforderlich: Ja

description

Von Ihnen angegebene Informationen, um den Zweck des Dokuments zu beschreiben. Sie können dieses Feld auch verwenden, um anzugeben, ob ein Parameter einen Wert für die Ausführung eines Dokuments benötigt oder ob die Bereitstellung eines Werts für den Parameter optional ist. Erforderliche und optionale Parameter sind in den Beispielen dieses Themas zu sehen.

Typ: Zeichenfolge

Erforderlich: Nein

Parameter

Eine Struktur, die die Parameter definiert, die das Dokument akzeptiert.

Um die Sicherheit bei der Verarbeitung von Zeichenfolgeparametern zu erhöhen, können Sie die Interpolation von Umgebungsvariablen verwenden, indem Sie die Eigenschaft interpolationType angeben. Wenn dies auf ENV_VAR gesetzt ist, wird eine Umgebungsvariable mit dem Namen SSM_parameter-name erstellt, die den Parameterwert enthält.

Das folgende Beispiel enthält einen Parameter mit der Umgebungsvariable 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}}"
            ]
        }
    }
}
Anmerkung

allowedPattern ist in SSD-Dokumenten streng genommen nicht erforderlich, wenn sie keine doppelten Klammern enthalten: {{ }}

Wir empfehlen, häufig verwendete Parameter in Parameter Store zu speichern, einem Tool in AWS Systems Manager. Anschließend können Sie Parameter in Ihrem Dokument definieren, die Parameter Store-Parameter als Standardwert referenzieren. Um auf einen Parameter Store-Parameter zu verweisen, verwenden Sie die folgende Syntax. 

{{ssm:parameter-name}}

Sie können einen Parameter, der auf einen Parameter Store-Parameter verweist, auf die gleiche Weise wie alle anderen Dokumentparameter verwenden. Im folgenden Beispiel ist der Standardwert für den commands-Parameter der Parameter Store-Parameter myShellCommands. Durch Angabe des commands-Parameters als runCommand-Zeichenfolge führt das Dokument die im myShellCommands-Parameter gespeicherten Befehle aus.

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 }}"],
            interpolationType : 'ENV_VAR'
            allowedPattern: '^[^"]*$'

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

Im parameters-Abschnitt Ihres Dokuments können Sie die -Parameter String und StringList Parameter Store referenzieren. Sie können nicht die Parameter SecureString Parameter Store referenzieren.

Mehr über Parameter Store erfahren Sie unter AWS Systems Manager Parameter Store.

Typ: Struktur

Die parameters-Struktur akzeptiert die folgenden Felder und Werte:

  • type: (Erforderlich) Zulässige Werte umfassen die Folgenden: String, StringList, Integer, Boolean, MapList und StringMap. Beispiele für jeden Typ finden Sie Beispiele für den Parameter type in SSM-Dokumenten im nächsten Abschnitt.

    Anmerkung

    Befehlstyp-Dokumente unterstützen nur die Parametertypen String und StringList.

  • description: (Optional) Eine Beschreibung der Parametergruppe.

  • default: (Optional) Der Standardwert des Parameters oder eine Referenz bezüglich eines Parameters in Parameter Store.

  • allowedValues: (Optional) Ein Array von Werten, die für den Parameter zulässig sind. Durch das Definieren zulässiger Werte für den Parameter wird die Benutzereingabe überprüft. Wenn ein Benutzer einen Wert eingibt, der nicht zulässig ist, kann die Ausführung nicht gestartet werden.

    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: (Optional) Ein regulärer Ausdruck, der überprüft, ob die Benutzereingabe mit dem definierten Muster für den Parameter übereinstimmt. Wenn die Benutzereingabe nicht mit dem zulässigen Muster übereinstimmt, kann die Ausführung nicht gestartet werden.

    Anmerkung

    Systems Manager führt zwei Validierungen für allowedPattern aus. Die erste Validierung erfolgt unter Verwendung der Java regex library (Java-Regex-Bibliothek) auf API-Ebene, wenn Sie ein Dokument verwenden. Die zweite Validierung wird am SSM Agent ausgeführt, indem Sie die GO regexp library (GO-regexp-Bibliothek) verwenden, bevor Sie das Dokument bearbeiten.

    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: (Optional) Wird verwendet, um entweder a textfield oder a textarea in der anzuzeigen AWS-Managementkonsole. textfieldist ein einzeiliges Textfeld. textareaist ein mehrzeiliger Textbereich.

  • minItems: (Optional) Die minimal zulässige Anzahl von Elementen.

  • maxItems: (Optional) Die maximal zulässige Anzahl von Elementen.

  • minChars: (Optional) Die minimal zulässige Anzahl an Parameterzeichen.

  • maxChars: (Optional) Die maximal zulässige Anzahl an Parameterzeichen.

  • interpolationType: (Optional) Definiert, wie Parameterwerte vor der Befehlsausführung verarbeitet werden. Wenn dies auf ENV_VAR gesetzt ist, wird der Parameterwert als Umgebungsvariable mit dem Namen SSM_parameter-name verfügbar gemacht. Dieses Feature trägt dazu bei, die Einschleusung von Befehlen zu verhindern, da Parameterwerte als Literalzeichenfolgen behandelt werden.

    Typ: Zeichenfolge

    Zulässige Werte: ENV_VAR

Erforderlich: Nein

variables

(Nur Schemaversion 0.3) Werte, auf die Sie während der einzelnen Schritte in einem Automation-Runbook verweisen oder diese aktualisieren können. Variablen ähneln Parametern, unterscheiden sich jedoch in einem sehr wichtigen Punkt. Parameterwerte sind im Kontext eines Runbooks statisch, aber die Werte von Variablen können im Kontext des Runbooks geändert werden. Beim Aktualisieren des Werts einer Variable muss der Datentyp dem definierten Datentyp entsprechen. Hinweise zum Aktualisieren von Variablenwerten in einer Automatisierung finden Sie unter aws:updateVariable – Aktualisiert einen Wert für eine Runbook-Variable.

Typ: Boolean | Integer | | Zeichenfolge | MapList | StringList StringMap

Erforderlich: Nein

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

(Nur für Schemaversion 1.2) Die Konfiguration für die Instance, wie sie von mindestens einem Systems Manager-Plugin verwendet wird. Es wird nicht garantiert, dass Plugins nacheinander ausgeführt werden.

Typ: Dictionary<String, > PluginConfiguration

Erforderlich: Nein

mainSteps

(Nur Schema-Version 0.3, 2.0 und 2.2) Ein Objekt, das mehrere Schritte (Plugins) enthalten kann. Plugins werden innerhalb von Schritten definiert. Die Schritte werden in der Reihenfolge ausgeführt, in der sie im Dokument aufgeführt sind.

Typ: Dictionary<String, > PluginConfiguration

Erforderlich: Ja

outputs

(Nur Schema-Version 0.3) Daten, die durch die Ausführung dieses Dokuments generiert werden, die in anderen Prozessen verwendet werden können. Wenn Ihr Dokument beispielsweise ein neues erstelltAMI, können Sie "angeben. CreateImage ImageId"als Ausgabewert und verwenden Sie diese Ausgabe dann, um in einer nachfolgenden Automatisierungsausführung neue Instanzen zu erstellen. Weitere Informationen zu Ausgaben finden Sie unter Verwenden von Aktionsausgaben als Eingaben.

Geben Sie ein: Dictionary<String, > OutputConfiguration

Erforderlich: Nein

files

(Nur Schema-Version 0.3) Die Skriptdateien (und ihre Prüfsummen), die dem Dokument zugeordnet sind und während einer Automatisierungsausführung ausgeführt werden. Gilt nur für Dokumente, die die aws:executeScript Aktion enthalten und für die Anfügungen in einem oder mehreren Schritten angegeben wurden.

Weitere Informationen zu den von Automation-Runbooks unterstützten Laufzeiten finden Sie unter aws:executeScript - Führen Sie ein Skript aus. Weitere Informationen zum Einbinden von Skripten in Automation-Runbooks finden Sie unter Verwenden von Skripten in Runbooks und Visuelle Designerfahrung für Automation-Runbooks.

Wenn Sie ein Automatisierungs-Runbook mit Anlagen erstellen, müssen Sie auch Anhangsdateien mit der --attachments Option (für AWS CLI) oder Attachments (für API und SDK) angeben. Sie können den Dateispeicherort für SSM-Dokumente und Dateien angeben, die in Amazon Simple Storage Service (Amazon S3)-Buckets gespeichert sind. Weitere Informationen finden Sie in der AWS Systems Manager API-Referenz unter Anlagen.

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

Geben Sie ein: Dictionary<String, > FilesConfiguration

Erforderlich: Nein

Beispiele für den Parameter type in SSM-Dokumenten

Parametertypen in SSM-Dokumenten sind statisch. Dies bedeutet, dass der Parametertyp nicht geändert werden kann, nachdem er definiert wurde. Bei der Verwendung von Parametern mit SSM-Dokumenten-Plugins kann der Typ eines Parameters innerhalb der Eingabe eines Plugins nicht dynamisch geändert werden. Beispielsweise können Sie nicht auf einen Integer-Parameter innerhalb der Eingabe runCommand des Plugins aws:runShellScript verweisen, da diese Eingabe eine Zeichenfolge oder eine Liste von Zeichenfolgen akzeptiert. Um einen Parameter für eine Plugin-Eingabe verwenden zu können, muss der Parametertyp mit dem akzeptierten Typ übereinstimmen. Sie müssen beispielsweise einen Parameter des Typs Boolean für die Eingabe allowDowngrade des Plugins aws:updateSsmAgent angeben. Wenn der Parametertyp nicht mit dem Eingabetyp für ein Plugin übereinstimmt, kann das SSM-Dokument nicht validiert werden und das System erstellt das Dokument nicht. Dies gilt auch, wenn Parameter nachgeschaltet in Eingaben für andere Plugins oder Automatisierungsaktionen verwendet werden. AWS Systems Manager Sie können beispielsweise keinen StringList-Parameter in der documentParameters-Eingabe des Plugins aws:runDocument referenzieren. Die documentParameters-Eingabe akzeptiert eine Zuordnung von Zeichenfolgen, auch wenn der nachgelagerte Parametertyp des SSM-Dokuments ein StringList-Parameter ist und dem referenzierten Parameter entspricht.

Wenn Sie Parameter mit -Automation-Aktionen verwenden, werden Parametertypen bei der Erstellung des SSM-Dokuments in den meisten Fällen nicht validiert. Nur wenn Sie die Aktion aws:runCommand verwenden, werden Parametertypen bei der Erstellen des SSM-Dokuments validiert. In allen anderen Fällen erfolgt die Parametervalidierung während der Automatisierungsausführung, wenn die Eingabe einer Aktion überprüft wird, bevor die Aktion ausgeführt wird. Wenn der Eingabeparameter beispielsweise ein String ist und Sie auf ihn als Wert für die Eingabe MaxInstanceCount der Aktion aws:runInstances verweisen, wird das SSM-Dokument erstellt. Beim Ausführen des Dokuments schlägt die Automatisierung jedoch fehl, wenn die Aktion aws:runInstances validiert wird, da für die Eingabe MaxInstanceCount ein Integer erforderlich ist.

Im Folgenden finden Sie für jeden Parametertype ein Beispiel.

String

Eine Abfolge von null oder mehr Unicode-Zeichen in Anführungszeichen. Zum Beispiel „i-1234567890abcdef0“. Verwenden Sie umgekehrte Schrägstriche als Escapezeichen.

Zeichenfolgeparameter können ein optionales interpolationType-Feld mit dem Wert ENV_VAR enthalten, um die Interpolation von Umgebungsvariablen zu ermöglichen und so die Sicherheit zu erhöhen.

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

Eine Liste von String-Elementen, die durch Kommas getrennt sind. Zum Beispiel ["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"
}
Boolesch

Akzeptiert nur true oder false. Akzeptiert nicht „true“ oder 0.

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

Ganze Zahlen. Akzeptiert keine Dezimalzahlen, z. B. 3,14159, oder Zahlen in Anführungszeichen, z. B. „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

Ein Mapping von Schlüsseln zu Werten. Schlüssel und Werte müssen Zeichenfolgen sein. Zum Beispiel {"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

Eine Liste von StringMap Objekten.

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
}

Inhalte von SSM-Befehlsdokument anzeigen

Um eine Vorschau der erforderlichen und optionalen Parameter für ein AWS Systems Manager (SSM-) Befehlsdokument anzuzeigen, können Sie zusätzlich zu den Aktionen, die das Dokument ausführt, den Inhalt des Dokuments in der Systems Manager Manager-Konsole anzeigen.

Inhalte von SSM-Befehlsdokument anzeigen

  1. Öffnen Sie die AWS Systems Manager Konsole unter. https://console.aws.amazon.com/systems-manager/

  2. Wählen Sie im Navigationsbereich die Option Dokumente aus.

  3. Wählen Sie im Suchfeld Dokumenttyp und wählen Sie danach Befehl.

  4. Wählen Sie den Namen eines Dokuments und dann die Registerkarte Content (Inhalt) aus.

  5. Überprüfen Sie im Inhaltsfeld die verfügbaren Parameter und Aktionsschritte für das Dokument.

    Das folgende Image zeigt beispielsweise, dass (1) version und (2) allowDowngrade optionale Parameter für das AWS-UpdateSSMAgent-Dokument sind, und dass die erste Aktion, die vom Dokument ausgeführt wird, (3) aws:updateSsmAgent ist.

    Zeigen Sie SSM-Dokumentinhalte in der Systems Manager-Konsole an.