Bagian parameter Bagian sumber daya Contoh template untuk pendaftaran massal Contoh template untuk penyediaan just-in-time (JITP)Penyediaan armada

Templat penyediaan

Template penyediaan adalah dokumen JSON yang menggunakan parameter untuk menggambarkan sumber daya yang harus digunakan perangkat Anda untuk berinteraksi dengannya AWS IoT. Template penyediaan berisi dua bagian: Parameters danResources. Ada dua jenis templat penyediaan di AWS IoT. Satu digunakan untuk penyediaan just-in-time (JITP) dan pendaftaran massal, dan yang kedua digunakan untuk penyediaan armada.

Topik

Bagian parameter
Bagian sumber daya
Contoh template untuk pendaftaran massal
Contoh template untuk penyediaan just-in-time (JITP)
Penyediaan armada

Bagian parameter

ParametersBagian ini menyatakan parameter yang digunakan di Resources bagian tersebut. Setiap parameter menyatakan nama, tipe, dan nilai default opsional. Nilai default digunakan ketika kamus yang diteruskan dengan template tidak berisi nilai untuk parameter. ParametersBagian dari dokumen template terlihat seperti berikut:


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

Cuplikan badan template ini menyatakan empat parameter:ThingName,, SerialNumberLocation, danCSR. Semua parameter ini adalah tipeString. LocationParameter menyatakan nilai default"WA".

Bagian sumber daya

ResourcesBagian badan template menyatakan sumber daya yang diperlukan perangkat Anda untuk berkomunikasi dengan AWS IoT: sesuatu, sertifikat, dan satu atau lebih kebijakan IoT. Setiap sumber daya menentukan nama logis, tipe, dan satu set properti.

Nama logis memungkinkan Anda untuk merujuk ke sumber daya di tempat lain dalam template.

Jenis menentukan jenis sumber daya yang Anda deklarasikan. Jenis yang valid adalah:

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

Properti yang Anda tentukan bergantung pada jenis sumber daya yang Anda deklarasikan.

Sumber daya benda

Sumber daya benda dideklarasikan menggunakan properti berikut:

ThingName: Tali.
AttributePayload: Opsional. Daftar pasangan nama-nilai.
ThingTypeName: Opsional. String untuk jenis benda terkait untuk benda tersebut.
ThingGroups: Opsional. Daftar kelompok tempat benda itu berada.
BillingGroup: Opsional. String untuk nama grup penagihan terkait.
PackageVersions: Opsional. String untuk paket terkait dan nama versi.

Sumber daya sertifikat

Anda dapat menentukan sertifikat dengan salah satu cara berikut:

Permintaan penandatanganan sertifikat (CSR).
ID sertifikat dari sertifikat perangkat yang ada. (Hanya ID sertifikat yang dapat digunakan dengan template penyediaan armada.)
Sertifikat perangkat yang dibuat dengan sertifikat CA terdaftar dengan AWS IoT. Jika Anda memiliki lebih dari satu sertifikat CA terdaftar dengan bidang subjek yang sama, Anda juga harus memasukkan sertifikat CA yang digunakan untuk menandatangani sertifikat perangkat.

catatan

Saat Anda mendeklarasikan sertifikat dalam template, gunakan hanya salah satu metode ini. Misalnya, jika Anda menggunakan CSR, Anda juga tidak dapat menentukan ID sertifikat atau sertifikat perangkat. Untuk informasi selengkapnya, lihat X.509 sertifikat klien.

Untuk informasi selengkapnya, lihat X.509 Ikhtisar sertifikat.

Sumber daya sertifikat dideklarasikan menggunakan properti berikut:

CertificateSigningRequest: Tali.
CertificateId: Tali.
CertificatePem: Tali.
CACertificatePem: Tali.
Status: Opsional. String yang bisa ACTIVE atauINACTIVE. Defaultnya aktif.
ThingPrincipalType: Opsional. String yang menentukan jenis hubungan antara benda dan prinsipal (sertifikat).
- EXCLUSIVE_THING: Membangun hubungan eksklusif. Prinsip hanya dapat melekat pada Hal khusus ini dan tidak ada yang lain.
- NON_EXCLUSIVE_THING: Melampirkan prinsip yang ditentukan ke hal-hal. Anda dapat melampirkan beberapa hal ke kepala sekolah. Ini adalah nilai default jika tidak ditentukan.
catatan
Anda juga dapat menyediakan perangkat tanpa sertifikat perangkat. Untuk informasi selengkapnya, lihat Menyediakan perangkat yang tidak memiliki sertifikat perangkat menggunakan penyediaan armada.

