Sección de parámetros Sección de recursos Ejemplo de plantilla para el registro masivo Ejemplo de plantilla para el just-in-time aprovisionamiento (JITP)Aprovisionamiento de flotas

Aprovisionamiento de plantillas

Una plantilla de aprovisionamiento es un documento JSON que utiliza parámetros para describir los recursos con los que el dispositivo debe interactuar. AWS IoT Una plantilla de aprovisionamiento contiene dos secciones: Parameters y Resources. Existen dos tipos de plantillas de aprovisionamiento. AWS IoT Una se usa para el just-in-time aprovisionamiento (JITP) y el registro masivo, y la segunda se usa para el aprovisionamiento de flotas.

Temas

Sección de parámetros
Sección de recursos
Ejemplo de plantilla para el registro masivo
Ejemplo de plantilla para el just-in-time aprovisionamiento (JITP)
Aprovisionamiento de flotas

Sección de parámetros

La sección Parameters declara los parámetros utilizados en la sección Resources. Cada parámetro declara un nombre, un tipo y un valor predeterminado opcional. El valor predeterminado se usa cuando el diccionario trasladado con la plantilla no contiene un valor para el parámetro. La sección Parameters de un documento de plantilla tiene el siguiente aspecto:


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

Este snippet de cuerpo de plantilla declara cuatro parámetros: ThingName, SerialNumber, Location y CSR. Todos esos parámetros son de tipo String. El parámetro Location declara un valor predeterminado de "WA".

Sección de recursos

La Resources sección del cuerpo de la plantilla declara los recursos necesarios para que el dispositivo se comunique con AWS IoT: una cosa, un certificado y una o más políticas de IoT. Cada recurso especifica un nombre lógico, un tipo y un conjunto de propiedades.

Un nombre lógico le permite hacer referencia a un recurso en cualquier lugar de la plantilla.

El tipo especifica la clase de recurso que está declarando. Los tipos válidos son:

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

Las propiedades que especifique dependen del tipo de recurso que está declarando.

Recursos de objetos

Los recursos de objetos se declaran mediante las siguientes propiedades:

ThingName: Cadena.
AttributePayload: Opcional. Una lista de pares de nombre-valor.
ThingTypeName: Opcional. Cadena para un tipo de objeto asociado para el objeto.
ThingGroups: Opcional. Una lista de grupos a los que pertenece el objeto.
BillingGroup: Opcional. Cadena para el nombre de un grupo de facturación asociado.
PackageVersions: Opcional. Cadena para un paquete asociado y los nombres de las versiones.

Recursos de certificados

Puede especificar certificados de una de las siguientes maneras:

Una solicitud de firma de certificado (CSR).
Un ID de certificado de un certificado de dispositivo existente. (Los ID de certificado solo se pueden utilizar con una plantilla de aprovisionamiento de flotas).
Un certificado de dispositivo creado con un certificado de CA registrado con AWS IoT. Si tiene más de un certificado de CA registrado con el mismo campo de asunto, también debe trasladar el certificado de CA utilizado para firmar el certificado de dispositivo.

nota

Cuando declare un certificado en una plantilla, use solo uno de estos métodos. Por ejemplo, si utiliza un CSR, no puede especificar también un ID de certificado o un certificado de dispositivo. Para obtener más información, consulte Certificados de cliente X.509.

Para obtener más información, consulte Información general del certificado X.509.

Los recursos de certificados se declaran mediante las siguientes propiedades:

CertificateSigningRequest: Cadena.
CertificateId: Cadena.
CertificatePem: Cadena.
CACertificatePem: Cadena.
Status: Opcional. Cadena, que puede ser ACTIVE o INACTIVE. El valor predeterminado es ACTIVE.

Ejemplos:

Certificado especificado con un CSR:


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

Certificado especificado con un ID de certificado existente:


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

Certificado especificado con un archivo .pem de certificado existente y un archivo .pem de certificado de CA:


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

Recursos de políticas

Los recursos de políticas se declaran mediante una de las siguientes propiedades:

PolicyName: Opcional. Cadena. Hash es el valor predeterminado del documento de políticas. Solo PolicyName puede hacer referencia a las políticas de AWS IoT , pero no a las políticas de IAM. Si utiliza una AWS IoT política existente, introduzca el nombre de la política para la PolicyName propiedad. No incluya la propiedad PolicyDocument.
PolicyDocument: Opcional. Un objeto JSON especificado como una cadena de escape. Si PolicyDocument no se proporciona, la política debe haberse creado ya.

nota

Si una sección Policy está presente, PolicyName o PolicyDocument, pero no ambas, debe especificarse.

Anular la configuración

Si una plantilla especifica un recurso que ya existe, la sección OverrideSettings le permite especificar la acción que se debe realizar:

DO_NOTHING: Dejar el recurso como está.
REPLACE: Sustituir el recurso por el recurso especificado en la plantilla.
FAIL: Provocar un error en la solicitud con ResourceConflictsException.
MERGE: Solo es válida para las propiedades ThingGroups y AttributePayload de un objeto (thing). Combinar los atributos o las pertenencias a grupos existentes de la cosa con los especificados en la plantilla.

Cuando declara un recurso de objeto, puede especificar OverrideSettings para las siguientes propiedades:

ATTRIBUTE_PAYLOAD
THING_TYPE_NAME
THING_GROUPS

Cuando declara un recurso de certificado, puede especificar OverrideSettings para la propiedad Status.

OverrideSettings no están disponibles para recursos de políticas.

Ejemplo de recursos

