Mise en service des modèles

Un modèle de provisionnement est un document JSON qui utilise des paramètres pour décrire les ressources avec AWS IoT lesquelles votre appareil doit interagir. Un modèle de mise en service contient deux sections : Parameters et Resources. Il existe deux types de modèles de provisionnement dans AWS IoT. L'un est utilisé pour le just-in-time provisionnement (JITP) et l'enregistrement en masse, et le second est utilisé pour le provisionnement de la flotte.

Section Parameters

La section Parameters déclare les paramètres utilisés dans la section Resources. Chaque paramètre déclare un nom, un type et une valeur facultative par défaut. La valeur par défaut est utilisée lorsque le dictionnaire transmis avec le modèle ne contient pas de valeur pour le paramètre. La section Parameters d'un modèle de document ressemble à ce qui suit :

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

Cet extrait de corps de modèle déclare quatre paramètres : ThingName, SerialNumber, Location et CSR. Tous ces paramètres sont de type String. Le paramètre Location déclare la valeur par défaut "WA".

Section Resources

La Resources section du corps du modèle indique les ressources nécessaires à la communication de votre appareil AWS IoT : un objet, un certificat et une ou plusieurs politiques IoT. Chaque ressource spécifie un nom logique, un type et un ensemble de propriétés.

Un nom logique vous permet de faire référence à une ressource à un autre endroit dans le modèle.

Le type spécifie le type de ressource que vous déclarez. Les types valides sont :

• AWS::IoT::Thing

• AWS::IoT::Certificate

• AWS::IoT::Policy

Les propriétés que vous spécifiez dépendent du type de ressource que vous déclarez.

Ressources d'objet

Les ressources d'objet sont déclarées à l'aide des propriétés suivantes :

• ThingName: String.

• AttributePayload : Facultatif. Liste de paires nom-valeur.

• ThingTypeName : Facultatif. Chaîne d'un type d'objet associé pour l'objet.

• ThingGroups : Facultatif. Liste des groupes auxquels l'objet appartient.

• BillingGroup : Facultatif. Chaîne pour le nom d’un groupe de facturation associé.

• PackageVersions : Facultatif. Chaîne pour un package associé et les noms de version.

Ressources de certificat

Les certificats peuvent être spécifiés de l'une des façons suivantes :

• Demande de signature du certificat (CSR).

