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

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, eine Fähigkeit von AWS Systems Manager. Anschließend können Sie Parameter in Ihrem Dokument definieren, auf die verweisen Parameter Store Parameter als Standardwert. Um auf eine zu verweisen Parameter Store Verwenden Sie die folgende Syntax. 

{{ssm:parameter-name}}

Sie können einen Parameter verwenden, der auf eine verweist Parameter Store Parameter auf die gleiche Weise wie bei allen anderen Dokumentparametern. 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 Parameters.

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 Parametertype 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 der API Ebene, auf der 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-Plug-In verwendet wird. Es wird nicht garantiert, dass Plug-Ins 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 dann mit dieser Ausgabe neue Instances in einer nachfolgenden Automatisierungsausführung 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 Automation-Runbook mit Anhang erstellen, geben Sie auch Anhangdateien mit der --attachments Option (für AWS CLI) oder Attachments (für API undSDK) an. Sie können den Dateispeicherort sowohl für lokale Dateien als auch für Dateien festlegen, die in Amazon Simple Storage Service (Amazon S3)-Buckets gespeichert sind. Weitere Informationen finden Sie unter Anhang in der AWS Systems Manager API Referenz.

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 Parametertype 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-Plug-ins kann der Typ eines Parameters innerhalb der Eingabe eines Plug-ins nicht dynamisch geändert werden. Beispielsweise können Sie nicht auf einen Integer-Parameter innerhalb der Eingabe runCommand des Plug-ins aws:runShellScript verweisen, da diese Eingabe eine Zeichenfolge oder eine Liste von Zeichenfolgen akzeptiert. Um einen Parameter für eine Plug-in-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 Plug-ins aws:updateSsmAgent angeben. Wenn der Parametertyp nicht mit dem Eingabetyp für ein Plug-in übereinstimmt, kann das SSM Dokument nicht validiert werden und das System erstellt das Dokument nicht. Das gilt auch bei Verwendung von Parametern in nachgelagerten Eingaben für andere Plug-Ins oder Aktionen von AWS Systems Manager Automation. Sie können beispielsweise keinen StringList-Parameter in der documentParameters-Eingabe des Plug-Ins 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 aws:runCommand Aktion verwenden, werden Parametertypen bei der Erstellung 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 Ihr Eingabeparameter beispielsweise a ist String und Sie ihn als Wert für die MaxInstanceCount Eingabe der aws:runInstances Aktion angeben, 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 Betriebs-Parameter für ein AWS Systems Manager (SSM) -Befehlsdokument sowie der Aktionen, die das Dokument ausführt, zu erhalten, können Sie 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 Documents (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 Manager-Konsole an.