El siguiente fragmento de plantilla declara un objeto, un certificado y una política:


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

El objeto se declara con:

El nombre lógico "thing".
El tipo AWS::IoT::Thing.
Un conjunto de propiedades de objeto.

Las propiedades de objeto incluyen el nombre de objeto, un conjunto de atributos, un nombre de tipo de objeto opcional y una lista opcional de grupos de objetos a los que pertenece el objeto.

Se hace referencia a los parámetros mediante {"Ref":"parameter-name"}. Cuando se evalúa la plantilla, los parámetros se reemplazan por el valor de los parámetros desde el diccionario trasladado con la plantilla.

El certificado se declara con:

El nombre lógico "certificate".
El tipo AWS::IoT::Certificate.
Un conjunto de propiedades.

Las propiedades incluyen el CSR para el certificado y el establecimiento del estado en ACTIVE. El texto CSR se transfiere como parámetro en el diccionario transferido con la plantilla.

La política se declara con:

El nombre lógico "policy".
El tipo AWS::IoT::Policy.
O el nombre de una política existente o un documento de políticas.

Ejemplo de plantilla para el registro masivo

El siguiente archivo JSON es un ejemplo de una plantilla de aprovisionamiento completa que especifica el certificado con un CSR:

(El valor del campo PolicyDocument debe ser un objeto JSON especificado como una cadena de 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\"] }] }"
            }
        }
    }
}

Ejemplo de plantilla para el just-in-time aprovisionamiento (JITP)

El siguiente archivo JSON es un ejemplo de una plantilla de aprovisionamiento completa que especifica un certificado existente con un ID de certificado:


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

Debe utilizar CertificateId en una plantilla que se utilice para el aprovisionamiento JIT.

Para obtener más información sobre el tipo de plantilla de aprovisionamiento, consulta la referencia de CreateProvisioningTemplatela AWS API.

Para obtener más información sobre cómo utilizar esta plantilla para el just-in-time aprovisionamiento, consulta: J ust-in-time Provisioning.

Aprovisionamiento de flotas

Las plantillas de aprovisionamiento de flotas se utilizan AWS IoT para configurar la nube y los dispositivos. Estas plantillas utilizan los mismos parámetros y recursos que las plantillas de registro masivo y JITP. Para obtener más información, consulte Aprovisionamiento de plantillas. Las plantillas de aprovisionamiento de flotas pueden contener una sección Mapping y una sección DeviceConfiguration. Puede utilizar funciones intrínsecas dentro de una plantilla de aprovisionamiento de flotas para generar una configuración específica del dispositivo. Las plantillas de aprovisionamiento de flotas son recursos con nombre y se identifican mediante el ARN (por ejemplo, arn:aws:iot:us-west-2:1234568788:provisioningtemplate/templateName).

Mapeos

La sección Mappings opcional hace coincidir una clave con el conjunto correspondiente de valores identificados. Por ejemplo, si desea establecer valores en función de una AWS región, puede crear un mapeo que utilice el Región de AWS nombre como clave y contenga los valores que desee especificar para cada región específica. Puede utilizar la función intrínseca Fn::FindInMap para recuperar valores en una asignación.

No puede incluir parámetros, pseudoparámetros ni funciones de llamadas intrínsecas en la sección Mappings.

Configuración del dispositivo

La sección de configuración del dispositivo contiene los datos arbitrarios que desea enviar a sus dispositivos al realizar el aprovisionamiento. Por ejemplo:


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

Si envías mensajes a tus dispositivos mediante el formato de carga útil de notación de JavaScript objetos (JSON), AWS IoT Core formatea estos datos como JSON. Si utilizas el formato de carga útil de representación concisa de objetos binarios (CBOR), AWS IoT Core formatea estos datos como CBOR. La sección DeviceConfiguration no admite objetos JSON anidados.

Funciones intrínsecas

Las funciones intrínsecas se utilizan en cualquier sección de la plantilla de aprovisionamiento, excepto en la sección Mappings.

Fn::Join

Agrega un conjunto de valores a un único valor separado por el delimitador especificado. Si un delimitador es la cadena vacía, los valores se concatena sin delimitador.

importante

Fn::Join no admite Recursos de políticas.

Fn::Select

Devuelve un único objeto de una lista de objetos por índice.

importante

Fn::Select no comprueba si hay valores null o si el índice queda fuera de los límites de la matriz. Ambas condiciones provocan un error de aprovisionamiento, así que asegúrese de elegir un valor de índice válido y de que la lista contenga valores que no sean nulos.

Fn::FindInMap

Devuelve el valor correspondiente a claves en una asignación de dos niveles declarada en la sección Mappings.

Fn::Split

Divide una cadena en una lista de valores de cadena para que pueda seleccionar un elemento de la lista de cadenas. Especifique un delimitador que determine dónde se divide la cadena (por ejemplo, una coma). Después de dividir una cadena, utilice Fn::Select para seleccionar un elemento.

Por ejemplo, si una cadena delimitada por comas de IDs de subred se importa a la plantilla de pila, puede dividir la cadena en cada coma. En la lista de ID de subred, utilice Fn::Select para especificar el ID de subred de un recurso.

Fn::Sub

Sustituye variables en una cadena de entrada por los valores que especifique. Puede utilizar esta función para crear comandos o salidas que incluyan valores que no están disponibles hasta que crea o actualiza una pila.

Ejemplo de plantilla de aprovisionamiento de flotas


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

Se puede actualizar una plantilla de aprovisionamiento existente para agregar un enlace de preaprovisionamiento.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Registro masivo

Enlaces de preaprovisionamiento