Bereich "Parameters"Bereich „Ressourcen“Vorlagenbeispiel für eine Massenregistrierung Beispiel für eine Vorlage für die just-in-time Bereitstellung (JITP)Flottenbereitstellung

Bereitstellen von Vorlagen

Eine Bereitstellungsvorlage ist ein JSON-Dokument, das Parameter verwendet, um die Ressourcen zu beschreiben, mit denen Ihr Gerät interagieren muss. AWS IoT Eine Bereitstellungsvorlage besteht aus zwei Abschnitten: Parameters und Resources. Es gibt zwei Arten von Bereitstellungsvorlagen in. AWS IoT Eine wird für die just-in-time Bereitstellung (JITP) und die Massenregistrierung verwendet, die zweite für die Flottenbereitstellung.

Themen

Bereich "Parameters"
Bereich „Ressourcen“
Vorlagenbeispiel für eine Massenregistrierung
Beispiel für eine Vorlage für die just-in-time Bereitstellung (JITP)
Flottenbereitstellung

Bereich "Parameters"

Der Abschnitt Parameters deklariert die im Abschnitt Resources verwendeten Parameter. Jeder Parameter deklariert einen Namen, einen Typ und einen optionalen Standardwert. Der Standardwert wird verwendet, wenn das mit der Vorlage eingegebene Lexikon keinen Wert für den Parameter enthält. Der Abschnitt Parameters eines Vorlagendokuments sieht wie folgt aus:


{
    "Parameters" : {
        "ThingName" : {
            "Type" : "String"
        },
        "SerialNumber" : {
            "Type" : "String"
        },
        "Location" : {
            "Type" : "String",
            "Default" : "WA"
        },
        "CSR" : {
            "Type" : "String"    
        }
    }
}

Dieses Vorlagentextfragment deklariert vier Parameter: ThingName, SerialNumber, Location und CSR. Alle diese Parameter sind vom Typ String. Der Parameter Location deklariert den Standardwert "WA".

Bereich „Ressourcen“

Im Resources Abschnitt des Vorlagentexts werden die Ressourcen deklariert, die für die Kommunikation Ihres Geräts erforderlich sind AWS IoT: eine Sache, ein Zertifikat und eine oder mehrere IoT-Richtlinien. Jede Ressource gibt einen logischen Namen, einen Typ und eine Reihe von Eigenschaften an.

Ein logischer Name ermöglicht den Verweis auf eine Ressource an einer anderen Stelle in der Vorlage.

Der Typ gibt die Art der Ressource an, die Sie deklarieren. Gültige Typen sind:

AWS::IoT::Thing
AWS::IoT::Certificate
AWS::IoT::Policy

Die Eigenschaften, die Sie angeben, hängen vom Typ der Ressource ab, die Sie deklarieren.

Objektressourcen

Objekt-Ressourcen werden mit den folgenden Eigenschaften deklariert:

ThingName: Zeichenfolge.
AttributePayload: Optional. Eine Liste von Name-Wert-Paaren.
ThingTypeName: Optional. Zeichenfolge für einen zugehörigen Objekttyp für das Objekt.
ThingGroups: Optional. Eine Liste der Gruppen, zu der das Objekt gehört.
BillingGroup: Optional. Zeichenfolge für den Namen einer zugehörigen Fakturierungsgruppe.
PackageVersions: Optional. Zeichenfolge für ein zugeordnetes Paket und Versionsnamen.

Zertifikatressourcen

Sie können Zertifikate auf eine der folgenden Arten angeben:

Eine Zertifikatssignierungsanforderung (Certificate Signing Request, CSR).
Eine Zertifikat-ID eines vorhandenen Geräte-Zertifikats. (Nur Zertifikats-IDs können mit einer Flottenbereitstellungsvorlage verwendet werden.)
Ein Geräte-Zertifikat mit einem für AWS IoT registrierten CA-Zertifikat. Wenn Sie über mehr als ein mit demselben Themafeld registriertes CA-Zertifikat verfügen, müssen Sie auch das verwendete CA-Zertifikat eingeben, um das Geräte-Zertifikat zu signieren.

Anmerkung

Wenn Sie ein Zertifikat in einer Vorlage deklarieren, verwenden Sie nur eine dieser Methoden. Wenn Sie z. B. eine Zertifikatsignierungsanforderung (CSR) verwenden, können Sie nicht auch eine Zertifikat-ID oder ein Geräte-Zertifikat angeben. Weitere Informationen finden Sie unter X.509-Clientzertifikate.