Contoh:

Sertifikat yang ditentukan dengan CSR:


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

Sertifikat yang ditentukan dengan ID sertifikat yang ada:


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

Sertifikat yang ditentukan dengan sertifikat yang ada .pem dan sertifikat CA .pem:


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

Secara eksklusif melampirkan satu hal ke kepala sekolah:


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

Sumber daya kebijakan

Sumber daya kebijakan dideklarasikan menggunakan salah satu properti berikut:

PolicyName: Opsional. String. Defaultnya adalah hash dari dokumen kebijakan. Hanya PolicyName dapat merujuk AWS IoT kebijakan tetapi tidak kebijakan IAM. Jika Anda menggunakan AWS IoT kebijakan yang ada, untuk PolicyName properti, masukkan nama kebijakan. Jangan menyertakan PolicyDocument properti.
PolicyDocument: Opsional. Objek JSON yang ditentukan sebagai string yang lolos. Jika PolicyDocument tidak disediakan, kebijakan harus sudah dibuat.

catatan

Jika ada Policy bagian, PolicyName atauPolicyDocument, tetapi tidak keduanya, harus ditentukan.

Mengganti pengaturan

Jika template menentukan sumber daya yang sudah ada, OverrideSettings bagian ini memungkinkan Anda untuk menentukan tindakan yang akan diambil:

DO_NOTHING: Biarkan sumber daya apa adanya.
REPLACE: Ganti sumber daya dengan sumber daya yang ditentukan dalam template.
FAIL: Menyebabkan permintaan gagal dengan aResourceConflictsException.
MERGE: Hanya berlaku untuk AttributePayload properti ThingGroups dan dari athing. Gabungkan atribut yang ada atau keanggotaan grup dari benda tersebut dengan yang ditentukan dalam template.

Ketika Anda mendeklarasikan sumber daya benda, Anda dapat menentukan OverrideSettings untuk properti berikut:

ATTRIBUTE_PAYLOAD
THING_TYPE_NAME
THING_GROUPS

Saat Anda mendeklarasikan sumber daya sertifikat, Anda dapat menentukan OverrideSettings untuk Status properti tersebut.

OverrideSettingstidak tersedia untuk sumber daya kebijakan.

Contoh sumber daya

Cuplikan template berikut mendeklarasikan sesuatu, sertifikat, dan kebijakan:


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

Hal ini dinyatakan dengan:

Nama logis"thing".
JenisnyaAWS::IoT::Thing.
Satu set properti benda.

Properti benda termasuk nama benda, satu set atribut, nama tipe benda opsional, dan daftar opsional kelompok benda yang menjadi milik benda itu.

Parameter direferensikan oleh{"Ref":"parameter-name"}. Ketika template dievaluasi, parameter diganti dengan nilai parameter dari kamus yang diteruskan dengan template.

Sertifikat dinyatakan dengan:

Nama logis"certificate".
JenisnyaAWS::IoT::Certificate.
Satu set properti.

Properti termasuk CSR untuk sertifikat, dan mengatur status keACTIVE. Teks CSR diteruskan sebagai parameter dalam kamus yang diteruskan dengan template.

Kebijakan tersebut dinyatakan dengan:

Nama logis"policy".
JenisnyaAWS::IoT::Policy.
Entah nama kebijakan yang ada atau dokumen kebijakan.

Contoh template untuk pendaftaran massal

File JSON berikut adalah contoh template penyediaan lengkap yang menentukan sertifikat dengan CSR:

(Nilai PolicyDocument bidang harus berupa objek JSON yang ditentukan sebagai string yang lolos.)


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

Contoh template untuk penyediaan just-in-time (JITP)

File JSON berikut adalah contoh template penyediaan lengkap yang menentukan sertifikat yang ada dengan ID sertifikat:


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

penting

