Sezione Parametri Sezione Risorse Esempio di modello per la registrazione in blocco Esempio di modello per il just-in-time provisioning (JITP)Provisioning del parco istanze

Modelli di provisioning

Un modello di provisioning è un documento JSON che utilizza parametri per descrivere le risorse che il dispositivo deve utilizzare per interagire. AWS IoT Un modello di provisioning contiene due sezioni: Parameters e Resources. Esistono due tipi di modelli di provisioning in. AWS IoT Uno viene utilizzato per il just-in-time provisioning (JITP) e la registrazione in blocco, mentre il secondo viene utilizzato per l'approvvigionamento del parco veicoli.

Argomenti

Sezione Parametri
Sezione Risorse
Esempio di modello per la registrazione in blocco
Esempio di modello per il just-in-time provisioning (JITP)
Provisioning del parco istanze

Sezione Parametri

La sezione Parameters dichiara i parametri usati all'interno della sezione Resources. Ogni parametro dichiara un nome, un tipo e un valore predefinito facoltativo. Il valore predefinito viene usato quando il dizionario passato con il modello non contiene un valore per il parametro. La sezione Parameters del documento di un modello è simile alla seguente:


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

Il frammento di codice di questo corpo del modello dichiara quattro parametri: ThingName, SerialNumber, Location e CSR. Tutti questi parametri sono di tipo String. Il parametro Location dichiara un valore predefinito "WA".

Sezione Risorse

La Resources sezione del corpo del modello dichiara le risorse necessarie per la comunicazione del dispositivo AWS IoT: un oggetto, un certificato e una o più policy IoT. Ogni risorsa specifica un nome logico, un tipo e un set di proprietà.

Un nome logico permette di fare riferimento a una risorsa in un'altra parte del modello.

Il tipo specifica il tipo di risorsa che intendi dichiarare. I tipi validi sono:

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

Le proprietà specificate dipendono dal tipo di risorsa dichiarato.

Risorse oggetto

Le risorse oggetto vengono dichiarate usando le proprietà seguenti:

ThingName: stringa.
AttributePayload: facoltativo. Un elenco di coppie nome-valore.
ThingTypeName: facoltativo. Stringa per un tipo di oggetto associato per l'oggetto.
ThingGroups: facoltativo. Elenco di gruppi cui appartiene l'oggetto.
BillingGroup: facoltativo. Stringa per il nome di un gruppo di fatturazione associato.
PackageVersions: facoltativo. Stringa per un pacchetto associato e nomi delle versioni.

Risorse certificato

È possibile specificare i certificati in uno dei modi seguenti:

Richiesta di firma del certificato.
ID certificato di un certificato del dispositivo esistente. (Solo gli ID di certificato possono essere utilizzati con un modello di provisioning del parco istanze dispositivi)
Certificato del dispositivo creato con un certificato CA registrato con AWS IoT. Se esistono più certificati CA registrati con lo stesso campo dell'oggetto, devi passare anche il certificato CA usato per firmare il certificato del dispositivo.

Nota

Quando dichiari un certificato in un modello, usa solo uno di questi metodi. Ad esempio, se usi una richiesta di firma del certificato, non potrai specificare anche un ID certificato o un certificato del dispositivo. Per ulteriori informazioni, consulta Certificati client X.509.

Per ulteriori informazioni, consultare Panoramica sui certificati X.509.

Le risorse certificato vengono dichiarate usando le proprietà seguenti:

CertificateSigningRequest: stringa.
CertificateId: stringa.
CertificatePem: stringa.
CACertificatePem: stringa.
Status: facoltativo. Stringa che può essere ACTIVE o INACTIVE. Il valore predefinito è ACTIVE.

Esempi:

Certificato specificato con una richiesta di firma del certificato (CSR):


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

Certificato specificato con un ID certificato esistente:


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

Certificate specificato con un .pem del certificato esistente e un .pem del certificato CA:


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

Risorse relative alle policy

Le risorse policy vengono dichiarate con una delle seguenti proprietà:

PolicyName: facoltativo. Stringa. Il valore predefinito è un hash del documento della policy. La PolicyName può solo fare riferimento alle policy AWS IoT ma non policy IAM. Se si utilizza una AWS IoT politica esistente, per la PolicyName proprietà, immettere il nome della politica. Non includere la proprietà PolicyDocument.
PolicyDocument: facoltativo. Un oggetto JSON specificato come stringa con carattere di escape. Se la proprietà PolicyDocument non è specificata, la policy deve essere già stata creata.

Nota

Se è presente una sezione Policy, è necessario specificare la proprietà PolicyName o PolicyDocument, ma non entrambe.

Sostituzione delle impostazioni

Se un modello specifica una risorsa già esistente, la sezione OverrideSettings permette di specificare l'operazione da eseguire:

DO_NOTHING: Lascia la risorsa inalterata.
REPLACE: Sostituisce la risorsa con quella specificata nel modello.
FAIL: La richiesta non riesce con ResourceConflictsException.
MERGE: Valido solo per le proprietà ThingGroups e AttributePayload di una risorsa thing. Unisce gli attributi o le appartenenze ai gruppi esistenti dell'oggetto a quelli specificati nel modello.

Quando si dichiara una risorsa oggetto, è possibile specificare OverrideSettings per le seguenti proprietà:

ATTRIBUTE_PAYLOAD
THING_TYPE_NAME
THING_GROUPS

Quando si dichiara una risorsa certificato, è possibile specificare OverrideSettings per la proprietà Status.

OverrideSettings non sono disponibili per le risorse policy.

Esempi di risorsa

Il frammento di codice del modello seguente dichiara un oggetto, un certificato e una policy:


