Datenelemente und Parameter - AWS Systems Manager

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 Management Console -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.

Für Parameter, die Sie häufig verwenden, empfehlen wir, diese Parameter in zu speichern Parameter Store, ein Tool in AWS Systems Manager. Anschließend können Sie in Ihrem Dokument Parameter definieren, auf die verwiesen wird Parameter Store Parameter als Standardwert. Um auf eine zu verweisen Parameter Store Verwenden Sie für den Parameter die folgende Syntax.

{{ssm:parameter-name}}

Sie können einen Parameter verwenden, der auf eine verweist Parameter Store Parameter auf die gleiche Weise wie alle anderen Dokumentparameter. Im folgenden Beispiel ist der Standardwert für den commands Parameter Parameter Store ParametermyShellCommands. 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 }}"] 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 }}" ] } } ] }
Anmerkung

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

Weitere Informationen zur Parameter Store, finden 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 auf einen Parameter 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 durchgeführt am SSM Agent indem Sie die GO-Regexp-Bibliothek verwenden, bevor Sie das Dokument verarbeiten.

    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: (Optional) Wird verwendet, um entweder a textfield oder a textarea in der anzuzeigen. AWS Management Consoletextfieldist 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.

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. Zum Beispiel, wenn Ihr Dokument ein neues erstellt AMI, Sie könnten "angebenCreateImage. 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.

YAML
--- InstanceId: type: String description: "(Optional) The target EC2 instance ID."
JSON
"InstanceId":{ "type":"String", "description":"(Optional) The target EC2 instance ID." }
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.