• ID d'un certificat d'appareil existant. (Seuls les ID de certificat peuvent être utilisés avec un modèle d'allocation de parc.)

• Certificat d'appareil créé avec un certificat CA enregistré auprès d' AWS IoT. Si vous avez plusieurs certificats CA enregistrés avec le même champ d'objet, vous devez également transmettre le certificat CA utilisé pour signer le certificat de l'appareil.

Note

Lorsque vous déclarez un certificat dans un modèle, vous devez uniquement utiliser ces méthodes. Par exemple, si vous utilisez une CSR, vous ne pouvez pas spécifier d'ID de certificat ou de certificat d'appareil. Pour plus d’informations, consultez Certificats client X.509.

Pour plus d’informations, consultez Présentation des certificats X.509.

Les ressources de certificat sont déclarées à l'aide des propriétés suivantes :

• CertificateSigningRequest: String.

• CertificateId: String.

• CertificatePem: String.

• CACertificatePem: String.

• Status : Facultatif. Chaîne qui peut être ACTIVE ou INACTIVE. ACTIVE est l'option sélectionnée par défaut.

Exemples :

• Certificat spécifié avec une CSR :

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

• Certificat spécifié avec un ID de certificat existant :

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

• Certificat spécifié avec un fichier .pem de certificat et un fichier .pem de certificat de CA existants :

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

Ressources de politique

Les ressources de stratégie sont déclarées à l'aide de l'une des propriétés suivantes :

• PolicyName : Facultatif. String. Un hachage du document de stratégie est utilisé par défaut. Les PolicyName peuvent uniquement faire référence à des politiques AWS IoT , mais pas à des politiques IAM. Si vous utilisez une AWS IoT politique existante, entrez le nom de la stratégie pour la PolicyName propriété. N'incluez pas la propriété PolicyDocument.

• PolicyDocument : Facultatif. Un objet JSON spécifié comme une chaîne placée dans une séquence d'échappement. Si PolicyDocument n'est pas fourni, la stratégie doit déjà être créée.

Note

Si une section Policy est présente, PolicyName ou PolicyDocument, mais pas les deux, doit être spécifié.

Paramètres de remplacement

Si un modèle spécifie une ressource qui existe déjà, la section OverrideSettings vous permet de spécifier l'action à effectuer :

DO_NOTHING

Conserver la ressource telle qu'elle est.

REPLACE

Remplacer la ressource par celle qui est spécifiée dans le modèle.

FAIL

Entraîner l'échec de la demande avec ResourceConflictsException.

MERGE

Valide uniquement pour les propriétés ThingGroups et AttributePayload d'un thing. Fusionnez les attributs existants ou les appartenances aux groupes de l'objet avec ceux spécifiés dans le modèle.

Lorsque vous déclarez une ressource d'objet, vous pouvez spécifier OverrideSettings pour les propriétés suivantes :

• ATTRIBUTE_PAYLOAD

• THING_TYPE_NAME

• THING_GROUPS

Lorsque vous déclarez une ressource de certificat, vous pouvez spécifier OverrideSettings pour la propriété Status.

OverrideSettings n'est pas disponible pour les ressources de stratégie.

Exemple de ressource

L'extrait de modèle suivant déclare un objet, un certificat et une stratégie :

{ 
    "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\"] }] }"
            }
        }
    }
}

L'objet est déclaré avec :

• Le nom logique "thing".

• Le type AWS::IoT::Thing.

• Un ensemble de propriétés d'objet.

  Les propriétés d'objet comprennent le nom de l'objet, un ensemble d'attributs, un nom de type d'objet facultatif et une liste facultative de groupes d'objets auxquels l'objet appartient.

Les paramètres sont référencés par {"Ref":"parameter-name"}. Lorsque le modèle est évalué, les paramètres sont remplacés par la valeur du paramètre à partir du dictionnaire transmis avec le modèle.

Le certificat est déclaré avec :

• Le nom logique "certificate".

• Le type AWS::IoT::Certificate.

• Un ensemble de propriétés.

  Les propriétés incluent la CSR pour le certificat et la définition de l'état sur ACTIVE. Le texte de la CSR est transmis en tant que paramètre dans le dictionnaire transmis avec le modèle.

La stratégie est déclarée avec :

• Le nom logique "policy".

• Le type AWS::IoT::Policy.

• Le nom d'une stratégie existante ou un document de stratégie.

Exemple de modèle pour l’enregistrement en bloc

Le fichier JSON suivant est un exemple de modèle de mise en service complet qui spécifie le certificat avec une CSR :

(La valeur du champ PolicyDocument doit être un objet JSON spécifié comme une chaîne placée dans une séquence d'échappement.)

{
    "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\"] }] }"
            }
        }
    }
}

Exemple de modèle pour le just-in-time provisionnement (JITP)

Le fichier JSON suivant est un exemple de modèle de mise en service complet qui spécifie un certificat existant avec un ID de certificat :

{
   "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\"] }] }"
         }
      }
   }
}

Important

Vous devez l’utiliser CertificateId dans un modèle utilisé pour la mise en service JIT.

Pour plus d'informations sur le type de modèle de provisionnement, consultez la référence CreateProvisioningTemplatede l' AWS API.

Pour plus d'informations sur l'utilisation de ce modèle pour le just-in-time provisionnement, voir : Provisionnement juste à temps.

Mise en service de flotte