Anda harus menggunakan CertificateId dalam template yang digunakan untuk penyediaan JIT.

Untuk informasi selengkapnya tentang jenis templat penyediaan, lihat CreateProvisioningTemplate di referensi AWS API.

Untuk informasi selengkapnya tentang cara menggunakan template ini untuk penyediaan just-in-time, lihat: penyediaan. Just-in-time

Penyediaan armada

Templat penyediaan armada digunakan AWS IoT untuk mengatur konfigurasi cloud dan perangkat. Template ini menggunakan parameter dan sumber daya yang sama dengan JITP dan template pendaftaran massal. Untuk informasi selengkapnya, lihat Templat penyediaan. Templat penyediaan armada dapat berisi Mapping bagian dan DeviceConfiguration bagian. Anda dapat menggunakan fungsi intrinsik di dalam template penyediaan armada untuk menghasilkan konfigurasi khusus perangkat. Template penyediaan armada diberi nama resource dan diidentifikasi oleh ARN (misalnya,arn:aws:iot:us-west-2:1234568788:provisioningtemplate/templateName).

Pemetaan

Bagian Mappings opsional cocok dengan kunci untuk satu set nilai yang sesuai. Misalnya, jika Anda ingin menetapkan nilai berdasarkan Wil AWS ayah, Anda dapat membuat pemetaan yang menggunakan Wilayah AWS nama sebagai kunci dan berisi nilai yang ingin Anda tentukan untuk setiap Wilayah tertentu. Anda menggunakan fungsi intrinsik Fn::FindInMap untuk mengambil nilai-nilai dalam peta.

Anda tidak dapat menyertakan parameter, parameter semu, atau memanggil fungsi intrinsik di bagian tersebutMappings.

Konfigurasi perangkat

Bagian konfigurasi perangkat berisi data arbitrer yang ingin Anda kirim ke perangkat saat penyediaan. Contoh:


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

Jika Anda mengirim pesan ke perangkat menggunakan format payload JavaScript Object Notation (JSON), AWS IoT Core format data ini sebagai JSON. Jika Anda menggunakan format payload Concise Binary Object Representation (CBOR), AWS IoT Core format data ini sebagai CBOR. DeviceConfigurationBagian ini tidak mendukung objek JSON bersarang.

Fungsi intrinsik

Fungsi intrinsik digunakan di bagian mana pun dari template penyediaan kecuali Mappings bagian.

Fn::Join

Menambahkan satu set nilai ke dalam satu nilai, dipisahkan oleh pembatas yang ditentukan. Jika pembatas adalah string kosong, nilai-nilai digabungkan tanpa pembatas.

penting

Fn::Jointidak didukung untukSumber daya kebijakan.

Fn::Select

Mengembalikan objek tunggal dari daftar objek berdasarkan indeks.

penting

Fn::Selecttidak memeriksa null nilai atau jika indeks berada di luar batas array. Kedua kondisi tersebut mengakibatkan kesalahan penyediaan, jadi pastikan Anda memilih nilai indeks yang valid dan daftar berisi nilai non-null.

Fn::FindInMap

Mengembalikan nilai yang sesuai dengan kunci dalam peta dua tingkat yang dinyatakan di Mappings bagian.

Fn::Split

Membagi string menjadi daftar nilai string sehingga Anda dapat memilih elemen dari daftar string. Anda menentukan pembatas yang menentukan di mana string dibagi (misalnya, koma). Setelah Anda membagi string, gunakan Fn::Select untuk memilih elemen.

Misalnya, jika string yang dipisahkan koma dari ID subnet diimpor ke templat tumpukan, Anda dapat membagi string pada setiap koma. Dari daftar ID subnet, gunakan Fn::Select untuk menentukan ID subnet untuk sumber daya.

Fn::Sub

Mengganti variabel dalam string input dengan nilai yang Anda tentukan. Anda dapat menggunakan fungsi ini untuk membuat perintah atau output yang menyertakan nilai yang tidak tersedia sampai Anda membuat atau memperbarui tumpukan.

Contoh template untuk penyediaan armada


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

catatan

Template penyediaan yang ada dapat diperbarui untuk menambahkan hook pra-penyediaan.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Pendaftaran massal

Pre-provisioning kait