翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # バイナリペイロードの使用 メッセージのペイロードを raw バイナリデータとして (JSON オブジェクトではなく) 処理するには、\$1 演算子を使用して SELECT 句で参照できます。 **Topics** + [ ## バイナリペイロードの例 ](#binary-payloads-examples) + [ ## protobuf メッセージペイロードのデコード ](#binary-payloads-protobuf) ## バイナリペイロードの例 メッセージペイロードを raw バイナリデータとして参照するために \$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 ルールは、[decode(value, 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`) は `.proto` ファイルのコンパイル版で、protobuf のシリアル化で使用されるデータ構造とメッセージタイプを定義するテキストファイルです。記述子ファイルを生成するには、`.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、E メール) を指定します。`.proto` ファイルメッセージ形式の詳細については、[言語ガイド (proto3)](https://developers.google.com/protocol-buffers/docs/proto3)を参照してください。 1. [protoc](https://github.com/protocolbuffers/protobuf/releases) コンパイラを使用して、`.proto` ファイルをコンパイルし、記述子ファイルを生成します。descriptor (`.desc`) ファイルを作成するコマンドの例として、次のものがあります。 ``` protoc --descriptor_set_out=.desc \ --proto_path= \ --include_imports \ .proto ``` このコマンド例では、記述子ファイル を生成します。このファイル を使用して`.desc`、 AWS IoT Core で定義されたデータ構造に準拠する protobuf ペイロードをデコードできます`.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 バケットにアップロードする 記述子ファイル を作成したら`.desc`、 AWS API、 AWS SDK、または を使用して、記述子ファイルを `.desc` Amazon S3 バケットにアップロードします AWS マネジメントコンソール。 **重要な考慮事項** + ルールを設定する AWS リージョン のと同じ AWS アカウント の Amazon S3 バケットに記述子ファイルをアップロードしてください。 + S3 `FileDescriptorSet`から を読み取る AWS IoT Core ためのアクセス許可を必ず付与してください。S3 バケットでサーバー側の暗号化が無効になっている場合、または 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 デコードを設定する 記述子ファイルを 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 メッセージペイロードをデコードする場合、1 つの SQL 式内で [decode SQL 関数](iot-sql-functions.md#iot-sql-decode-base64)を最大 2 回使用できます。 + インバウンドペイロードの最大サイズは 128 KiB (1KiB = 1024 バイト)、アウトバウンドペイロードの最大サイズは 128 KiB、Amazon S3 バケットに保存される `FileDescriptorSet` オブジェクトの最大サイズは 32 KiB です。 + 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 Rules は `eventType`の を持つログエントリを生成します。これには`FunctionExecution`、障害のトラブルシューティングに役立つ理由フィールドが含まれます。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` をアップロードし、ルール内のオブジェクトキーを更新することをお勧めします。