Weitere Informationen finden Sie unter Übersicht zum X.509-Zertifikat.

Zertifikat-Ressourcen werden mit den folgenden Eigenschaften deklariert:

CertificateSigningRequest: Zeichenfolge.
CertificateId: Zeichenfolge.
CertificatePem: Zeichenfolge.
CACertificatePem: Zeichenfolge.
Status: Optional. Zeichenfolge, die ACTIVE oder INACTIVE sein kann. Der Standardwert ist ACTIVE.

Beispiele:

Zertifikat, das mit einer Zertifikatsignierungsanforderung (CSR) angegeben wird:


{
    "certificate" : {
        "Type" : "AWS::IoT::Certificate",
        "Properties" : {
            "CertificateSigningRequest": {"Ref" : "CSR"},
            "Status" : "ACTIVE"      
        }
    }
}

Zertifikat, das mit einer vorhandenen Zertifikat-ID angegeben wird:


{
    "certificate" : {
        "Type" : "AWS::IoT::Certificate",
        "Properties" : {
            "CertificateId": {"Ref" : "CertificateId"}
        }
    }
}

Zertifikat, das mit der PEM-Datei eines vorhandenen Zertifikats und der PEM-Datei einer vorhandenen Zertifizierungsstelle angegeben wird:


{
    "certificate" : {
        "Type" : "AWS::IoT::Certificate",
        "Properties" : {
            "CACertificatePem": {"Ref" : "CACertificatePem"},
            "CertificatePem": {"Ref" : "CertificatePem"}
        }
    }
}

Richtlinienressourcen

Richtlinien-Ressourcen werden mit einer der folgenden Eigenschaften deklariert:

PolicyName: Optional. Zeichenfolge. Standardmäßig eine Prüfsumme des Richtliniendokuments. PolicyName kann nur auf AWS IoT -Richtlinien verweisen, nicht jedoch auf IAM-Richtlinien. Wenn Sie eine bestehende AWS IoT Richtlinie verwenden, geben Sie für die PolicyName Eigenschaft den Namen der Richtlinie ein. Verwenden Sie nicht die Eigenschaft PolicyDocument.
PolicyDocument: Optional. Ein JSON-Objekt, das als Zeichenfolge mit Escapezeichen angegeben wird. Wenn PolicyDocument nicht angegeben wird, muss die Richtlinie bereits erstellt worden sein.

Anmerkung

Wenn ein Policy-Abschnitt vorhanden ist, muss PolicyName oder PolicyDocument, nicht aber beide, angegeben werden.

Überschreibungseinstellungen

Wenn eine Vorlage eine Ressource angibt, die bereits vorhanden ist, ermöglicht der Abschnitt OverrideSettings die Angabe der durchzuführenden Aktion:

DO_NOTHING: Die Ressource unverändert lassen
REPLACE: Die Ressource durch die in der Vorlage angegebene Ressource ersetzen.
FAIL: Die Anfrage mit einer ResourceConflictsException fehlschlagen lassen.
MERGE: Dies gilt nur für die Eigenschaften ThingGroups und AttributePayload eines thing. Kombinieren der vorhandenen Attribute oder Gruppenmitgliedschaften des Objekts mit denjenigen, die in der Vorlage spezifiziert sind.

Wenn Sie eine Ding-Ressource deklarieren, können Sie OverrideSettings für die folgenden Eigenschaften angeben:

ATTRIBUTE_PAYLOAD
THING_TYPE_NAME
THING_GROUPS

Wenn Sie eine Zertifikat-Ressource deklarieren, können Sie OverrideSettings für die Status-Eigenschaft angeben.

OverrideSettings stehen nicht für Richtlinienressourcen zur Verfügung.

Ressourcenbeispiel

Das folgende Vorlagenfragment deklariert ein Objekt, ein Zertifikat und eine Richtlinie:


{ 
    "Resources" : {
        "thing" : {
            "Type" : "AWS::IoT::Thing",
            "Properties" : {
                "ThingName" : {"Ref" : "ThingName"},
                "AttributePayload" : { "version" : "v1", "serialNumber" :  {"Ref" : "SerialNumber"}}, 
                "ThingTypeName" :  "lightBulb-versionA",
                "ThingGroups" : ["v1-lightbulbs", {"Ref" : "Location"}]
            },
            "OverrideSettings" : {
                "AttributePayload" : "MERGE",
                "ThingTypeName" : "REPLACE",
                "ThingGroups" : "DO_NOTHING"
            }
        },  
        "certificate" : {
            "Type" : "AWS::IoT::Certificate",
            "Properties" : {
                "CertificateSigningRequest": {"Ref" : "CSR"},
                "Status" : "ACTIVE"      
            }
        },
        "policy" : {
            "Type" : "AWS::IoT::Policy",
            "Properties" : {
                "PolicyDocument" : "{ \"Version\": \"2012-10-17\", \"Statement\": [{ \"Effect\": \"Allow\", \"Action\":[\"iot:Publish\"], \"Resource\": [\"arn:aws:iot:us-east-1:123456789012:topic/foo/bar\"] }] }"
            }
        }
    }
}

Das Objekt wird deklariert mit:

Dem logischen Namen "thing".
Dem Typ AWS::IoT::Thing.
Einer Reihe von Objekteigenschaften.

Zu den Objekteigenschaften gehören der Name des Objekts, eine Reihe von Attributen, ein optionaler Name für den Objekttyp sowie eine optionale Liste von Objektgruppen, zu denen das Objekt gehört.

Parameter werden von {"Ref":"parameter-name"} referenziert. Wenn die Vorlage evaluiert wird, werden die Parameter durch den Parameterwert aus dem mit der Vorlage eingegebenen Lexikon ersetzt.

Das Zertifikat wird deklariert mit:

Dem logischen Namen "certificate".
Dem Typ AWS::IoT::Certificate.
Einer Reihe von Eigenschaften.

Zu den Eigenschaften gehören die CSR für das Zertifikat und die Einstellung des Status auf ACTIVE. Der CSR-Text wird als Parameter in das mit der Vorlage eingegebene Lexikon eingegeben.

Die Richtlinie wird deklariert mit:

Dem logischen Namen "policy".
Dem Typ AWS::IoT::Policy.
Dem Namen einer vorhandenen Richtlinie oder dem Richtliniendokument.

Vorlagenbeispiel für eine Massenregistrierung

Die folgende JSON-Datei ist ein Beispiel für eine vollständige Bereitstellungsvorlage, die das Zertifikat mit einer Zertifikatsignierungsanforderung angibt:

(Der Feldwert PolicyDocument muss ein JSON-Objekt sein, da als Zeichenfolge mit Escapezeichen angegeben wird.)


{
    "Parameters" : {
        "ThingName" : {
            "Type" : "String"
        },
        "SerialNumber" : {
            "Type" : "String"
        },
        "Location" : {
            "Type" : "String",
            "Default" : "WA"
        },
        "CSR" : {
            "Type" : "String"    
        }
    },
    "Resources" : {
        "thing" : {
            "Type" : "AWS::IoT::Thing",
            "Properties" : {
                "ThingName" : {"Ref" : "ThingName"},
                "AttributePayload" : { "version" : "v1", "serialNumber" :  {"Ref" : "SerialNumber"}}, 
                "ThingTypeName" :  "lightBulb-versionA",
                "ThingGroups" : ["v1-lightbulbs", {"Ref" : "Location"}]
            }
        },
        "certificate" : {
            "Type" : "AWS::IoT::Certificate",
            "Properties" : {
                "CertificateSigningRequest": {"Ref" : "CSR"},
                "Status" : "ACTIVE"      
            }
        },
        "policy" : {
            "Type" : "AWS::IoT::Policy",
            "Properties" : {
                "PolicyDocument" : "{ \"Version\": \"2012-10-17\", \"Statement\": [{ \"Effect\": \"Allow\", \"Action\":[\"iot:Publish\"], \"Resource\": [\"arn:aws:iot:us-east-1:123456789012:topic/foo/bar\"] }] }"
            }
        }
    }
}

Beispiel für eine Vorlage für die just-in-time Bereitstellung (JITP)

Die folgende JSON-Datei ist ein Beispiel für eine vollständige Bereitstellungsvorlage, die ein vorhandenes Zertifikat mit einer Zertifikat-ID angibt:


