Seção de parâmetros Seção de recursos Exemplo de modelo para registro em massa Exemplo de modelo para provisionamento just-in-time (JITP)Provisionamento de frota

Modelos de provisionamento

Um modelo de provisionamento é um documento JSON que usa parâmetros para descrever os recursos que seu dispositivo deve usar para interagir com a AWS IoT. Um modelo de provisionamento contém duas seções: Parameters e Resources. Existem dois tipos de modelos de provisionamento na AWS IoT. Um é usado para provisionamento just-in-time (JITP) e registro em massa, e o segundo é usado para provisionamento de frotas.

Tópicos

Seção de parâmetros
Seção de recursos
Exemplo de modelo para registro em massa
Exemplo de modelo para provisionamento just-in-time (JITP)
Provisionamento de frota

Seção de parâmetros

A seção Parameters declara os parâmetros usados na seção Resources. Cada parâmetro declara um nome, um tipo e um valor padrão opcional. O valor padrão é usado quando o dicionário passado com o modelo não contém um valor para o parâmetro. A seção Parameters de um documento de modelo é semelhante à seguinte:


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

Esse trecho de código do corpo de modelo declara quatro parâmetros: ThingName, SerialNumber, Location e CSR. Todos esses parâmetros são do tipo String. O parâmetro Location declara um valor padrão de "WA".

Seção de recursos

A seção Resources do corpo de modelo declara os recursos necessários para o dispositivo se comunicar com a AWS IoT: uma coisa, um certificado e uma ou mais políticas da IoT. Cada recurso especifica um nome lógico, um tipo e um conjunto de propriedades.

Um nome lógico permite que você faça referência a um recurso em outro lugar no modelo.

O tipo especifica o tipo de recurso que você está declarando. Os tipos válidos são:

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

As propriedades que você especifica dependem do tipo de recurso que você está declarando.

Recursos de coisas

Os recursos de coisas são declarados usando as seguintes propriedades:

ThingName: String.
AttributePayload: opcional. Uma lista de pares nome-valor.
ThingTypeName: opcional. String para um tipo de coisa associado à coisa.
ThingGroups: opcional. Uma lista de grupos aos quais a coisa pertence.
BillingGroup: opcional. String para o nome de um grupo de faturamento associado.
PackageVersions: opcional. String para um pacote associado e nomes de versão.

Recursos de certificados

É possível especificar certificados de uma das seguintes maneiras:

Uma solicitação de assinatura de certificado (CSR).
Um ID de certificado de um certificado de dispositivo existente. (Somente IDs de certificado podem ser usados com um modelo de provisionamento de frotas.)
Um certificado de dispositivo criado com um certificado da CA registrado na AWS IoT. Se houver mais de um certificado CA registrado com o mesmo campo de assunto, você também deverá passar o certificado CA usado para assinar o certificado do dispositivo.

nota

Ao declarar um certificado em um modelo, use somente um desses métodos. Por exemplo, se você usar uma CSR, não será possível especificar também um ID de certificado ou um certificado de dispositivo. Para obter mais informações, consulte Certificados do cliente X.509.

Para obter mais informações, consulte Visão geral do certificado X.509.

Os recursos de certificados são declarados usando as seguintes propriedades:

CertificateSigningRequest: String.
CertificateId: String.
CertificatePem: String.
CACertificatePem: String.
Status: opcional. String que pode ser ACTIVE ou INACTIVE. Padronizada como ACTIVE.
ThingPrincipalType: opcional. String que especifica o tipo de relacionamento entre a coisa e a entidade principal (o certificado).
- EXCLUSIVE_THING: estabelece um relacionamento exclusivo. A entidade principal só pode ser vinculada a essa coisa específica e a nenhuma outra.
- NON_EXCLUSIVE_THING: anexa a entidade principal especificada às coisas. É possível anexar várias coisas à entidade principal. Esse é o valor padrão caso não seja especificado.
nota
Você também pode provisionar dispositivos sem certificados de dispositivos. Para obter mais informações, consulte Provisionar dispositivos que não têm certificados de dispositivo usando o provisionamento de frotas.

