이진 페이로드 작업 - AWS IoT Core
이진 페이로드 예protobuf 메시지 페이로드 디코딩

이진 페이로드 작업

메시지 페이로드를 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를 사용하면 작은 패킷 크기로 다른 메시징 형식보다 빠른 속도로 데이터를 전송할 수 있습니다. AWS IoT Core 규칙은 decode(value, decodingScheme) SQL 함수를 제공하여 protobuf를 지원합니다. 이 함수를 사용하면 protobuf로 인코딩된 메시지 페이로드를 JSON 형식으로 디코딩하고 다운스트림 서비스로 라우팅할 수 있습니다. 이 섹션에서는 AWS IoT Core 규칙에서 protobuf 디코딩을 구성하는 단계별 프로세스를 자세히 설명합니다.

사전 조건

설명자 파일 생성

설명자 파일이 이미 있는 경우 이 단계를 건너뛰어도 됩니다. 설명자 파일(.desc)은 protobuf 직렬화에 사용할 데이터 구조와 메시지 유형을 정의하는 텍스트 파일인 .proto 파일의 컴파일된 버전입니다. 설명자 파일을 생성하려면 .proto 파일을 정의하고 protoc 컴파일러를 사용하여 컴파일해야 합니다.

  1. 메시지 유형을 정의하는 .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))를 참조하세요.

  2. 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 규칙은 이 설명자 파일을 사용하여 <PROTO_FILENAME>.proto에 정의된 데이터 구조를 준수하는 protobuf 페이로드를 디코딩할 수 있습니다.

    • --descriptor_set_out

      생성할 설명자 파일(<FILENAME>.desc)의 이름을 지정합니다.

    • --proto_path

      컴파일되는 파일에서 참조하는 가져온 .proto 파일의 위치를 지정합니다. 가져온 .proto 파일이 여러 개 있고 파일의 위치가 서로 다른 경우 플래그를 여러 번 지정할 수 있습니다.

    • --include_imports

      가져온 .proto 파일도 컴파일하여 <FILENAME>.desc 설명자 파일에 포함하도록 지정합니다.

    • <PROTO_FILENAME>.proto

      컴파일할 .proto 파일의 이름을 지정합니다.

    protoc 참조에 대한 자세한 내용은 API 참조를 참조하세요.

S3 버킷에 설명자 파일 업로드

설명자 파일 <FILENAME>.desc를 생성한 후 AWS API, AWS SDK 또는 AWS Management Console을 사용하여 설명자 파일 <FILENAME>.desc를 Amazon S3 버킷에 업로드합니다.

중요 고려 사항

  • 규칙을 구성하려는 AWS 리전과 동일한 리전에 있는 AWS 계정의 Amazon S3 버킷에 설명자 파일을 업로드해야 합니다.

  • S3에서 FileDescriptorSet를 읽을 수 있는 액세스 권한을 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 로깅을 구성합니다.

    CloudWatch에서 계정에 대한 AWS IoT 로그를 확인할 수 있도록 AWS IoT 로깅을 구성하는 것이 좋습니다. 규칙의 SQL 쿼리가 외부 함수를 호출하면 AWS IoT Core 규칙은 오류 해결에 도움이 되는 이유 필드를 포함하여 eventType이 FunctionExecution인 로그 항목을 생성합니다. 발생할 수 있는 오류에는 Amazon S3 객체를 찾을 수 없거나 protobuf 파일 설명자가 잘못된 것 등이 포함됩니다. AWS IoT 로깅을 구성하고 로그 항목을 확인하는 방법에 대한 자세한 내용은 AWS IoT 로깅 구성 및 규칙 엔진 로그 항목을 참조하세요.

  • 새 객체 키를 사용하여 FileDescriptorSet를 업데이트하고 규칙에서 객체 키를 업데이트합니다.

    업데이트된 설명자 파일을 Amazon S3 버킷에 업로드하여 FileDescriptorSet를 업데이트할 수 있습니다. FileDescriptorSet에 대한 업데이트 내용이 반영되는 데 최대 15분이 걸릴 수 있습니다. 이러한 지연을 피하려면 새 객체 키를 사용하여 업데이트된 FileDescriptorSet를 업로드하고 규칙에서 객체 키를 업데이트하는 것이 좋습니다.