{ 
    "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'oggetto viene dichiarato con:

Nome logico "thing".
Tipo AWS::IoT::Thing.
Un set di proprietà dell'oggetto.

Le proprietà dell'oggetto includono il nome dell'oggetto, un set di attributi, un nome di tipo di oggetto facoltativo e un elenco facoltativo di gruppi di oggetti cui appartiene l'oggetto.

Ai parametri viene fatto riferimento tramite {"Ref":"parameter-name"}. Quando il modello viene valutato, i parametri vengono sostituiti con il valore del parametro specificato nel dizionario passato con il modello.

Il certificato viene dichiarato con:

Nome logico "certificate".
Tipo AWS::IoT::Certificate.
Un set di proprietà.

Le proprietà includono la richiesta di firma per il certificato e l'impostazione dello stato su ACTIVE. Il testo della richiesta di firma del certificato viene passato come parametro nel dizionario a sua volta passato con il modello.

La policy viene dichiarata con:

Nome logico "policy".
Tipo AWS::IoT::Policy.
Nome di una policy esistente o di un documento di policy.

Esempio di modello per la registrazione in blocco

Il seguente file JSON è un esempio di un modello di provisioning completo che specifica il certificato con una CSR:

(Il valore del campo PolicyDocument deve essere un oggetto JSON specificato come stringa con carattere escape).


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

Esempio di modello per il just-in-time provisioning (JITP)

Il seguente file JSON è un esempio di un modello di provisioning completo che specifica un certificato esistente con un ID certificato:


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

Importante

Devi utilizzare CertificateId in un modello utilizzato per il provisioning JIT.

Per ulteriori informazioni sul tipo di modello di provisioning, consulta il riferimento CreateProvisioningTemplateall'API. AWS

Per ulteriori informazioni su come utilizzare questo modello per il just-in-time provisioning, vedere: Just-in-Time Provisioning.

Provisioning del parco istanze

I modelli di provisioning della flotta vengono utilizzati da per configurare la configurazione del AWS IoT cloud e dei dispositivi. Questi modelli utilizzano gli stessi parametri e risorse dei modelli di registrazione JITP e in blocco. Per ulteriori informazioni, consulta Modelli di provisioning. I modelli di provisioning del parco istanze dispositivi possono contenere una sezione Mapping e una sezione DeviceConfiguration. È possibile utilizzare funzioni intrinseche all'interno di un modello di provisioning del parco istanze dei dispositivi per generare una configurazione specifica del dispositivo. I modelli di provisioning del parco istanze dei dispositivi sono risorse denominate e sono identificati da ARN (ad esempio arn:aws:iot:us-west-2:1234568788:provisioningtemplate/templateName).

Mappature

La sezione Mappings opzionale abbina una chiave a un corrispondente set di valori denominati. Ad esempio, se si desidera impostare valori basati su una AWS regione, è possibile creare una mappatura che utilizzi il Regione AWS nome come chiave e contenga i valori che si desidera specificare per ogni regione specifica. Utilizzi quindi la funzione intrinseca Fn::FindInMap per recuperare i valori in una mappa.

Non puoi includere parametri, pseudoparametri o funzioni intrinseche di chiamata nella sezione Mappings.

Configurazione del dispositivo

La sezione di configurazione del dispositivo contiene dati arbitrari che si desidera inviare ai dispositivi durante il provisioning. Per esempio:


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

Se invii messaggi ai tuoi dispositivi utilizzando il formato di payload JavaScript Object Notation (JSON), AWS IoT Core formatta questi dati come JSON. Se utilizzi il formato di payload Concise Binary Object Representation (CBOR), formatta questi dati come CBOR. AWS IoT Core La sezione DeviceConfiguration non supporta gli oggetti JSON nidificati.

Funzioni intrinseche

Le funzioni intrinseche vengono utilizzate in qualsiasi sezione del modello di provisioning ad eccezione della sezione Mappings.

Fn::Join

Aggiunge un set di valori in un singolo valore, separato dal delimitatore specificato. Se un delimitatore è una stringa vuota, i valori sono concatenati senza alcun delimitatore.

Importante

Fn::Join non è supportato per Risorse relative alle policy.

Fn::Select

Restituisce un singolo oggetto da un elenco di oggetti per indice.

Importante

Fn::Select non verifica la presenza di valori null o se l'indice è fuori dai limiti dell'array. Entrambe le condizioni generano un errore di provisioning, quindi assicurati di aver scelto un valore di indice valido e che l'elenco contenga valori non nulli.

Fn::FindInMap

Restituisce i valori corrispondenti alle chiavi in una mappatura a due livelli dichiarata nella sezione Mappings.

Fn::Split

Divide una stringa in un elenco di valori stringa in modo da poter selezionare un elemento dall'elenco di stringhe. Si specifica un delimitatore che stabilisce dove è suddivisa la stringa (ad esempio, una virgola). Dopo aver suddiviso una stringa, utilizzare Fn::Select per selezionare un elemento.

Ad esempio, se una stringa delimitata dalla virgola di ID di una sottorete viene importata nel tuo modello di stack, puoi suddividere la stringa in corrispondenza di ciascuna virgola. Nell'elenco degli ID di sottorete, utilizzare Fn::Select per specificare un ID di sottorete per una risorsa.

Fn::Sub

Sostituisce le variabili in una stringa di input con valori che puoi specificare. Questa funzione è utilizzabile per costruire comandi o output che includono valori non disponibili finché non crei o aggiorni uno stack.

Esempio di modello per il provisioning del parco istanze dei dispositivi


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

Nota

È possibile aggiornare un modello di provisioning esistente per aggiungere un hook di pre-provisioning.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Registrazione in blocco

Hook di pre-provisioning