기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # 이진 페이로드 작업 메시지 페이로드를 JSON 객체가 아닌 원시 이진 데이터로 처리해야 하려면 \$1 연산자를 사용하여 SELECT 절에서 참조할 수 있습니다. **Topics** + [이진 페이로드 예](#binary-payloads-examples) + [protobuf 메시지 페이로드 디코딩](#binary-payloads-protobuf) ## 이진 페이로드 예 \$1를 사용하여 메시지 페이로드를 원시 이진 데이터로 참조하면 규칙에 데이터를 추가할 수 있습니다. 비어 있거나 JSON 페이로드가 있는 경우 결과 페이로드에 규칙을 사용하여 데이터를 추가할 수 있습니다. 다음은 지원되는 `SELECT` 절의 예를 보여줍니다. + 다음 이진 페이로드에 \$1만 있는 다음 `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 작업](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rule-actions.html#lambda-rule)과 같은 일부 규칙 작업은 이진 페이로드 입력을 지원하지 않으므로 이진 페이로드를 디코딩해야 합니다. Lambda 규칙 작업은 base64로 인코딩되고 JSON 페이로드에 있는 경우 이진 데이터를 수신할 수 있습니다. 규칙을 다음으로 변경하여 이 작업을 수행할 수 있습니다. ``` SELECT encode(*, 'base64') AS data FROM 'my_topic' ``` + SQL 문은 문자열을 입력으로 지원하지 않습니다. 문자열 입력을 JSON으로 변환하려면 다음 명령을 실행합니다. ``` SELECT decode(encode(*, 'base64'), 'base64') AS payload FROM 'topic' ``` ## protobuf 메시지 페이로드 디코딩 [프로토콜 버퍼(protobuf)](https://developers.google.com/protocol-buffers)는 구조화된 데이터를 압축 이진 형식으로 직렬화하는 데 사용되는 오픈 소스 데이터 형식입니다. 이는 데이터를 네트워크를 통해 전송하거나 파일에 저장하는 데 사용됩니다. Protobuf를 사용하면 다른 메시징 형식보다 작은 패킷 크기와 빠른 속도로 데이터를 전송할 수 있습니다. AWS IoT Core 규칙은 디[코딩(값, 디decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) SQL 함수를 제공하여 protobuf를 지원하므로 protobuf 인코딩 메시지 페이로드를 JSON 형식으로 디코딩하고 다운스트림 서비스로 라우팅할 수 있습니다. 이 섹션에서는 AWS IoT Core 규칙에서 protobuf 디코딩을 구성하는 단계별 프로세스를 자세히 설명합니다. **Topics** + [사전 조건](#binary-payloads-protobuf-prerequisites) + [설명자 파일 생성](#binary-payloads-protobuf-descriptor-steps) + [S3 버킷에 설명자 파일 업로드](#binary-payloads-protobuf-s3-steps) + [규칙에서 protobuf 디코딩 구성](#binary-payloads-protobuf-steps) + [제한 사항](#binary-payloads-protobuf-limitations) + [모범 사례](#binary-payloads-protobuf-bestpractices) ### 사전 조건 + [프로토콜 버퍼(protobuf)](https://developers.google.com/protocol-buffers) 에 대한 기본적인 이해 + 메시지 유형 및 관련 종속 항목을 정의하는 [`.proto` 파일](https://developers.google.com/protocol-buffers/docs/proto3) + 시스템에 [Protobuf 컴파일러(protoc)](https://github.com/protocolbuffers/protobuf/releases) 설치 ### 설명자 파일 생성 설명자 파일이 이미 있는 경우 이 단계를 건너뛰어도 됩니다. 설명자 파일(`.desc`)은 protobuf 직렬화에 사용할 데이터 구조와 메시지 유형을 정의하는 텍스트 파일인 `.proto` 파일의 컴파일된 버전입니다. 설명자 파일을 생성하려면 `.proto` 파일을 정의하고 [protoc](https://github.com/protocolbuffers/protobuf/releases) 컴파일러를 사용하여 컴파일해야 합니다. 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)](https://developers.google.com/protocol-buffers/docs/proto3)(언어 가이드(proto3))를 참조하세요. 1. [protoc](https://github.com/protocolbuffers/protobuf/releases) 컴파일러를 사용하여 `.proto` 파일을 컴파일하고 설명자 파일을 생성합니다. 설명자(`.desc`) 파일을 생성하는 예제 명령은 다음과 같습니다. ``` protoc --descriptor_set_out=.desc \ --proto_path= \ --include_imports \ .proto ``` 이 예제 명령은에 정의된 데이터 구조를 준수하는 protobuf 페이로드를 디코딩하는 데 사용할 수 있는 `.desc` AWS IoT Core 설명자 파일을 생성합니다`.proto`. + `--descriptor_set_out` 생성할 설명자 파일(`.desc`)의 이름을 지정합니다. + `--proto_path` 컴파일되는 파일에서 참조하는 가져온 `.proto` 파일의 위치를 지정합니다. 가져온 `.proto` 파일이 여러 개 있고 파일의 위치가 서로 다른 경우 플래그를 여러 번 지정할 수 있습니다. + `--include_imports` 가져온 `.proto` 파일도 컴파일하여 `.desc` 설명자 파일에 포함하도록 지정합니다. + `.proto` 컴파일할 `.proto` 파일의 이름을 지정합니다. protoc 참조에 대한 자세한 내용은 [API 참조](https://developers.google.com/protocol-buffers/docs/reference/overview)를 참조하세요. ### S3 버킷에 설명자 파일 업로드 설명자 파일을 생성한 후 AWS API`.desc`, AWS SDK 또는 `.desc`를 사용하여 설명자 파일을 Amazon S3 버킷에 업로드합니다 AWS Management Console. **중요 고려 사항** + 규칙을 구성하려는 AWS 리전 것과 동일한의 Amazon S3 버킷 AWS 계정 에 설명자 파일을 업로드해야 합니다. + 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:::/.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)](iot-sql-functions.md#iot-sql-decode-base64) SQL 함수를 사용하여 protobuf 메시지 페이로드 형식을 디코딩할 수 있는 [규칙](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-rule.html)을 구성합니다. 자세한 함수 서명 및 예시는 *AWS IoT SQL 참조*의 [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) SQL 함수 섹션에서 찾을 수 있습니다. 다음은 [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) 함수를 사용하는 예시 SQL 표현식입니다. ``` SELECT VALUE decode(*, 'proto', '', '.desc', '', '') FROM '' ``` 이 예제 표현식에서는 + [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) 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를 지원합니다. + [대체 템플릿](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) 내에서 protobuf 메시지 페이로드를 디코딩하는 것은 지원되지 않습니다. + protobuf 메시지 페이로드를 디코딩할 때 단일 SQL 표현식 내에서 [decode SQL 함수](iot-sql-functions.md#iot-sql-decode-base64)를 최대 두 번 사용할 수 있습니다. + 최대 인바운드 페이로드 크기는 128KiB(1KiB=1024바이트)이고, 최대 아웃바운드 페이로드 크기는 128KiB이며, Amazon S3 버킷에 저장되는 `FileDescriptorSet` 객체의 최대 크기는 32KiB입니다. + SSE-C로 암호화된 Amazon S3 버킷은 지원되지 않습니다. ### 모범 사례 다음은 몇 가지 모범 사례와 문제 해결 팁입니다. + Amazon S3 버킷에 proto 파일을 백업합니다. 문제가 발생할 경우에 대비하여 proto 파일을 백업하는 것이 좋습니다. 예를 들어, protoc을 실행할 때 백업 없이 proto 파일을 잘못 수정하면 프로덕션 스택에 문제가 발생할 수 있습니다. Amazon S3 버킷에 파일을 백업하는 방법에는 여러 가지가 있습니다. 예를 들어, [S3 버킷에서 버전 관리를 사용](https://docs.aws.amazon.com//AmazonS3/latest/userguide/Versioning.html)할 수 있습니다. Amazon S3 버킷에 파일을 백업하는 방법에 대한 자세한 내용은 *[Amazon S3 개발자 안내서](https://docs.aws.amazon.com//aws-backup/latest/devguide/recovery-points.html)*를 참조하세요. + 로그 항목을 보도록 AWS IoT 로깅을 구성합니다. CloudWatch에서 계정의 AWS IoT 로그를 확인할 수 있도록 AWS IoT 로깅을 구성하는 것이 좋습니다. 규칙의 SQL 쿼리가 외부 함수를 호출하면 AWS IoT Core 규칙은 실패 문제를 해결하는 데 도움이 `FunctionExecution`되는 이유 필드가 포함된 `eventType`의를 사용하여 로그 항목을 생성합니다. 발생할 수 있는 오류에는 Amazon S3 객체를 찾을 수 없거나 protobuf 파일 설명자가 잘못된 것 등이 포함됩니다. AWS IoT 로깅을 구성하고 로그 항목을 확인하는 방법에 대한 자세한 내용은 [AWS IoT 로깅 구성](https://docs.aws.amazon.com//iot/latest/developerguide/configure-logging.html) 및 [규칙 엔진 로그 항목](https://docs.aws.amazon.com//iot/latest/developerguide/cwl-format.html#log-rules-fn-exec)을 참조하세요. + 새 객체 키를 사용하여 `FileDescriptorSet`를 업데이트하고 규칙에서 객체 키를 업데이트합니다. 업데이트된 설명자 파일을 Amazon S3 버킷에 업로드하여 `FileDescriptorSet`를 업데이트할 수 있습니다. `FileDescriptorSet`에 대한 업데이트 내용이 반영되는 데 최대 15분이 걸릴 수 있습니다. 이러한 지연을 피하려면 새 객체 키를 사용하여 업데이트된 `FileDescriptorSet`를 업로드하고 규칙에서 객체 키를 업데이트하는 것이 좋습니다.