{
   "Parameters":{
      "AWS::IoT::Certificate::CommonName":{
         "Type":"String"
      },
      "AWS::IoT::Certificate::SerialNumber":{
         "Type":"String"
      },
      "AWS::IoT::Certificate::Country":{
         "Type":"String"
      },
      "AWS::IoT::Certificate::Id":{
         "Type":"String"
      }
   },
   "Resources":{
      "thing":{
         "Type":"AWS::IoT::Thing",
         "Properties":{
            "ThingName":{
               "Ref":"AWS::IoT::Certificate::CommonName"
            },
            "AttributePayload":{
               "version":"v1",
               "serialNumber":{
                  "Ref":"AWS::IoT::Certificate::SerialNumber"
               }
            },
            "ThingTypeName":"lightBulb-versionA",
            "ThingGroups":[
               "v1-lightbulbs",
               {
                  "Ref":"AWS::IoT::Certificate::Country"
               }
            ]
         },
         "OverrideSettings":{
            "AttributePayload":"MERGE",
            "ThingTypeName":"REPLACE",
            "ThingGroups":"DO_NOTHING"
         }
      },
      "certificate":{
         "Type":"AWS::IoT::Certificate",
         "Properties":{
            "CertificateId":{
               "Ref":"AWS::IoT::Certificate::Id"
            },
            "Status":"ACTIVE"
         }
      },
      "policy":{
         "Type":"AWS::IoT::Policy",
         "Properties":{
            "PolicyDocument":"{ \"Version\": \"2012-10-17\", \"Statement\": [{ \"Effect\": \"Allow\", \"Action\":[\"iot:Publish\"], \"Resource\": [\"arn:aws:iot:us-east-1:123456789012:topic/foo/bar\"] }] }"
         }
      }
   }
}

Wichtig

Sie müssen CertificateId in einer Vorlage verwenden, die für die JIT-Bereitstellung verwendet wird.

Weitere Informationen zum Typ einer Bereitstellungsvorlage finden Sie CreateProvisioningTemplatein der AWS API-Referenz.

Weitere Informationen zur Verwendung dieser Vorlage für die just-in-time Bereitstellung finden Sie unter: Just-in-Time-Bereitstellung.

Flottenbereitstellung

Vorlagen für die Flottenbereitstellung werden von verwendet, AWS IoT um die Cloud- und Gerätekonfiguration einzurichten. Diese Vorlagen verwenden dieselben Parameter und Ressourcen wie die JITP- und Massenregistrierungsvorlagen. Weitere Informationen finden Sie unter Bereitstellen von Vorlagen. Flottenbereitstellungsvorlagen können einen Mapping-Abschnitt und einen DeviceConfiguration-Abschnitt enthalten. Sie können intrinsische Funktionen innerhalb einer Flottenbereitstellungsvorlage verwenden, um die gerätespezifische Konfiguration zu generieren. Flottenbereitstellungsvorlagen sind benannte Ressourcen und werden durch ARNs identifiziert (z. B. arn:aws:iot:us-west-2:1234568788:provisioningtemplate/templateName).

Mappings

Im optionalen Abschnitt Mappings werden Schlüssel einem Satz benannter Werte zugewiesen. Wenn Sie beispielsweise Werte basierend auf einer AWS Region festlegen möchten, können Sie eine Zuordnung erstellen, die den AWS-Region Namen als Schlüssel verwendet und die Werte enthält, die Sie für jede spezifische Region angeben möchten. Zum Abrufen von Werten aus einer Karte nutzen Sie die intrinsische Funktion Fn::FindInMap.

Im Abschnitt Mappings dürfen keine Parameter, Pseudoparameter verwendet oder intrinsische Funktionen aufgerufen werden.

Gerätekonfiguration

Der Abschnitt „Gerätekonfiguration“ enthält beliebige Daten, die Sie bei der Bereitstellung an Ihre Geräte senden möchten. Beispielsweise:


{
    "DeviceConfiguration": {
        "Foo":"Bar"
    }
}

Wenn Sie Nachrichten mithilfe des Payload-Formats JavaScript Object Notation (JSON) an Ihre Geräte senden, AWS IoT Core formatieren Sie diese Daten als JSON. Wenn Sie das Payload-Format Concise Binary Object Representation (CBOR) verwenden, AWS IoT Core formatiert Sie diese Daten als CBOR. Der Abschnitt DeviceConfiguration unterstützt keine verschachtelten JSON-Objekte.

Intrinsische Funktionen

Intrinsische Funktionen werden in jedem Abschnitt der Bereitstellungsvorlage mit Ausnahme des Mappings-Abschnitts verwendet.