Exemplos:

Certificado especificado com um CSR:


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

Certificado especificado com um ID de certificado existente:


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

Certificado especificado com um certificado .pem existente .pem e certificado .pem da CA:


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

Vincule exclusivamente uma coisa a uma entidade principal:


{
    "certificate" : {
        "Type" : "AWS::IoT::Certificate",
        "Properties" : {
            "ThingPrincipalType" : "EXCLUSIVE_THING"
        }
    }
}

Recursos de políticas

Os recursos de políticas são declarados com uma das seguintes propriedades:

PolicyName: opcional. String. Padroniza para um hash do documento de política. O PolicyName só pode referenciar políticas da AWS IoT, mas não políticas do IAM. Se você estiver usando uma política da AWS IoT existente, insira o nome da política para a propriedade PolicyName. Não inclua a propriedade PolicyDocument.
PolicyDocument: opcional. Um objeto JSON especificado como uma string de escape. Se PolicyDocument não for fornecido, a política já deverá estar criada.

nota

Se uma seção Policy estiver presente, PolicyName ou PolicyDocument, mas não ambos, deve ser especificado.

Configurações de substituição

Se um modelo especificar um recurso que já existe, a seção OverrideSettings permitirá que você especifique a ação a ser executada:

DO_NOTHING: Deixe o recurso como está.
REPLACE: Substitui o recurso pelo recurso especificado no modelo.
FAIL: Faz com que a solicitação falhe com um ResourceConflictsException.
MERGE: Válido apenas para as propriedades ThingGroups e AttributePayload de uma thing. Mescla os atributos ou associações de grupo existentes da coisa com os especificados no modelo.

Ao declarar um recurso de coisa, você pode especificar OverrideSettings para as seguintes propriedades:

ATTRIBUTE_PAYLOAD
THING_TYPE_NAME
THING_GROUPS

Ao declarar um recurso de certificado, você pode especificar OverrideSettings para a propriedade Status.

OverrideSettings não estão disponíveis para recursos de política.

Exemplo de recurso

O trecho de código do modelo a seguir declara uma coisa, um certificado e uma 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\"] }] }"
            }
        }
    }
}

A coisa é declarada com:

O nome lógico "thing".
O tipo AWS::IoT::Thing.
Um conjunto de propriedades de coisas.

As propriedades da coisa incluem o nome, um conjunto de atributos, um nome opcional de tipo de coisa e uma lista opcional de grupos de coisas aos quais a coisa pertence.

Os parâmetros são referenciados por {"Ref":"parameter-name"}. Quando o modelo é avaliado, os parâmetros são substituídos pelo valor do parâmetro do dicionário passado com o modelo.

O certificado é declarado com:

O nome lógico "certificate".
O tipo AWS::IoT::Certificate.
Um conjunto de propriedades.

As propriedades incluem a CSR do certificado e a configuração do status como ACTIVE. O texto da CSR é passado como um parâmetro no dicionário passado com o modelo.

A política é declarada com:

O nome lógico "policy".
O tipo AWS::IoT::Policy.
O nome de uma política existente ou um documento de política.

Exemplo de modelo para registro em massa

O arquivo JSON a seguir é um exemplo de modelo de provisionamento completo que especifica o certificado com uma CSR:

(O valor do campo PolicyDocument deve ser um objeto JSON especificado como uma string 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",
                "ThingPrincipalType" : "EXCLUSIVE_THING"
            }
        },
        "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\"] }] }"
            }
        }
    }
}

Exemplo de modelo para provisionamento just-in-time (JITP)

O arquivo JSON a seguir é um exemplo de modelo de provisionamento completo que especifica um certificado existente com um 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",
            "ThingPrincipalType" : "EXCLUSIVE_THING"
         }
      },
      "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

