기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
이진 페이로드 작업
메시지 페이로드를 JSON 객체가 아닌 원시 이진 데이터로 처리해야 하려면 * 연산자를 사용하여 SELECT 절에서 참조할 수 있습니다.
이 주제에서 수행할 작업
이진 페이로드 예
*를 사용하여 메시지 페이로드를 원시 이진 데이터로 참조하면 규칙에 데이터를 추가할 수 있습니다. 비어 있거나 JSON 페이로드가 있는 경우 결과 페이로드에 규칙을 사용하여 데이터를 추가할 수 있습니다. 다음은 지원되는 SELECT 절의 예를 보여줍니다.
-
다음 이진 페이로드에 *만 있는 다음
SELECT절을 사용할 수 있습니다.SELECT * FROM 'topic/subtopic'SELECT * FROM 'topic/subtopic' WHERE timestamp() % 12 = 0
-
데이터를 추가하고 다음
SELECT절을 사용할 수도 있습니다.SELECT *, principal() as principal, timestamp() as time FROM 'topic/subtopic'SELECT encode(*, 'base64') AS data, timestamp() AS ts FROM 'topic/subtopic'
-
이진 페이로드에 이러한
SELECT절을 사용할 수도 있습니다.다음은 WHERE 절에서
device_type을 참조합니다.SELECT * FROM 'topic/subtopic' WHERE device_type = 'thermostat'다음도 지원됩니다.
{ "sql": "SELECT * FROM 'topic/subtopic'", "actions": [ { "republish": { "topic": "device/${device_id}" } } ] }
다음 규칙 작업은 이진 페이로드를 지원하지 않으므로 디코딩해야 합니다.
-
Lambda 작업과 같은 일부 규칙 작업은 이진 페이로드 입력을 지원하지 않으므로 이진 페이로드를 디코딩해야 합니다. Lambda 규칙 작업은 base64로 인코딩되고 JSON 페이로드에 있는 경우 이진 데이터를 수신할 수 있습니다. 규칙을 다음으로 변경하여 이 작업을 수행할 수 있습니다.
SELECT encode(*, 'base64') AS data FROM 'my_topic' -
SQL 문은 문자열을 입력으로 지원하지 않습니다. 문자열 입력을 JSON으로 변환하려면 다음 명령을 실행합니다.
SELECT decode(encode(*, 'base64'), 'base64') AS payload FROM 'topic'
protobuf 메시지 페이로드 디코딩
프로토콜 버퍼(protobuf)
필수 조건
-
프로토콜 버퍼(protobuf)
에 대한 기본적인 이해 -
메시지 유형 및 관련 종속 항목을 정의하는
.proto파일 -
시스템에 Protobuf 컴파일러(protoc)
설치
설명자 파일 생성
설명자 파일이 이미 있는 경우 이 단계를 건너뛰어도 됩니다. 설명자 파일(.desc)은 protobuf 직렬화에 사용할 데이터 구조와 메시지 유형을 정의하는 텍스트 파일인 .proto 파일의 컴파일된 버전입니다. 설명자 파일을 생성하려면 .proto 파일을 정의하고 protoc
-
메시지 유형을 정의하는
.proto파일을 생성합니다. 예제.proto파일은 다음과 같습니다.syntax = "proto3"; message Person { optional string name = 1; optional int32 id = 2; optional string email = 3; }이 예제
.proto파일에서는 proto3 구문을 사용하고Person이라는 메시지 유형을 정의합니다.Person메시지 정의는 3개의 필드(이름, ID 및 이메일)를 지정합니다..proto파일 메시지 형식에 대한 자세한 내용은 Language Guide(proto3)(언어 가이드(proto3))를 참조하세요. -
protoc
컴파일러를 사용하여 .proto파일을 컴파일하고 설명자 파일을 생성합니다. 설명자(.desc) 파일을 생성하는 예제 명령은 다음과 같습니다.protoc --descriptor_set_out=<FILENAME>.desc \ --proto_path=<PATH_TO_IMPORTS_DIRECTORY> \ --include_imports \ <PROTO_FILENAME>.proto이 예제 명령은 설명자 파일을 생성하며
<FILENAME>.desc, AWS IoT Core 규칙은 이 파일을 사용하여 에서 정의된 데이터 구조를 준수하는 protobuf 페이로드를 디코딩할 수 있습니다.<PROTO_FILENAME>.proto-
--descriptor_set_out생성할 설명자 파일(
<FILENAME>.desc)의 이름을 지정합니다. -
--proto_path컴파일되는 파일에서 참조하는 가져온
.proto파일의 위치를 지정합니다. 가져온.proto파일이 여러 개 있고 파일의 위치가 서로 다른 경우 플래그를 여러 번 지정할 수 있습니다. -
--include_imports가져온
.proto파일도 컴파일하여<FILENAME>.desc설명자 파일에 포함하도록 지정합니다. -
<PROTO_FILENAME>.proto컴파일할
.proto파일의 이름을 지정합니다.
protoc 참조에 대한 자세한 내용은 API 참조
를 참조하세요. -
S3 버킷에 설명자 파일 업로드
디스크립터 파일을 생성한 후 AWS API<FILENAME>.desc, AWS SDK 또는 <FILENAME>.desc 를 사용하여 Amazon S3 버킷에 디스크립터 파일을 업로드합니다. AWS Management Console
중요 고려 사항
-
규칙을 구성하려는 AWS 리전 위치와 동일한 Amazon S3 버킷에 디스크립터 파일을 업로드해야 합니다. AWS 계정
FileDescriptorSetS3에서 읽을 수 있는 AWS IoT Core 액세스 권한을 부여했는지 확인하십시오. S3 버킷에서 서버 측 암호화(SSE)가 비활성화되었거나 S3 버킷이 Amazon S3 관리형 키(SSE-S3)를 사용하여 암호화된 경우 추가 정책 구성이 필요하지 않습니다. 이 작업은 다음과 같은 예제 버킷 정책을 사용하여 수행할 수 있습니다.{ "Version": "2012-10-17", "Statement": [ { "Sid": "Statement1", "Effect": "Allow", "Principal": { "Service": "iot.amazonaws.com" }, "Action": "s3:Get*", "Resource": "arn:aws:s3:::<BUCKET NAME>/<FILENAME>.desc" } ] }-
S3 버킷이 AWS Key Management Service 키 (SSE-KMS) 를 사용하여 암호화된 경우, S3 버킷에 액세스할 때 키 사용 AWS IoT Core 권한을 부여해야 합니다. 키 정책에 다음 문을 추가하면 됩니다.
{ "Sid": "Statement1", "Effect": "Allow", "Principal": { "Service": "iot.amazonaws.com" }, "Action": [ "kms:Decrypt", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" }
규칙에서 protobuf 디코딩 구성
설명자 파일을 Amazon S3 버킷에 업로드한 후 decode(value, decodingScheme) SQL 함수를 사용하여 protobuf 메시지 페이로드 형식을 디코딩할 수 있는 규칙을 구성합니다. 자세한 함수 서명 및 예시는 AWS IoT SQL 참조의 decode(value, decodingScheme) SQL 함수 섹션에서 찾을 수 있습니다.
다음은 decode(value, decodingScheme) 함수를 사용하는 예시 SQL 표현식입니다.
SELECT VALUE decode(*, 'proto', '<BUCKET NAME>', '<FILENAME>.desc', '<PROTO_FILENAME>', '<PROTO_MESSAGE_TYPE>') FROM '<MY_TOPIC>'
이 예제 표현식에서는
-
decode(value, decodingScheme) SQL 함수를 사용하여
*에서 참조하는 바이너리 메시지 페이로드를 디코딩합니다. 이는 바이너리 protobuf로 인코딩된 페이로드이거나 base64로 인코딩된 protobuf 페이로드를 나타내는 JSON 문자열일 수 있습니다. -
제공된 메시지 페이로드는
PROTO_FILENAME.proto에 정의된Person메시지 유형을 사용하여 인코딩됩니다. -
BUCKET NAME이라는 Amazon S3 버킷에는PROTO_FILENAME.proto에서 생성된FILENAME.desc가 포함되어 있습니다.
구성을 완료한 후 규칙을 구독하는 AWS IoT Core 주제에 대한 메시지를 게시하십시오.
제한 사항
AWS IoT Core 규칙은 protobuf를 지원하지만 다음과 같은 제한이 있습니다.
-
대체 템플릿 내에서 protobuf 메시지 페이로드를 디코딩하는 것은 지원되지 않습니다.
-
protobuf 메시지 페이로드를 디코딩할 때 단일 SQL 표현식 내에서 decode SQL 함수를 최대 두 번 사용할 수 있습니다.
-
최대 인바운드 페이로드 크기는 128KiB(1KiB=1024바이트)이고, 최대 아웃바운드 페이로드 크기는 128KiB이며, Amazon S3 버킷에 저장되는
FileDescriptorSet객체의 최대 크기는 32KiB입니다. -
SSE-C로 암호화된 Amazon S3 버킷은 지원되지 않습니다.
모범 사례
다음은 몇 가지 모범 사례와 문제 해결 팁입니다.
-
Amazon S3 버킷에 proto 파일을 백업합니다.
문제가 발생할 경우에 대비하여 proto 파일을 백업하는 것이 좋습니다. 예를 들어, protoc을 실행할 때 백업 없이 proto 파일을 잘못 수정하면 프로덕션 스택에 문제가 발생할 수 있습니다. Amazon S3 버킷에 파일을 백업하는 방법에는 여러 가지가 있습니다. 예를 들어, S3 버킷에서 버전 관리를 사용할 수 있습니다. Amazon S3 버킷에 파일을 백업하는 방법에 대한 자세한 내용은 Amazon S3 개발자 안내서를 참조하세요.
-
로그 항목을 볼 수 있도록 AWS IoT 로깅을 구성합니다.
에서 계정의 AWS IoT 로그를 확인할 수 있도록 AWS IoT 로깅을 구성하는 것이 좋습니다 CloudWatch. 규칙의 SQL 쿼리가 외부 함수를 호출하는 경우 Rules는 f가 포함된 로그 항목을 생성합니다. 이 항목에는 실패 문제를 해결하는 데 도움이 되는 이유 필드가 포함되어 있습니다. AWS IoT Core
eventTypeFunctionExecution발생할 수 있는 오류에는 Amazon S3 객체를 찾을 수 없거나 protobuf 파일 설명자가 잘못된 것 등이 포함됩니다. AWS IoT 로깅을 구성하고 로그 항목을 확인하는 방법에 대한 자세한 내용은 AWS IoT 로깅 구성 및 규칙 엔진 로그 항목을 참조하세요. -
새 객체 키를 사용하여
FileDescriptorSet를 업데이트하고 규칙에서 객체 키를 업데이트합니다.업데이트된 설명자 파일을 Amazon S3 버킷에 업로드하여
FileDescriptorSet를 업데이트할 수 있습니다.FileDescriptorSet에 대한 업데이트 내용이 반영되는 데 최대 15분이 걸릴 수 있습니다. 이러한 지연을 피하려면 새 객체 키를 사용하여 업데이트된FileDescriptorSet를 업로드하고 규칙에서 객체 키를 업데이트하는 것이 좋습니다.
