프로비저닝 템플릿 - AWS IoT Core
파라미터 섹션리소스 섹션대량 등록에 대한 템플릿 예 just-in-time프로비저닝을 위한 템플릿 예제 (JITP)플릿 프로비저닝

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

프로비저닝 템플릿

프로비저닝 템플릿은 매개변수를 사용하여 기기가 상호 작용하는 데 사용해야 하는 리소스를 설명하는 JSON 문서입니다. AWS IoT 프로비저닝 템플릿에는 Parameters와 Resources, 2가지 섹션이 포함됩니다. 에는 두 가지 유형의 프로비저닝 템플릿이 있습니다. AWS IoT 하나는 just-in-time 프로비저닝 (JITP) 및 대량 등록에 사용되고 다른 하나는 플릿 프로비저닝에 사용됩니다.

파라미터 섹션

Parameters 섹션은 Resources 섹션에서 사용할 파라미터를 선언합니다. 각 파라미터는 이름과 형식, 그리고 옵션으로 기본값을 선언합니다. 기본값은 템플릿과 함께 전달되는 딕셔너리에 파라미터 값이 포함되어 있지 않을 때 사용합니다. 템플릿 문서의 Parameters 섹션은 다음과 같습니다.

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

위의 템플릿 본문 코드 조각에서는 ThingName, SerialNumber, Location, CSR의 4가지 파라미터를 선언하고 있습니다. 이 파라미터들은 모두 String 형식을 갖습니다. Location 파라미터는 기본값으로 "WA"를 선언하고 있습니다.

리소스 섹션

템플릿 본문의 Resources 섹션은 기기가 통신하는 데 필요한 리소스 (사물, 인증서, 하나 이상의 IoT 정책) 를 AWS IoT 선언합니다. 각 리소스는 논리적 이름과 유형, 그리고 여러 가지 속성을 지정합니다.

논리적 이름은 템플릿의 다른 곳에서 리소스를 참조하는 데 사용됩니다.

유형은 선언하는 리소스 종류를 지정합니다. 유효한 유형은 다음과 같습니다.

  • AWS::IoT::Thing

  • AWS::IoT::Certificate

  • AWS::IoT::Policy

지정하는 속성은 선언하는 리소스 유형에 따라 달라집니다.

사물 리소스

사물 리소스는 다음 속성을 사용하여 선언합니다.

  • ThingName: 문자열.

  • AttributePayload: 선택 사항입니다. 이름-값 페어 목록입니다.

  • ThingTypeName: 선택 사항. 사물에 연결되어 있는 사물 유형을 나타내는 문자열

  • ThingGroups: 선택 사항. 사물이 속하는 그룹의 목록

  • BillingGroup: 선택 사항. 연결된 결제 그룹 이름의 문자열

  • PackageVersions: 선택 사항입니다. 연결된 패키지 및 버전 이름의 문자열

인증서 리소스

다음 방법 중 하나로 인증서를 지정할 수 있습니다.

  • 인증서 서명 요청(CSR)

  • 기존 디바이스 인증서의 ID (플릿 프로비저닝 템플릿에는 인증서 ID만 사용할 수 있습니다.)

  • AWS IoT에 등록한 CA 인증서로 생성된 디바이스 인증서. 동일한 제목 필드로 등록한 CA 인증서가 2개 이상인 경우에는 디바이스 인증서 서명에 사용한 CA 인증서도 전달해야 합니다.

참고

템플릿에서 인증서를 선언할 때는 이들 방법 중에서 한 가지만 사용하세요. 예를 들어 CSR을 사용하는 경우 인증서 ID 또는 디바이스 인증서는 지정할 수 없습니다. 자세한 내용은 X.509 클라이언트 인증서 단원을 참조하세요.

자세한 내용은 X.509 인증서 개요 단원을 참조하세요.

인증서 리소스는 다음 속성을 사용하여 선언합니다.

  • CertificateSigningRequest: 문자열.

  • CertificateId: 문자열.

  • CertificatePem: 문자열.

  • CACertificatePem: 문자열.

  • Status: 선택 사항. ACTIVE 또는 INACTIVE일 수 있는 문자열입니다. 기본값은 ACTIVE입니다.