Você deve usar CertificateId em um modelo usado para o provisionamento JIT.

Para obter mais informações sobre o tipo de um modelo de provisionamento, consulte CreateProvisioningTemplate na Referência de API da AWS.

Para obter mais informações sobre como usar esse modelo para provisionamento just-in-time, consulte: provisionamento just-in-time.

Provisionamento de frota

Os modelos de provisionamento de frotas são usados pela AWS IoT para configurar a nuvem e a configuração do dispositivo. Esses modelos usam os mesmos parâmetros e recursos que o JITP e os modelos de registro em massa. Para obter mais informações, consulte Modelos de provisionamento. Os modelos de provisionamento de frotas podem conter uma seção Mapping e uma seção DeviceConfiguration. É possível usar funções intrínsecas dentro de um modelo de provisionamento de frotas para gerar uma configuração específica de dispositivo. Os modelos de provisionamento de frotas são recursos nomeados e são identificados por ARNs (por exemplo, arn:aws:iot:us-west-2:1234568788:provisioningtemplate/templateName).

Mapeamentos

A seção opcional Mappings corresponde uma chave a um conjunto de valores nomeados correspondente. Por exemplo, para definir valores com base em uma região AWS, você pode criar um mapeamento que use o nome da Região da AWS como uma chave e contenha os valores que você quer especificar para cada região específica. Você usa a função intrínseca Fn::FindInMap para recuperar valores em um mapa.

Não é possível incluir parâmetros, pseudoparâmetros ou chamar funções intrínsecas na seção Mappings.

Configuração do dispositivo

A seção de configuração do dispositivo contém os dados arbitrários que você deseja enviar para os dispositivos ao provisionar. Por exemplo:


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

Se você estiver enviando mensagens para seus dispositivos usando o formato de carga útil Notação de Objetos para JavaScript (JSON), o AWS IoT Core formatará esses dados como JSON. Se você estiver usando o formato de carga útil Concise Binary Object Representation (CBOR), o AWS IoT Core formatará esses dados como CBOR. A seção DeviceConfiguration não é compatível com objetos JSON aninhados.

Funções intrínsecas

As funções intrínsecas são usadas em qualquer seção do modelo de provisionamento, exceto a seção Mappings.

Fn::Join

Anexa um conjunto de valores em um único valor, separados pelo delimitador especificado. Se um delimitador é uma string vazia, os valores são concatenados sem delimitador.

Importante

Fn::Join não é compatível com Recursos de políticas.

Fn::Select

Retorna um único objeto de uma lista de objetos por índice.

Importante

Fn::Select não verifica valores null ou se o índice está fora dos limites da matriz. Ambas as condições resultam em um erro de provisionamento, portanto, escolha um valor de índice e garanta que a lista contenha valores não nulos.

Fn::FindInMap

Retorna o valor correspondente às chaves em um mapa de dois níveis que é declarado na seção Mappings.

Fn::Split

Divide uma string em uma lista de valores de string para que seja possível selecionar um elemento na lista de strings. Especifique um delimitador que determine onde a string é dividida (por exemplo, uma vírgula). Depois de dividir uma string, use Fn::Select para selecionar um elemento.

Por exemplo, se uma string de IDs de sub-rede delimitada por vírgulas for importada para seu modelo de pilha, você poderá dividir a string em cada vírgula. Na lista de IDs de sub-rede, use Fn::Select para especificar um ID de sub-rede para um recurso.

Fn::Sub

Substitui variáveis em uma string de entrada por valores especificados por você. É possível usar essa função para criar comandos ou saídas que incluem valores que não estão disponíveis até que você crie ou atualize uma pilha.

Exemplo de modelo de provisionamento por frota


{
    "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",
                "ThingPrincipalType" : "EXCLUSIVE_THING"
            }
        },
        "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

Um modelo de provisionamento existente pode ser atualizado para adicionar um hook de pré-provisionamento.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Registro em massa

Ganchos de pré-provisionamento