Fn::Join

Fügt einem einzelnen Wert eine Gruppe von Werten getrennt durch das angegebene Trennzeichen an. Wenn das Trennzeichen eine leere Zeichenfolge ist, dann werden die Werte ohne Trennzeichen verkettet.

Wichtig

Fn::Join wird nicht für Richtlinienressourcen unterstützt.

Fn::Select

Gibt ein einzelnes Objekt aus einer Liste von Objekten nach Index zurück.

Wichtig

Fn::Select überprüft nicht auf null-Werte oder ob sich der Index außerhalb des Arrays befindet. Beide Bedingungen führen zu einem Bereitstellungsfehler. Stellen Sie daher sicher, dass Sie einen gültigen Indexwert ausgewählt haben und die Liste Werte enthält, die nicht Null sind.

Fn::FindInMap

Gibt die Werte von Schlüsseln in einer Zwei-Ebenen-Karte zurück, die im Abschnitt Mappings deklariert ist.

Fn::Split

Teilt eine Zeichenfolge in eine Liste von Zeichenfolgenwerten auf, sodass Sie ein Element aus der Liste der Zeichenfolgen auswählen können. Sie geben ein Trennzeichen an, das bestimmt, wo die Zeichenfolge geteilt wird (z. B. ein Komma). Nachdem Sie eine Zeichenfolge geteilt haben, verwenden Sie Fn::Select, um ein Element auszuwählen.

Wenn beispielsweise eine durch ein Komma getrennte Zeichenfolge von Subnetz-IDs in Ihre Stack-Vorlage importiert wird, können Sie die Zeichenfolge an jedem Komma teilen. Geben Sie in der Liste der Subnetz-IDs mit Fn::Select eine Subnetz-ID für eine Ressource an.

Fn::Sub

Sie können Variablen in einer Eingabezeichenfolge mit Werten ersetzen, die Sie angeben. Sie können diese Funktion verwenden, um Befehle oder Ausgaben mit Werten zu erstellen, die erst verfügbar sind, wenn Sie ein Stack erstellen oder aktualisieren.

Beispiel einer Flottenbereitstellungsvorlage


{
    "Parameters" : {
        "ThingName" : {
            "Type" : "String"
        },
        "SerialNumber": {
            "Type": "String"
        },
        "DeviceLocation": {
            "Type": "String"
        }
    },
    "Mappings": {
        "LocationTable": {
            "Seattle": {
                "LocationUrl": "https://example.aws"
            }
        }
    },
    "Resources" : {
        "thing" : {
            "Type" : "AWS::IoT::Thing",
            "Properties" : {
                "AttributePayload" : { 
                    "version" : "v1",
                    "serialNumber" : "serialNumber"
                },
                "ThingName" : {"Ref" : "ThingName"},
                "ThingTypeName" : {"Fn::Join":["",["ThingPrefix_",{"Ref":"SerialNumber"}]]},
                "ThingGroups" : ["v1-lightbulbs", "WA"],
                "BillingGroup": "LightBulbBillingGroup"
            },
            "OverrideSettings" : {
                "AttributePayload" : "MERGE",
                "ThingTypeName" : "REPLACE",
                "ThingGroups" : "DO_NOTHING"
            }
        },
        "certificate" : {
            "Type" : "AWS::IoT::Certificate",
            "Properties" : {
                "CertificateId": {"Ref": "AWS::IoT::Certificate::Id"},
                "Status" : "Active"
            }
        },
        "policy" : {
            "Type" : "AWS::IoT::Policy",
            "Properties" : {
                "PolicyDocument" : {
                    "Version": "2012-10-17",
                    "Statement": [{
                        "Effect": "Allow",
                        "Action":["iot:Publish"],
                        "Resource": ["arn:aws:iot:us-east-1:123456789012:topic/foo/bar"]
                    }]
                }
            }
        }
    },
    "DeviceConfiguration": {
        "FallbackUrl": "https://www.example.com/test-site",
        "LocationUrl": {
            "Fn::FindInMap": ["LocationTable",{"Ref": "DeviceLocation"}, "LocationUrl"]}
        }
}

Anmerkung

Eine vorhandene Bereitstellungsvorlage kann aktualisiert werden, um einen Pre-Provisioning-Hook hinzuzufügen.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Massenregistrierung

Pre-Provisioning-Hooks