예시:

  • CSR을 사용하여 지정된 인증서:

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

  • 기존 인증서 ID를 사용하여 지정된 인증서:

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

  • 기존 인증서 .pem 및 CA 인증서 .pem을 사용하여 지정된 인증서:

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

정책 리소스

정책 리소스는 다음 속성 중 한 가지를 사용하여 선언합니다.

  • PolicyName: 선택 사항. 문자열. 기본 값은 정책 문서의 해시입니다. PolicyName은 AWS IoT 정책만 참조할 수 있고 IAM 정책은 참조할 수 없습니다. 기존 AWS IoT 정책을 사용하는 경우 PolicyName 속성에 정책 이름을 입력합니다. PolicyDocument 속성은 포함하지 마세요.

  • PolicyDocument: 선택 사항. 이스케이프된 문자열로 지정된 JSON 객체. PolicyDocument를 입력하지 않는 경우에는 정책이 이미 생성되어 있어야 합니다.

참고

Policy 섹션이 존재하는 경우에는 PolicyName 또는 PolicyDocument를 지정해야 합니다(두 속성을 모두 지정할 수는 없습니다).

설정 재정의

템플릿이 기존 리소스를 지정하는 경우에는 OverrideSettings 섹션에서 실행할 작업을 지정할 수 있습니다.

DO_NOTHING

리소스를 그대로 유지합니다.

REPLACE

리소스를 템플릿에서 지정하는 리소스로 변경합니다.

FAIL

ResourceConflictsException을 사용해 리소스를 중단합니다.

MERGE

thing의 ThingGroups 및 AttributePayload 속성에만 유효합니다. 사물의 그룹 멤버십이나 기존 속성과 템플릿에 지정된 속성을 병합합니다.

특정 사물을 리소스로 선언할 때 다음 속성에 OverrideSettings를 지정할 수 있습니다.

  • ATTRIBUTE_PAYLOAD

  • THING_TYPE_NAME

  • THING_GROUPS

인증서 리소스를 선언할 경우 Status 속성에 OverrideSettings를 지정할 수 있습니다.

정책 리소스에는 OverrideSettings를 사용할 수 없습니다.

리소스 예제

다음은 사물, 인증서 및 정책을 선언하는 템플릿 조각입니다.

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

위 예제에서 사물은 다음과 같이 선언되어 있습니다.

  • 논리적 이름: "thing"

  • 유형: AWS::IoT::Thing

  • 여러 가지 사물 속성

    사물 속성 중에는 사물 이름, 속성 집합, 사물 유형 이름(선택적), 사물이 속하는 사물 그룹 목록(선택적)이 있습니다.

파라미터는 {"Ref":"parameter-name"}에서 참조할 수 있습니다. 템플릿을 평가할 때는 파라미터가 템플릿과 함께 전달되는 딕셔터리의 파라미터 값으로 치환됩니다.

위 예제에서 인증서는 다음과 같이 선언되어 있습니다.

  • 논리적 이름: "certificate"

  • 유형: AWS::IoT::Certificate

  • 속성 집합

    속성 중에는 인증서 CSR과 ACTIVE 상태 설정이 있습니다. CSR 텍스트는 템플릿과 함께 전달되는 딕셔너리에서 파라미터로 전달됩니다.

위 예제에서 정책은 다음과 같이 선언되어 있습니다.

  • 논리적 이름: "policy"

  • 유형: AWS::IoT::Policy

  • 기존 정책의 이름 또는 정책 문서

대량 등록에 대한 템플릿 예

다음 JSON 파일은 CSR을 사용하여 인증서를 지정하는 완전한 프로비저닝 템플릿의 예제입니다.

(PolicyDocument 필드 값은 이스케이프된 문자열로 지정된 JSON 객체여야 합니다.)

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

just-in-time프로비저닝을 위한 템플릿 예제 (JITP)

다음 JSON 파일은 인증서 ID를 사용하여 기존 인증서를 지정하는 완전한 프로비저닝 템플릿의 예제입니다.

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

JIT 프로비저닝에 사용되는 템플릿에서 CertificateId를 사용해야 합니다.

프로비저닝 템플릿 유형에 대한 자세한 내용은 API 참조를 참조하십시오 CreateProvisioningTemplate. AWS