Les modèles de provisionnement de flotte sont utilisés AWS IoT pour configurer la configuration du cloud et des appareils. Ces modèles utilisent les mêmes paramètres et ressources que le JITP et les modèles d'enregistrement en bloc. Pour plus d’informations, consultez Mise en service des modèles. Les modèles de mise en service de flotte peuvent contenir une section Mapping et une section DeviceConfiguration. Vous pouvez utiliser des fonctions intrinsèques à l’intérieur d’un modèle de mise en service de flotte pour générer une configuration spécifique à l’appareil. Les modèles d'allocation de parc sont des ressources nommées et sont identifiés par des noms ARN (par exemple, arn:aws:iot:us-west-2:1234568788:provisioningtemplate/templateName).

Mappages

La section Mappings facultative associe à une clé à un ensemble de valeurs correspondantes portant un nom. Par exemple, si vous souhaitez définir des valeurs en fonction d'une AWS région, vous pouvez créer un mappage qui utilise le Région AWS nom comme clé et qui contient les valeurs que vous souhaitez spécifier pour chaque région spécifique. Pour récupérer les valeurs d'un mappage, utilisez la fonction intrinsèque Fn::FindInMap.

Vous ne pouvez pas inclure des paramètres, des pseudo-paramètres ou des fonctions d'appel intrinsèques dans la section Mappings.

Configuration de l'appareil

La section Configuration des appareils contient des données arbitraires que vous souhaitez envoyer à vos appareils lors de la mise en service. Par exemple :

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

Si vous envoyez des messages à vos appareils à l'aide du format de charge utile JSON ( JavaScript Object Notation), AWS IoT Core formatez ces données au format JSON. Si vous utilisez le format de charge utile CBOR (Concise Binary Object Representation), AWS IoT Core formatez ces données au format CBOR. La section DeviceConfiguration ne prend pas en charge les objets JSON imbriqués.

Fonctions intrinsèques

Les fonctions intrinsèques sont utilisées dans n'importe quelle section du modèle de mise en service, à l'exception de la section Mappings.

Fn::Join

Ajoute un ensemble de valeurs dans une seule valeur, séparées par le délimiteur spécifié. Si un délimiteur est une chaîne vide, l’ensemble de valeurs est concaténé avec aucun délimiteur.

Important

Fn::Join n’est pas pris en charge pour Ressources de politique.

Fn::Select

Renvoie un seul objet à partir d'une liste d'objets en fonction de son index.

Important

Fn::Select ne recherche pas les valeurs null ou ne vérifie pas si l'index sort des limites du tableau. Les deux conditions entraînent une erreur de provisionnement. Assurez-vous donc que vous avez choisi une valeur d'index valide et que la liste contient des valeurs non nulles.

Fn::FindInMap

Renvoie la valeur correspondant aux clés dans un mappage à deux niveaux déclaré dans la section Mappings.

Fn::Split

Divise une chaîne en liste de valeurs de chaîne afin que vous puissiez sélectionner un élément dans la liste de chaînes. Vous spécifiez un délimiteur qui détermine où la chaîne est fractionnée (par exemple, une virgule). Après avoir divisé une chaîne, utilisez Fn::Select pour sélectionner un élément.

Par exemple, si une chaîne d'ID de sous-réseaux délimités par des virgules est importée dans votre modèle de pile, vous pouvez la fractionner au niveau de chaque virgule. Dans la liste des ID de sous-réseau, utilisez Fn::Select pour spécifier un ID de sous-réseau pour une ressource.

Fn::Sub

Remplace les variables contenues dans une chaîne d'entrée par des valeurs que vous spécifiez. Vous pouvez utiliser cette fonction pour construire des commandes ou des sorties qui incluent des valeurs qui ne sont pas disponibles tant que vous n'avez pas créé ou mis à jour une pile.

Exemple de modèle pour la mise en service d’une flotte

{
    "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"]}
        }
}

Note

Un modèle de mise en service existant peut être mis à jour afin d’ajouter un hook de mise en service en amont.