이 템플릿을 프로비저닝에 사용하는 방법에 대한 자세한 내용은 J just-in-time ust-in-time 프로비저닝을 참조하십시오.

플릿 프로비저닝

플릿 프로비저닝 템플릿은 클라우드 및 AWS IoT 기기 구성을 설정하는 데 사용됩니다. 이러한 템플릿은 JITP 및 대량 등록 템플릿과 동일한 파라미터 및 리소스를 사용합니다. 자세한 내용은 프로비저닝 템플릿 단원을 참조하세요. 플릿 프로비저닝 템플릿은 Mapping 섹션 및 DeviceConfiguration 섹션을 포함할 수 있습니다. 플릿 프로비저닝 템플릿 내에서 내장 함수를 사용하여 디바이스별 구성을 생성할 수 있습니다. 플릿 프로비저닝 템플릿은 이름이 지정된 리소스이며 ARN으로 식별됩니다(예: arn:aws:iot:us-west-2:1234568788:provisioningtemplate/templateName).

매핑

Mappings 섹션(선택 사항)은 키를 해당하는 명명된 값 세트와 맞춥니다. 예를 들어 AWS 지역을 기반으로 값을 설정하려는 경우 AWS 리전 이름을 키로 사용하고 각 특정 지역에 지정하려는 값을 포함하는 매핑을 생성할 수 있습니다. Fn::FindInMap 내장 함수를 사용하여 맵에서 값을 불러올 수 있습니다.

Mappings 섹션에는 파라미터, 가상 파라미터 또는 호출 내장 함수를 포함할 수 없습니다.

디바이스 구성

디바이스 구성 섹션은 프로비저닝할 때 디바이스에 전송할 임의의 데이터를 포함합니다. 예: 

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

JavaScript 객체 표기법 (JSON) 페이로드 형식을 사용하여 디바이스에 메시지를 보내는 경우 이 데이터를 JSON으로 AWS IoT Core 포맷하십시오. 간결한 이진 객체 표현 (CBOR) 페이로드 형식을 사용하는 경우 이 데이터를 CBOR 형식으로 지정하십시오. AWS IoT Core DeviceConfiguration 섹션은 중첩 JSON 객체를 지원하지 않습니다.

내장 함수

내장 함수는 Mappings 섹션을 제외한 프로비저닝 템플릿의 모든 섹션에서 사용됩니다.

Fn::Join

지정된 구분 기호로 구분된 값 집합을 단일 값에 추가합니다. 구분 기호가 빈 문자열이면 값은 구분 기호 없이 연결됩니다.

중요

정책 리소스에는 Fn::Join이 지원되지 않습니다.

Fn::Select

인덱스별로 객체 목록에서 단일 객체를 반환합니다.

중요

인덱스가 어레이 범위를 벗어나는 경우 Fn::Select는 null 값을 확인하지 않습니다. 두 조건 모두 프로비저닝 오류가 발생하므로 유효한 인덱스 값을 선택하고 목록에 null이 아닌 값이 포함되어 있는지 확인하십시오.

Fn::FindInMap

Mappings 섹션에서 선언된 2수준 맵의 키에 해당하는 값을 반환합니다.

Fn::Split

문자열 목록에서 요소를 선택할 수 있도록 문자열을 문자열 값 목록으로 분할합니다. 문자열이 분할되는 위치를 결정하는 구분 기호(예: 쉼표)를 지정합니다. 문자열을 분할한 후 Fn::Select를 사용하여 요소를 선택합니다.

예를 들어, 쉼표로 구분된 서브넷 ID 문자열을 스택 템플릿으로 가져올 경우 각 쉼표로 문자열을 분할할 수 있습니다. 서브넷 ID 목록에서 Fn::Select를 사용하여 리소스의 서브넷 ID를 지정합니다.

Fn::Sub

입력 문자열의 변수를 사용자가 지정한 값으로 바꿉니다. 이 함수를 사용하여 스택을 생성하거나 업데이트해야만 사용할 수 있는 값이 포함된 명령 또는 출력을 작성할 수 있습니다.

플릿 프로비저닝 템플릿 예

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

기존 프로비저닝 템플릿을 업데이트하여 사전 프로비저닝 후크를 추가할 수 있습니다.